@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 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}.
@end example
The result is not @samp{("" "two" "words" "")}, which would rarely be
-useful. If you need such a result, use an explict value for
+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{@samp{"[ \f\t\n\r\v]+"}}.
@end defvar
@node Modifying Strings
@code{clear-string}:
@defun clear-string string
-This clears the contents of @var{string} to zeros
-and may change its length.
+This clears the contents of @var{string} to zeros.
+It may also change @var{string}'s length and convert it to
+a unibyte string.
@end defun
@need 2000
This function works like @code{assoc}, except that @var{key} must be a
string, and comparison is done using @code{compare-strings}. If
@var{case-fold} is non-@code{nil}, it ignores case differences.
+Unlike @code{assoc}, this function can also match elements of the alist
+that are strings rather than conses. In particular, @var{alist} can
+be a list of strings rather than an actual alist.
@xref{Association Lists}.
@end defun
@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
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; if they have text properties,
+these are copied into the output also.
@end defun
@cindex @samp{%} in format
@var{objects}. Thus, the first format specification in @var{string}
uses the first such value, the second format specification uses the
second such value, and so on. Any extra format specifications (those
-for which there are no corresponding values) cause unpredictable
-behavior. Any extra values to be formatted are ignored.
+for which there are no corresponding values) cause an error. Any
+extra values to be formatted are ignored.
Certain format specifications require values of particular types. If
you supply a value that doesn't fit the requirements, an error is
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.
@end group
@end example
-@cindex numeric prefix
@cindex field width
@cindex padding
- All the specification characters allow an optional numeric prefix
-between the @samp{%} and the character. The optional numeric prefix
-defines the minimum width for the object. If the printed
-representation of the object contains fewer characters than this, then
-it is padded. The padding is on the left if the prefix is positive
-(or starts with zero) and on the right if the prefix is negative. The
-padding character is normally a space, but if the numeric prefix
-starts with a zero, zeros are used for padding. Some of these
-conventions are ignored for specification characters for which they do
-not make sense. That is, %s, %S and %c accept a numeric prefix
-starting with 0, but still pad with @emph{spaces} on the left. Also,
-%% accepts a numeric prefix, but ignores it. Here are some examples
-of padding:
+ 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
+width is positive (or starts with zero) and on the right if the
+width is negative. The padding character is normally a space, but if
+the width starts with a zero, zeros are used for padding. Some of
+these conventions are ignored for specification characters for which
+they do not make sense. That is, @samp{%s}, @samp{%S} and @samp{%c}
+accept a width starting with 0, but still pad with @emph{spaces} on
+the left. Also, @samp{%%} accepts a width, but ignores it. Here are
+some examples of padding:
@example
(format "%06d is padded on the left with zeros" 123)
@result{} "123 is padded on the right"
@end example
- @code{format} never truncates an object's printed representation, no
-matter what width you specify. Thus, you can use a numeric prefix to
-specify a minimum spacing between columns with no risk of losing
-information.
+If the width is too small, @code{format} does not truncate the
+object's printed representation. Thus, you can use a width to specify
+a minimum spacing between columns with no risk of losing information.
In the following three examples, @samp{%7s} specifies a minimum width
of 7. In the first case, the string inserted in place of @samp{%7s} has
@end group
@end smallexample
+@cindex precision in format specifications
+ All the specification characters allow an optional ``precision''
+before the character (after the width, if present). The precision is
+a decimal-point @samp{.} followed by a digit-string. For the
+floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the
+precision specifies how many decimal places to show; if zero, the
+decimal-point itself is also omitted. For @samp{%s} and @samp{%S},
+the precision truncates the string to the given width, so
+@samp{%.3s} shows only the first three characters of the
+representation for @var{object}. Precision is ignored for other
+specification characters.
+
+@cindex flags in format specifications
+Immediately after the @samp{%} and before the optional width and
+precision, you can put certain ``flag'' characters.
+
+A space character inserts a space for positive numbers (otherwise
+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
+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
+precision is zero.
+
@node Case Conversion
@comment node-name, next, previous, up
@section Case Conversion in Lisp
canonical equivalent character (which should be either @samp{a} for both
of them, or @samp{A} for both of them).
- The extra table @var{equivalences} is a map that cyclicly permutes
+ The extra table @var{equivalences} is a map that cyclically permutes
each equivalence class (of characters with the same canonical
equivalent). (For ordinary @acronym{ASCII}, this would map @samp{a} into
@samp{A} and @samp{A} into @samp{a}, and likewise for each set of