Commit 728345f8 authored by Jonathan Yavner's avatar Jonathan Yavner

For `format', make source and documentation match.

parent 2528f9c4
......@@ -798,19 +798,18 @@ operation} error.
@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
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
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 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, %s, %S and %c accept a width
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:
%% accepts a width, but ignores it. Here are some examples of
padding:
@example
(format "%06d is padded on the left with zeros" 123)
......@@ -820,10 +819,9 @@ of padding:
@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
......@@ -851,6 +849,28 @@ not truncated. In the third case, the padding is on the right.
@end group
@end smallexample
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 (%e, %f, %g), the precision specifies
how many decimal places to show; if zero, the decimal-point itself is
also omitted. For %s and %S, the precision truncates the string to
the given width, so @code{"%.3s"} shows only the first three
characters of the representation for @var{object}. Precision is
ignored for other specification characters.
Immediately after the % and before the optional width and precision,
you can put certain ``flag'' characters.
A space @var{" "} inserts a space for positive numbers (otherwise
nothing is inserted for positive numbers). This flag is ignored
except for %d, %e, %f, %g.
The flag @var{"#"} indicates ``alternate form''. For %o it ensures
that the result begins with a 0. For %x and %X the result is prefixed
with ``0x'' or ``0X''. For %e, %f, and %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
......
......@@ -3193,6 +3193,10 @@ It may contain %-sequences meaning to substitute the next argument.
The argument used for %d, %o, %x, %e, %f, %g or %c must be a number.
Use %% to put a single % into the output.
The basic structure of a %-sequence is
% <flags> <width> <precision> character
where flags is [- #0]+, width is [0-9]+, and precision is .[0-9]+
usage: (format STRING &rest OBJECTS) */)
(nargs, args)
int nargs;
......@@ -3300,7 +3304,7 @@ usage: (format STRING &rest OBJECTS) */)
where
flags ::= [#-* 0]+
flags ::= [- #0]+
field-width ::= [0-9]+
precision ::= '.' [0-9]*
......@@ -3312,14 +3316,7 @@ usage: (format STRING &rest OBJECTS) */)
digits to print after the '.' for floats, or the max.
number of chars to print from a string. */
/* NOTE the handling of specifiers here differs in some ways
from the libc model. There are bugs in this code that lead
to incorrect formatting when flags recognized by C but
neither parsed nor rejected here are used. Further
revisions will be made soon. */
/* incorrect list of flags to skip; will be fixed */
while (index ("-*# 0", *format))
while (index ("-0# ", *format))
++format;
if (*format >= '0' && *format <= '9')
......@@ -3403,7 +3400,7 @@ usage: (format STRING &rest OBJECTS) */)
if (*format == 'c')
{
if (! SINGLE_BYTE_CHAR_P (XINT (args[n]))
/* Note: No one can remeber why we have to treat
/* Note: No one can remember why we have to treat
the character 0 as a multibyte character here.
But, until it causes a real problem, let's
don't change it. */
......@@ -3494,17 +3491,19 @@ usage: (format STRING &rest OBJECTS) */)
discarded[format - format_start] = 1;
format++;
/* Process a numeric arg and skip it. */
/* NOTE atoi is the wrong thing to use here; will be fixed */
while (index("-0# ", *format))
{
if (*format == '-')
{
negative = 1;
}
discarded[format - format_start] = 1;
++format;
}
minlen = atoi (format);
if (minlen < 0)
minlen = - minlen, negative = 1;
/* NOTE the parsing here is not consistent with the first
pass, and neither attempt is what we want to do. Will be
fixed. */
while ((*format >= '0' && *format <= '9')
|| *format == '-' || *format == ' ' || *format == '.')
while ((*format >= '0' && *format <= '9') || *format == '.')
{
discarded[format - format_start] = 1;
format++;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment