Bug 15227 – std.format undocumented grammar

I don't see anywhere in the documentation of std.format including the grammar of a format specifier for the following that appears to be implemented around line 1000: - positional argument of the forms %m:n$ and %m:$ - digits and '$' following a '*' for positional width - digits and '$' following '.*' for positional precision Further, while the documentation for arrays (compound format) and the various output is pretty good, I don't see many examples of the other sorts of formats. There does appear to be many undocumented unit tests scattered throughout the 6700 line module, so maybe some of them can be used. Particularly, there appears to be a fairly comprehensive one at line 6226. I suppose a certain familiarity with printf may be assumed here, but of course, this isn't exactly printf.

The code seems to have been added by Andrei Alexandrescu himself back in 2011: https://github.com/D-Programming-Language/phobos/commit/e068168273e4200bbf0c44e5ebba6a697a714b97 https://issues.dlang.org/show_bug.cgi?id=3479 CCing our diligent documentation writers.

In addition to the above problems, the examples in text should be moved to unit test examples.

In addition to the undocumented syntax I've further noticed: - grammar for 'Integer' technically allows leading 0's and disallows negative integers - 'Integer' is used in the grammar for both non-negative (Position) and negative (Width, Precision) purposes - the 'r' (raw) and 'u' (unsigned) format spec characters are not documented anywhere (neither in the grammar or the rest of the text) That last bullet is probably more important than any other. Caveat on the original issue: there is indeed a hyperlink very early on in the formattedWrite documentation, which goes to an external page that does explain the positional syntax/semantics: "%n$" and "*m$" but not the forms involving ':' Incidentally, that page (2004 edition) indicates a newer version is available: http://pubs.opengroup.org/onlinepubs/9699919799/ (2013 edition). However, it doesn't appear to have anything new regarding positional notation. Related question: is there a reason, or should std.format support the 'i', 'p', or 'n' format spec characters from the *printf family of functions?

Correction: the 2013 edition link should be: http://pubs.opengroup.org/onlinepubs/9699919799/functions/printf.html

@berni44 created dlang/phobos pull request #7927 "Fix Issue 15227 - std.format undocumented grammar" fixing this issue: - Fix Issue 15227 - std.format undocumented grammar https://github.com/dlang/phobos/pull/7927

dlang/phobos pull request #7927 "Fix Issue 15227 - std.format undocumented grammar" was merged into master: - d5cb431b70935a87b926dd7db3fe2241e6300331 by berni44: Fix Issue 15227 - std.format undocumented grammar https://github.com/dlang/phobos/pull/7927