From c331f393c120208983a4c9890cfd606635ef782a Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 28 Jan 2017 10:30:17 +0200 Subject: [PATCH] Improve documentation of 'format' conversions * 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) --- doc/lispref/strings.texi | 32 ++++++++++++++++++++------------ src/editfns.c | 24 +++++++++++++++--------- 2 files changed, 35 insertions(+), 21 deletions(-) diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index d343bcf5eff..d5980f62bd4 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -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} diff --git a/src/editfns.c b/src/editfns.c index 395b3f3faed..18384a7d03a 100644 --- a/src/editfns.c +++ b/src/editfns.c @@ -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) -- 2.39.5