* Re: doc string of `format' - FLAGS unexplained [not found] <003c01c8767e$115f1520$0600a8c0@us.oracle.com> @ 2008-02-25 23:13 ` Chong Yidong 2008-02-25 23:27 ` Andreas Schwab 2008-02-26 0:05 ` Lennart Borgman (gmail) 0 siblings, 2 replies; 6+ messages in thread From: Chong Yidong @ 2008-02-25 23:13 UTC (permalink / raw) To: emacs-devel "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) ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: doc string of `format' - FLAGS unexplained 2008-02-25 23:13 ` doc string of `format' - FLAGS unexplained Chong Yidong @ 2008-02-25 23:27 ` Andreas Schwab 2008-02-26 0:23 ` Chong Yidong 2008-02-26 0:05 ` Lennart Borgman (gmail) 1 sibling, 1 reply; 6+ messages in thread From: Andreas Schwab @ 2008-02-25 23:27 UTC (permalink / raw) To: Chong Yidong; +Cc: emacs-devel Chong Yidong <cyd@stupidchicken.com> writes: > 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. This is wrong. '-' and '0' are real flags that can be freely mixed with other flags, eg. "%0#10d" is valid and the same as "%#010d". They are never considered part of the width. Andreas. -- Andreas Schwab, SuSE Labs, schwab@suse.de SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany PGP key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different." ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: doc string of `format' - FLAGS unexplained 2008-02-25 23:27 ` Andreas Schwab @ 2008-02-26 0:23 ` Chong Yidong 2008-02-26 12:07 ` Andreas Schwab 0 siblings, 1 reply; 6+ messages in thread From: Chong Yidong @ 2008-02-26 0:23 UTC (permalink / raw) To: Andreas Schwab; +Cc: emacs-devel Andreas Schwab <schwab@suse.de> writes: > Chong Yidong <cyd@stupidchicken.com> writes: > >> 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. > > This is wrong. '-' and '0' are real flags that can be freely mixed with > other flags, eg. "%0#10d" is valid and the same as "%#010d". They are > never considered part of the width. The question is, do we regard this as an undocumented side-effect of the implementation? Treating '-' and '0' as part of the width specifier is conceptually simpler, and the elisp manual documents these as such. If we treat '0' as a real flag, then maybe the description in the elisp manual should be revised. ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: doc string of `format' - FLAGS unexplained 2008-02-26 0:23 ` Chong Yidong @ 2008-02-26 12:07 ` Andreas Schwab 2008-02-26 16:33 ` Chong Yidong 0 siblings, 1 reply; 6+ messages in thread From: Andreas Schwab @ 2008-02-26 12:07 UTC (permalink / raw) To: Chong Yidong; +Cc: emacs-devel Chong Yidong <cyd@stupidchicken.com> writes: > Andreas Schwab <schwab@suse.de> writes: > >> Chong Yidong <cyd@stupidchicken.com> writes: >> >>> 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. >> >> This is wrong. '-' and '0' are real flags that can be freely mixed with >> other flags, eg. "%0#10d" is valid and the same as "%#010d". They are >> never considered part of the width. > > The question is, do we regard this as an undocumented side-effect of > the implementation? It works the same as in C, which is widely understood. Gratuitous differences only confuse people. Andreas. -- Andreas Schwab, SuSE Labs, schwab@suse.de SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany PGP key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different." ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: doc string of `format' - FLAGS unexplained 2008-02-26 12:07 ` Andreas Schwab @ 2008-02-26 16:33 ` Chong Yidong 0 siblings, 0 replies; 6+ messages in thread From: Chong Yidong @ 2008-02-26 16:33 UTC (permalink / raw) To: Andreas Schwab; +Cc: emacs-devel Andreas Schwab <schwab@suse.de> writes: > Chong Yidong <cyd@stupidchicken.com> writes: > >> Andreas Schwab <schwab@suse.de> writes: >> >>> Chong Yidong <cyd@stupidchicken.com> writes: >>> >>>> 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. >>> >>> This is wrong. '-' and '0' are real flags that can be freely mixed with >>> other flags, eg. "%0#10d" is valid and the same as "%#010d". They are >>> never considered part of the width. >> >> The question is, do we regard this as an undocumented side-effect of >> the implementation? > > It works the same as in C, which is widely understood. Gratuitous > differences only confuse people. True enough. I've checked in a corrected docstring that treats - and 0 as flags. ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: doc string of `format' - FLAGS unexplained 2008-02-25 23:13 ` doc string of `format' - FLAGS unexplained Chong Yidong 2008-02-25 23:27 ` Andreas Schwab @ 2008-02-26 0:05 ` Lennart Borgman (gmail) 1 sibling, 0 replies; 6+ messages in thread From: Lennart Borgman (gmail) @ 2008-02-26 0:05 UTC (permalink / raw) To: Chong Yidong; +Cc: emacs-devel Chong Yidong wrote: > 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? How nice with a readable description of those formats. But > ! %<flags><width><precision>character > ! > ! where flags is [+ #]+, width is [0-9]+, and precision is .[0-9]+ ! where <flags> is [+ #0]+, width is [1-9][0-9]*, and precision is .[0-9]+ is perhaps more accurate. `0' is a flag that gives leading 0:s, isn't it? And perhaps is it more logical to write <flags> then just flags? ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2008-02-26 16:33 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <003c01c8767e$115f1520$0600a8c0@us.oracle.com> 2008-02-25 23:13 ` doc string of `format' - FLAGS unexplained Chong Yidong 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)
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).