@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
an error if @var{obj} doesn't fit within @var{string}'s actual length,
or if any new character requires a different number of bytes from the
character currently present at that point in @var{string}.
+@end defun
+
+ To clear out a string that contained a password, use
+@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.
@end defun
@need 2000
strings. When @code{equal} (@pxref{Equality Predicates}) compares two
strings, it uses @code{string=}.
-If the strings contain non-@acronym{ASCII} characters, and one is unibyte
-while the other is multibyte, then they cannot be equal. @xref{Text
+For technical reasons, a unibyte and a multibyte string are
+@code{equal} if and only if they contain the same sequence of
+character codes and all these codes are either in the range 0 through
+127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
+However, when a unibyte string gets converted to a multibyte string,
+all characters with codes in the range 160 through 255 get converted
+to characters with higher codes, whereas @acronym{ASCII} characters
+remain unchanged. Thus, a unibyte string and its conversion to
+multibyte are only @code{equal} if the string is all @acronym{ASCII}.
+Character codes 160 through 255 are not entirely proper in multibyte
+text, even though they can occur. As a consequence, the situation
+where a unibyte and a multibyte string are @code{equal} without both
+being all @acronym{ASCII} is a technical oddity that very few Emacs
+Lisp programmers ever get confronted with. @xref{Text
Representations}.
@end defun
the string).
The strings are both converted to multibyte for the comparison
-(@pxref{Text Representations}) so that a unibyte string can be equal to
-a multibyte string. If @var{ignore-case} is non-@code{nil}, then case
-is ignored, so that upper case letters can be equal to lower case letters.
+(@pxref{Text Representations}) so that a unibyte string and its
+conversion to multibyte are always regarded as equal. If
+@var{ignore-case} is non-@code{nil}, then case is ignored, so that
+upper case letters can be equal to lower case letters.
If the specified portions of the two strings match, the value is
@code{t}. Otherwise, the value is an integer which indicates how many
portion) is less.
@end defun
-@defun assoc-ignore-case key alist
+@defun assoc-string key alist &optional case-fold
This function works like @code{assoc}, except that @var{key} must be a
-string, and comparison is done using @code{compare-strings}, ignoring
-case differences. @xref{Association Lists}.
-@end defun
-
-@defun assoc-ignore-representation key alist
-This function works like @code{assoc}, except that @var{key} must be a
-string, and comparison is done using @code{compare-strings}.
-Case differences are significant.
+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
See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
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
HCoop / bpt / emacs.git / blobdiff