procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of 'format' conversions

Browse source 
* src/editfns.c (Fformat): More accurate description of %g and
effects of the various flags on it.  More accurate description of
integer conversions.

* doc/lispref/strings.texi (Formatting Strings): More accurate
description of %g and effects of the various flags on it.  More
accurate description of integer conversions.  (Bug#25557)
This commit is contained in:
Eli Zaretskii 2017-01-28 10:30:17 +02:00
parent 9f52f67a96
commit c331f393c1
2 changed files with 35 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
doc/lispref/strings.texi
View file

@ -893,17 +893,18 @@ Functions}). Thus, strings are enclosed in @samp{"} characters, and
@item %o
@cindex integer to octal
Replace the specification with the base-eight representation of an
integer.
unsigned integer.
@item %d
Replace the specification with the base-ten representation of an
Replace the specification with the base-ten representation of a signed
integer.
@item %x
@itemx %X
@cindex integer to hexadecimal
Replace the specification with the base-sixteen representation of an
integer. @samp{%x} uses lower case and @samp{%X} uses upper case.
unsigned integer. @samp{%x} uses lower case and @samp{%X} uses upper
case.
@item %c
Replace the specification with the character which is the value given.
@ -918,8 +919,9 @@ floating-point number.
@item %g
Replace the specification with notation for a floating-point number,
using either exponential notation or decimal-point notation, whichever
is shorter.
using either exponential notation or decimal-point notation. The
exponential notation is used if the exponent would be less than -4 or
greater than or equal to the precision (default: 6).
@item %%
Replace the specification with a single @samp{%}. This format
@ -1000,9 +1002,11 @@ both flags are used, @samp{+} takes precedence.
The flag @samp{#} specifies an alternate form which depends on
the format in use. For @samp{%o}, it ensures that the result begins
with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result
with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g},
the @samp{#} flag means include a decimal point even if the precision
is zero.
with @samp{0x} or @samp{0X}. For @samp{%e} and @samp{%f}, the
@samp{#} flag means include a decimal point even if the precision is
zero. For @samp{%g}, it always includes a decimal point, and also
forces any trailing zeros after the decimal point to be left in place
where they would otherwise be removed.
The flag @samp{0} ensures that the padding consists of @samp{0}
characters instead of spaces. This flag is ignored for non-numerical
@ -1033,10 +1037,14 @@ ignored.
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
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}
floating-point specifications (@samp{%e} and @samp{%f}), the
precision specifies how many digits following the decimal point to
show; if zero, the decimal-point itself is also omitted. For
@samp{%g}, the precision specifies how many significant digits to show
(significant digits are the first digit before the decimal point and
all the digits after it). If the precision of %g is zero or
unspecified, it is treated as 1. 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}. For other specification characters, the effect of
precision is what the local library functions of the @code{printf}

24
src/editfns.c
View file

@ -3823,12 +3823,14 @@ The format control string may contain %-sequences meaning to substitute
the next available argument:
%s means print a string argument. Actually, prints any object, with `princ'.
%d means print as number in decimal (%o octal, %x hex).
%d means print as signed number in decimal.
%o means print as unsigned number in octal, %x as unsigned number in hex.
%X is like %x, but uses upper case.
%e means print a number in exponential notation.
%f means print a number in decimal-point notation.
%g means print a number in exponential notation
or decimal-point notation, whichever uses fewer characters.
%g means print a number in exponential notation if the exponent would be
less than -4 or greater than or equal to the precision (default: 6);
otherwise it prints in decimal-point notation.
%c means print a number as a single character.
%S means print any object as an s-expression (using `prin1').
@ -3851,8 +3853,10 @@ The - and 0 flags affect the width specifier, as described below.
The # flag means to use an alternate display form for %o, %x, %X, %e,
%f, and %g sequences: for %o, it ensures that the result begins with
\"0\"; for %x and %X, it prefixes the result with \"0x\" or \"0X\";
for %e, %f, and %g, it causes a decimal point to be included even if
the precision is zero.
for %e and %f, it causes a decimal point to be included even if the
the precision is zero; for %g, it causes a decimal point to be
included even if the the precision is zero, and also forces trailing
zeros after the decimal point to be left in place.
The width specifier supplies a lower limit for the length of the
printed representation. The padding, if any, normally goes on the
@ -3861,10 +3865,12 @@ character is normally a space, but it is 0 if the 0 flag is present.
The 0 flag is ignored if the - flag is present, or the format sequence
is something other than %d, %e, %f, and %g.
For %e, %f, and %g sequences, the number after the "." in the
precision specifier says how many decimal places to show; if zero, the
decimal point itself is omitted. For %s and %S, the precision
specifier truncates the string to the given width.
For %e and %f sequences, the number after the "." in the precision
specifier says how many decimal places to show; if zero, the decimal
point itself is omitted. For %g, the precision specifies how many
significant digits to print; zero or omitted are treated as 1.
For %s and %S, the precision specifier truncates the string to the
given width.
usage: (format STRING &rest OBJECTS) */)
(ptrdiff_t nargs, Lisp_Object *args)