diff options
Diffstat (limited to 'doc/lispref/strings.texi')
| -rw-r--r-- | doc/lispref/strings.texi | 69 |
1 files changed, 20 insertions, 49 deletions
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 8de1473b83d..580eb43acca 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -805,27 +805,22 @@ formatting feature described here; they differ from @code{format} only in how they use the result of formatting. @defun format string &rest objects -This function returns a string that is equivalent to copying +This function returns a new string that is made by copying @var{string} and then replacing any format specification in the copy with encodings of the corresponding @var{objects}. The 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, including their text properties, -if any. If the output equals @var{string}, this function may return -@var{string} itself rather than a new copy. +if any. @end defun @cindex @samp{%} in format @cindex format specification -@cindex curved quotes -@cindex curly quotes A format specification is a sequence of characters beginning with a -@samp{%} or is a curved single quotation mark. Except for @samp{%%} -and quotation marks, each format specification says how to represent -one of the arguments @var{objects}. For example, if there -is a @samp{%d} in @var{string}, the @code{format} function replaces it -with the decimal representation of the integer to be formatted. +@samp{%}. Thus, if there is a @samp{%d} in @var{string}, the +@code{format} function replaces it with the printed representation of +one of the values to be formatted (one of the arguments @var{objects}). For example: @example @@ -835,12 +830,11 @@ For example: @end group @end example - Since @code{format} interprets @samp{%}, @samp{‘} and @samp{’} -characters as format + 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 of the three special characters, pass @code{"%s"}, described +never include any @samp{%} characters, pass @code{"%s"}, described below, as the first argument, and the string as the second, like this: @example @@ -914,27 +908,17 @@ is shorter. Replace the specification with a single @samp{%}. This format specification is unusual in that it does not use a value. For example, @code{(format "%% %d" 30)} returns @code{"% 30"}. - -@item ‘ -@itemx ’ -@cindex curved quotes -@cindex curly quotes -Replace the specification with a left or right quote, respectively. -Although typically a curved single quotation mark stands for itself, -other quoting styles are available as per the variable -@samp{text-quoting-style} described below. @end table - Any other format character after @samp{%} results in an @samp{Invalid format + Any other format character results in an @samp{Invalid format operation} error. - Here are several examples, which assume the typical quoting style -where curved single quotes stand for themselves: + Here are several examples: @example @group -(format "The name of this buffer is ‘%s’." (buffer-name)) - @result{} "The name of this buffer is ‘strings.texi’." +(format "The name of this buffer is %s." (buffer-name)) + @result{} "The name of this buffer is strings.texi." (format "The buffer object prints as %qs." (current-buffer)) @result{} "The buffer object prints as ‘strings.texi’." @@ -948,7 +932,7 @@ where curved single quotes stand for themselves: @cindex field width @cindex padding - A @samp{%} specification can have a @dfn{width}, which is a decimal number + A specification can have a @dfn{width}, which is a decimal number between the @samp{%} and the specification character. If the printed representation of the object contains fewer characters than this width, @code{format} extends it with padding. The width specifier is @@ -964,7 +948,7 @@ the width specifier normally consists of spaces inserted on the left: 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 two examples, @samp{%7s} specifies a minimum width +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 only 3 letters, and needs 4 blank spaces as padding. In the second case, the string @code{"specification"} is 13 letters wide but @@ -972,12 +956,12 @@ is not truncated. @example @group -(format "The word ‘%7s’ has %d letters in it." +(format "The word '%7s' has %d letters in it." "foo" (length "foo")) - @result{} "The word ‘ foo’ has 3 letters in it." -(format "The word ‘%7s’ has %d letters in it." + @result{} "The word ' foo' has 3 letters in it." +(format "The word '%7s' has %d letters in it." "specification" (length "specification")) - @result{} "The word ‘specification’ has 13 letters in it." + @result{} "The word 'specification' has 13 letters in it." @end group @end example @@ -1022,14 +1006,14 @@ variable @samp{text-quoting-style} described below. (format "%q-6d is padded on the right" 123) @result{} "‘123 ’ is padded on the right" -(format "The word ‘%-7s’ actually has %d letters in it." +(format "The word '%-7s' actually has %d letters in it." "foo" (length "foo")) - @result{} "The word ‘foo ’ actually has 3 letters in it." + @result{} "The word 'foo ' actually has 3 letters in it." @end group @end example @cindex precision in format specifications - The @samp{%} specification characters allow an optional @dfn{precision} + All the specification characters allow an optional @dfn{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 @@ -1040,19 +1024,6 @@ shows only the first three characters of the representation for @var{object}. Precision has no effect for other specification characters. -@defvar text-quoting-style -@cindex curved quotes -@cindex curly quotes -This variable specifies the style @code{format} uses when generating -left and right quotes. If the value is @code{curve}, the style is -@t{‘like this’} with curved single quotes. If the value is -@code{straight}, the style is @t{'like this'} with straight -apostrophes. If the value is @code{grave}, the style is @t{`like -this'} with grave accent and apostrophe. The default value @code{nil} -acts like @code{curve} if curved single quotes are displayable, and -like @code{grave} otherwise. -@end defvar - @node Case Conversion @section Case Conversion in Lisp @cindex upper case |