@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
-@c 2004, 2005, 2006 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/strings
@node Strings and Characters, Lists, Numbers, Top
@code{clear-string}:
@defun clear-string string
-This clears the contents of @var{string} to zeros.
-It may also change @var{string}'s length and convert it to
-a unibyte string.
+This makes @var{string} a unibyte string and clears its contents to
+zeros. It may also change @var{string}'s length.
@end defun
@need 2000
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; 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}
@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