@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/strings
@node Strings and Characters, Lists, Numbers, Top
and other modifiers for keyboard input characters.
Strings are useful for holding regular expressions. You can also
-match regular expressions against strings (@pxref{Regexp Search}). The
-functions @code{match-string} (@pxref{Simple Match Data}) and
-@code{replace-match} (@pxref{Replacing Match}) are useful for
-decomposing and modifying strings based on regular expression matching.
+match regular expressions against strings with @code{string-match}
+(@pxref{Regexp Search}). The functions @code{match-string}
+(@pxref{Simple Match Data}) and @code{replace-match} (@pxref{Replacing
+Match}) are useful for decomposing and modifying strings after
+matching regular expressions against them.
Like a buffer, a string can contain text properties for the characters
in it, as well as the characters themselves. @xref{Text Properties}.
otherwise.
@end defun
+@defun string-or-null-p object
+This function returns @code{t} if @var{object} is a string or nil,
+@code{nil} otherwise.
+@end defun
+
@defun char-or-string-p object
This function returns @code{t} if @var{object} is a string or a
character (i.e., an integer), @code{nil} otherwise.
whenever there are two consecutive matches for @var{separators}, or a
match is adjacent to the beginning or end of @var{string}. If
@var{omit-nulls} is @code{t}, these null strings are omitted from the
-result list.
+result.
If @var{separators} is @code{nil} (or omitted),
the default is the value of @code{split-string-default-separators}.
@result{} ("two" "words")
@end example
-The result is not @samp{("" "two" "words" "")}, which would rarely be
+The result is not @code{("" "two" "words" "")}, which would rarely be
useful. If you need such a result, use an explicit value for
@var{separators}:
@example
-(split-string " two words " split-string-default-separators)
+(split-string " two words "
+ split-string-default-separators)
@result{} ("" "two" "words" "")
@end example
@end defun
@defvar split-string-default-separators
-The default value of @var{separators} for @code{split-string}, initially
-@w{@samp{"[ \f\t\n\r\v]+"}}.
+The default value of @var{separators} for @code{split-string}. Its
+usual value is @w{@code{"[ \f\t\n\r\v]+"}}.
@end defvar
@node Modifying Strings
@xref{Association Lists}.
@end defun
- See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
-a way to compare text in buffers. The function @code{string-match},
-which matches a regular expression against a string, can be used
-for a kind of string comparison; see @ref{Regexp Search}.
+ See also the @code{compare-buffer-substrings} function in
+@ref{Comparing Text}, for a way to compare text in buffers. The
+function @code{string-match}, which matches a regular expression
+against a string, can be used for a kind of string comparison; see
+@ref{Regexp Search}.
@node String Conversion
@comment node-name, next, previous, up
@cindex conversion of strings
This section describes functions for conversions between characters,
-strings and integers. @code{format} and @code{prin1-to-string}
+strings and integers. @code{format} (@pxref{Formatting Strings})
+and @code{prin1-to-string}
(@pxref{Output Functions}) can also convert Lisp objects into strings.
@code{read-from-string} (@pxref{Input Functions}) can ``convert'' a
string representation of a Lisp object into an object. The functions
@xref{Documentation}, for functions that produce textual descriptions
of text characters and general input events
(@code{single-key-description} and @code{text-char-description}). These
-functions are used primarily for making help messages.
+are used primarily for making help messages.
@defun char-to-string character
@cindex character to string
arguments @var{objects} are the computed values to be formatted.
The characters in @var{string}, other than the format specifications,
-are copied directly into the output; starting in Emacs 21, if they have
-text properties, these are copied into the output also.
+are copied directly into the output, including their text properties,
+if any.
@end defun
@cindex @samp{%} in format
@end group
@end example
+ Since @code{format} interprets @samp{%} characters as format
+specifications, you should @emph{never} pass an arbitrary string as
+the first argument. This is particularly true when the string is
+generated by some Lisp code. Unless the string is @emph{known} to
+never include any @samp{%} characters, pass @code{"%s"}, described
+below, as the first argument, and the string as the second, like this:
+
+@example
+ (format "%s" @var{arbitrary-string})
+@end example
+
If @var{string} contains more than one format specification, the
format specifications correspond to successive values from
@var{objects}. Thus, the first format specification in @var{string}
by their contents alone, with no @samp{"} characters, and symbols appear
without @samp{\} characters.
-Starting in Emacs 21, if the object is a string, its text properties are
+If the object is a string, its text properties are
copied into the output. The text properties of the @samp{%s} itself
are also copied, but those of the object take priority.
@cindex field width
@cindex padding
- All the specification characters allow an optional ``width'', which
+ All the specification characters allow an optional ``width,'' which
is a digit-string between the @samp{%} and the character. If the
printed representation of the object contains fewer characters than
this width, then it is padded. The padding is on the left if the
nothing is inserted for positive numbers). This flag is ignored
except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}.
-The flag @samp{#} indicates ``alternate form''. For @samp{%o} it
+The flag @samp{#} indicates ``alternate form.'' For @samp{%o} it
ensures that the result begins with a 0. For @samp{%x} and @samp{%X}
the result is prefixed with @samp{0x} or @samp{0X}. For @samp{%e},
@samp{%f}, and @samp{%g} a decimal point is always shown even if the