From: Chong Yidong <cyd@stupidchicken.com>
To: emacs-devel@gnu.org
Subject: Re: doc string of `format' - FLAGS unexplained
Date: Mon, 25 Feb 2008 18:13:33 -0500 [thread overview]
Message-ID: <87r6f0wrxe.fsf@stupidchicken.com> (raw)
In-Reply-To: <003c01c8767e$115f1520$0600a8c0@us.oracle.com> (Drew Adams's message of "Sat\, 23 Feb 2008 16\:42\:00 -0800")
"Drew Adams" <drew.adams@oracle.com> writes:
> The doc string includes this:
>
> The basic structure of a %-sequence is
> % <flags> <width> <precision> character
> where flags is [-+ #0]+, width is [0-9]+, and precision is .[0-9]+
>
> But there is absolutely no explanation of what FLAGS, WIDTH, and
> PRECISION mean. One might be able to guess for WIDTH and PRECISION,
> but not for FLAGS. Please include some of the explanation from the
> Elisp manual, adapting it as needed.
>
> Also, the EMACS convention for doc strings is to use uppercase: FLAGS,
> not angle brackets: <flags>.
I'd like to propose the following change to the doc string of
`format'.
In particular, the statement "flags is [-+ #0]+" is misleading; it
should be [+ #]+, since the - and 0 characters are actually used to
identify the width specifier instead.
Any thoughts?
*** emacs/src/editfns.c.~1.439.2.10.~ 2008-01-10 10:26:25.000000000 -0500
--- emacs/src/editfns.c 2008-02-25 18:12:57.000000000 -0500
***************
*** 3383,3389 ****
doc: /* Format a string out of a format-string and arguments.
The first argument is a format control string.
The other arguments are substituted into it to make the result, a string.
! It may contain %-sequences meaning to substitute the next argument.
%s means print a string argument. Actually, prints any object, with `princ'.
%d means print as number in decimal (%o octal, %x hex).
%X is like %x, but uses upper case.
--- 3383,3392 ----
doc: /* Format a string out of a format-string and arguments.
The first argument is a format control string.
The other arguments are substituted into it to make the result, a string.
!
! 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).
%X is like %x, but uses upper case.
***************
*** 3393,3404 ****
or decimal-point notation, whichever uses fewer characters.
%c means print a number as a single character.
%S means print any object as an s-expression (using `prin1').
! 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)
--- 3396,3428 ----
or decimal-point notation, whichever uses fewer characters.
%c means print a number as a single character.
%S means print any object as an s-expression (using `prin1').
!
! The argument used for %d, %o, %x, %e, %f, %g or %c must be a number.
Use %% to put a single % into the output.
! A %-sequence may contain optional flag, width, and precision
! specifiers, as follows:
!
! %<flags><width><precision>character
!
! where flags is [+ #]+, width is [0-9]+, and precision is .[0-9]+
!
! The + flag character inserts a + before any positive number, while a
! space inserts a space before any positive number; these flags only
! affect %d, %e, %f, and %g sequences, and + takes precedence if both
! flags are present. The # flag means to use an alternate display form
! for %o, %x, %X, %e, %f, and %g sequences.
!
! The width specifier supplies a lower limit for the length of the
! printed representation. The padding, if any, goes on the left if the
! width specifier is positive or starts with a 0, and on the right if it
! is negative. The padding character is normally a space, and 0 if the
! width specifier starts with the character 0.
!
! 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.
usage: (format STRING &rest OBJECTS) */)
(nargs, args)
next prev parent reply other threads:[~2008-02-25 23:13 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-02-24 0:42 doc string of `format' - FLAGS unexplained Drew Adams
2008-02-25 23:13 ` Chong Yidong [this message]
2008-02-25 23:27 ` Andreas Schwab
2008-02-26 0:23 ` Chong Yidong
2008-02-26 12:07 ` Andreas Schwab
2008-02-26 16:33 ` Chong Yidong
2008-02-26 0:05 ` Lennart Borgman (gmail)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87r6f0wrxe.fsf@stupidchicken.com \
--to=cyd@stupidchicken.com \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.