Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r57670 - trunk/libs/format/doc
From: Samuel.Krempp_at_[hidden]
Date: 2009-11-15 02:54:50

Next message: Samuel.Krempp_at_[hidden]: "[Boost-commit] svn:boost r57671 - trunk/libs/format/doc"
Previous message: xushiweizh_at_[hidden]: "[Boost-commit] svn:boost r57669 - sandbox/memory/boost/memory"

Author: samuel_krempp
Date: 2009-11-15 02:54:49 EST (Sun, 15 Nov 2009)
New Revision: 57670
URL: http://svn.boost.org/trac/boost/changeset/57670

Log:
replaced two remaining instances of brackets with pipes.
closing ticket #3577
Text files modified:
trunk/libs/format/doc/format.html | 1782 ++++++++++++++++++---------------------
1 files changed, 839 insertions(+), 943 deletions(-)

Modified: trunk/libs/format/doc/format.html
==============================================================================
--- trunk/libs/format/doc/format.html (original)
+++ trunk/libs/format/doc/format.html 2009-11-15 02:54:49 EST (Sun, 15 Nov 2009)
@@ -1,110 +1,102 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
-<html>
-<head>
- <meta http-equiv="Content-Language" content="en-us">
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
-
- <title>The Boost Format library</title>
-</head>
-
-<body bgcolor="white" text="black">
- <h1><img align="middle" alt="boost.png (6897 bytes)" height="86" src=
- "../../../boost.png" width="277">The Boost Format library</h1>
-
- The <code><a href=
- "../../../boost/format.hpp"><boost/format.hpp></a></code> format
- class provides printf-like formatting, in a type-safe manner which allows
- output of user-defined types. 
-
- <ul>
- <li>Synopsis</li>
-
- <li>How it works</li>
-
- <li>Examples</li>
-
- <li>
- Syntax
-
- <ul>
- <li><a href="#printf_directives">printf format-specification
- syntax</a></li>
-
- <li><a href="#printf_differences">Incompatibilities with
- printf</a></li>
- </ul>
- </li>
-
- <li><a href="#manipulators">Manipulators and the internal stream
- state</a></li>
-
- <li>User-defined types</li>
-
- <li>Alternatives</li>
-
- <li>Exceptions</li>
-
- <li>Performance</li>
-
- <li>Class Interface Extract</li>
-
- <li>Rationale</li>
- </ul><a name="synopsis" id="synopsis"></a>
- <hr>
-
- <h2>Synopsis</h2>
-
- A format object is constructed from a format-string, and is then given
- arguments through repeated calls to operator%. 
- Each of those arguments are then converted to strings, who are in turn
- combined into one string, according to the format-string.
-
- <blockquote>
- <pre>
-cout << boost::format("writing %1%, x=%2% : %3%-th try") % "toto" % 40.23 % 50;
- // prints "writing toto, x=40.230 : 50-th try"
-</pre>
- </blockquote><a name="how_it_works" id="how_it_works"></a>
- <hr>
-
- <h2>How it works</h2>
-
- <ol>
- <li>When you call format(s), where s is the format-string, it
- constructs an object, which parses the format string and look for all
- directives in it and prepares internal structures for the next step.</li>
-
- <li>Then, either immediately, as in
-
- <blockquote>
- <pre>
-cout << format("%2% %1%") % 36 % 77;
-</pre>
- </blockquote>or later on, as in
-
- <blockquote>
- <pre>
-format fmter("%2% %1%");
-fmter % 36; fmter % 77;
-</pre>
- </blockquote>you feed variables into the formatter. 
- those variables are dumped into an internal stream, which state is set
- according to the given formatting options in the format-string -if
- there are any-, and the format object stores the string results for the
- last step.
- </li>
-
- <li>Once all arguments have been fed you can dump the format object to a
- stream, or get its string value by using the str() member
- function, or the free function str(const format& ) in
- namespace boost. The result string stays accessible in the format
- object until another argument is passed, at which time it is
- reinitialised.
-
- <blockquote>
- <pre>
-
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+<HEAD>
+ <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
+ <TITLE>The Boost Format library</TITLE>
+ <META NAME="GENERATOR" CONTENT="OpenOffice.org 3.1 (Win32)">
+ <META NAME="CREATED" CONTENT="0;0">
+ <META NAME="CHANGEDBY" CONTENT="Samuel K">
+ <META NAME="CHANGED" CONTENT="20091115;8491800">
+ <META HTTP-EQUIV="Content-Language" CONTENT="en-us">
+ <STYLE TYPE="text/css">
+ 
+ </STYLE>
+</HEAD>
+<BODY LANG="fr-FR" TEXT="#000000" BGCOLOR="#ffffff" DIR="LTR">
+<H1><IMG SRC="../../../boost.png" NAME="images1" ALT="boost.png (6897 bytes)" ALIGN=MIDDLE WIDTH=277 HEIGHT=86 BORDER=0>The
+Boost Format library</H1>
+The <CODE><boost/format.hpp></CODE>
+format class provides printf-like formatting, in a type-safe manner
+which allows output of user-defined types.
+<UL>
+ <LI>Synopsis
+ 
+ <LI><A HREF="#how_it_works">How it
+ works</A>
+ 
+ <LI>Examples
+ 
+ <LI>Syntax
+ 
+ <UL>
+ <LI><A HREF="#printf_directives">printf
+ format-specification syntax</A>
+ 
+ <LI><A HREF="#printf_differences">Incompatibilities
+ with printf</A>
+ 
+ </UL>
+ <LI><A HREF="#manipulators">Manipulators
+ and the internal stream state</A>
+ 
+ <LI><A HREF="#user-defined">User-defined
+ types</A>
+ 
+ <LI>Alternatives
+ 
+ <LI>Exceptions
+ 
+ <LI>Performance
+ 
+ <LI><A HREF="#extract">Class Interface
+ Extract</A>
+ 
+ <LI>Rationale
+ 
+</UL>
+<HR>
+<H2>Synopsis</H2>
+A format object is constructed from a format-string, and is then
+given arguments through repeated calls to operator%. Each
+of those arguments are then converted to strings, who are in turn
+combined into one string, according to the format-string.
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">cout << boost::format("writing %1%, x=%2% : %3%-th try") % "toto" % 40.23 % 50;
+ // prints "writing toto, x=40.230 : 50-th try"</PRE>
+<HR>
+<H2>How it works</H2>
+<OL>
+ <LI>When you call format(s),
+ where s is the format-string, it constructs an object, which parses
+ the format string and look for all directives in it and prepares
+ internal structures for the next step.
+ 
+ <LI>Then, either immediately, as in
+ 
+ <PRE STYLE="margin-right: 1cm; margin-bottom: 0.5cm">cout << format("%2% %1%") % 36 % 77;</PRE>
+ or later on, as in
+ 
+ <PRE STYLE="margin-right: 1cm">format fmter("%2% %1%");
+fmter % 36; fmter % 77;</PRE>
+ you feed variables into the formatter. those variables are
+ dumped into an internal stream, which state is set according to the
+ given formatting options in the format-string -if there are any-,
+ and the format object stores the string results for the last step.
+ 
+ <LI>Once all arguments have been fed you can dump the format
+ object to a stream, or get its string value by using the str()
+ member function, or the free function str(const format& )
+ in namespace boost. The result string stays accessible in the
+ format object until another argument is passed, at which time it is
+ reinitialised.
+ 
+ <PRE STYLE="margin-right: 1cm">
// fmter was previously created and fed arguments, it can print the result :
cout << fmter ;

@@ -115,793 +107,711 @@
s = fmter.str( );

// You can also do all steps at once :
-cout << boost::format("%2% %1%") % 36 % 77;
+cout << boost::format("%2% %1%") % 36 % 77;

// using the str free function :
-string s2 = str( format("%2% %1%") % 36 % 77 );
-
-</pre>
- </blockquote>
- </li>
-
- <li>Optionnally, after step 3, you can re-use a format object and restart
- at step2 : fmter % 18 % 39; 
- to format new variables with the same format-string, saving the expensive
- processing involved at step 1.</li>
- </ol>All in all, the format class translates a format-string (with
- eventually printf-like directives) into operations on an internal stream,
- and finally returns the result of the formatting, as a string, or directly
- into an output stream. <a name="examples" id="examples"></a>
- <hr>
-
- <h2>Examples</h2>
-
- <blockquote>
- <pre>
-using namespace std;
+string s2 = str( format("%2% %1%") % 36 % 77 );
+</PRE>
+ <LI>Optionnally, after step 3, you can re-use a format object and
+ restart at step2 : fmter % 18 % 39; to format new
+ variables with the same format-string, saving the expensive
+ processing involved at step 1.
+ 
+</OL>
+All in all, the format class translates
+a format-string (with eventually printf-like directives) into
+operations on an internal stream, and finally returns the result of
+the formatting, as a string, or directly into an output stream.
+
+<HR>
+<H2>Examples</H2>
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">using namespace std;
using boost::format;
-using boost::io::group;
-</pre>
- </blockquote>
-
- <ul>
- <li>Simple output, with reordering :
-
- <blockquote>
- <pre>
-
-cout << format("%1% %2% %3% %2% %1% \n") % "11" % "22" % "333"; // 'simple' style.
-
-</pre>
- </blockquote>It prints : "11 22 333 22 11 \n"
- </li>
-
- <li>More precise formatting, with Posix-printf positional directives :
-
- <blockquote>
- <pre>
-
-cout << format("(x,y) = (%1$+5d,%2$+5d) \n") % -23 % 35; // Posix-Printf style
-
-</pre>
- </blockquote>It prints : "(x,y) = ( -23, +35) \n"
- </li>
-
- <li>classical printf directive, no reordering :
-
- <blockquote>
- <pre>
-
-cout << format("writing %s, x=%s : %d-th step \n") % "toto" % 40.23 % 50;
+using boost::io::group;</PRE>
+<UL>
+ <LI>Simple output, with reordering :
+ 
+ <PRE STYLE="margin-right: 1cm">
+cout << format("%1% %2% %3% %2% %1% \n") % "11" % "22" % "333"; // 'simple' style.
+</PRE>
+ It prints : "11 22 333 22 11 \n"
+ 
+ <LI>More precise formatting, with Posix-printf positional
+ directives :
+ 
+ <PRE STYLE="margin-right: 1cm">
+cout << format("(x,y) = (%1$+5d,%2$+5d) \n") % -23 % 35; // Posix-Printf style
+</PRE>
+ It prints : "(x,y) = ( -23, +35) \n"
+ 
+ <LI>classical printf directive, no reordering :
+ 
+ <PRE STYLE="margin-right: 1cm">
+cout << format("writing %s, x=%s : %d-th step \n") % "toto" % 40.23 % 50;
+</PRE>
+ It prints : "writing toto, x=40.23 : 50-th step \n"
+ 
+ <LI>Several ways to express the same thing :
+ 
+ <PRE STYLE="margin-right: 1cm">
+cout << format("(x,y) = (%+5d,%+5d) \n") % -23 % 35;
+cout << format("(x,y) = (%|+5|,%|+5|) \n") % -23 % 35;
+
+cout << format("(x,y) = (%1$+5d,%2$+5d) \n") % -23 % 35;
+cout << format("(x,y) = (%|1$+5|,%|2$+5|) \n") % -23 % 35;
+</PRE>
+ all those print : "(x,y) = ( -23, +35) \n"
+ 
+ <LI>Using manipulators to modify the format-string :
+ 
+ <PRE STYLE="margin-right: 1cm">
+format fmter("_%1$+5d_ %1$d \n");

-</pre>
- </blockquote>It prints : "writing toto, x=40.23 : 50-th step \n"
- </li>
-
- <li>Several ways to express the same thing :
-
- <blockquote>
- <pre>
-
-cout << format("(x,y) = (%+5d,%+5d) \n") % -23 % 35;
-cout << format("(x,y) = (%|+5|,%|+5|) \n") % -23 % 35;
-
-cout << format("(x,y) = (%1$+5d,%2$+5d) \n") % -23 % 35;
-cout << format("(x,y) = (%|1$+5|,%|2$+5|) \n") % -23 % 35;
-
-</pre>
- </blockquote>all those print : "(x,y) = ( -23, +35) \n"
- </li>
-
- <li>Using manipulators to modify the format-string :
-
- <blockquote>
- <pre>
-
-format fmter("_%1$+5d_ %1$d \n");
-
-format fmter2("_%1%_ %1% \n");
+format fmter2("_%1%_ %1% \n");
fmter2.modify_item(1, group(showpos, setw(5)) );

cout << fmter % 101 ;
cout << fmter2 % 101 ;
-
-</pre>
- </blockquote>Both print the same : "_ +101_ 101 \n"
- </li>
-
- <li>Using manipulators with arguments :
-
- <blockquote>
- <pre>
-
-cout << format("_%1%_ %1% \n") % group(showpos, setw(5), 101);
-
-</pre>
- </blockquote>The manipulators are applied at each occurence of %1%, and
- thus it prints : "_ +101_ +101 \n"
- </li>
-
- <li>New formatting feature : 'absolute tabulations', useful inside loops,
- to insure a field is printed at the same position from one line to the
- next, even if the widthes of the previous arguments can vary a lot.
-
- <blockquote>
- <pre>
-
+</PRE>
+ Both print the same : "_ +101_ 101 \n"
+ 
+ <LI>Using manipulators with arguments :
+ 
+ <PRE STYLE="margin-right: 1cm">
+cout << format("_%1%_ %1% \n") % group(showpos, setw(5), 101);
+</PRE>
+ The manipulators are applied at each occurence of %1%, and thus it
+ prints : "_ +101_ +101 \n"
+ 
+ <LI>New formatting feature : 'absolute tabulations', useful
+ inside loops, to insure a field is printed at the same position from
+ one line to the next, even if the widthes of the previous arguments
+ can vary a lot.
+ 
+ <PRE STYLE="margin-right: 1cm">
for(unsigned int i=0; i < names.size(); ++i)
- cout << format("%1%, %2%, %|40t|%3%\n") % names[i] % surname[i] % tel[i];
-
-</pre>
- </blockquote>For some std::vector names, surnames, and
- tel (see sample_new_features.cpp) it prints :
-
- <blockquote>
- <pre>
-Marc-François Michel, Durand, +33 (0) 123 456 789
-Jean, de Lattre de Tassigny, +33 (0) 987 654 321
-</pre>
- </blockquote>
- </li>
- </ul>
- <hr>
-
- <h2>Sample Files</h2>
-
- The program <a href=
- "../example/sample_formats.cpp">sample_formats.cpp</a> demonstrates simple
- uses of format. 
-
- sample_new_features.cpp
- illustrates the few formatting features that were added to printf's syntax
- such as simple positional directives, centered alignment, and
- 'tabulations'. 
-
- sample_advanced.cpp
- demonstrates uses of advanced features, like reusing, and modifying, format
- objects, etc.. 
-
- And sample_userType.cpp
- shows the behaviour of the format library on user-defined
- types.<a name="syntax" id="syntax"></a>
- <hr>
-
- <h2>Syntax</h2>
-
- boost::format( format-string ) % arg1 % arg2
- % ... % argN
-
- The format-string contains text in which special directives will
- be replaced by strings resulting from the formatting of the given
- arguments. 
- The legacy syntax in the C and C++ worlds is the one used by printf, and
- thus format can use directly printf format-strings, and produce the same
- result (in almost all cases. see <a href=
- "#printf_differences">Incompatibilities with printf</a> for details) 
- This core syntax was extended, to allow new features, but also to adapt to
- the C++ streams context. Thus, format accepts several forms of directives
- in format-strings :
-
- <ul>
- <li>Legacy printf format strings : %spec where spec
- is a printf format specification 
- spec passes formatting options, like width, alignment, numerical
- base used for formatting numbers, as well as other specific flags. But
- the classical type-specification flag of printf has a weaker
- meaning in format. It merely sets the appropriate flags on the internal
- stream, and/or formatting parameters, but does not require the
- corresponding argument to be of a specific type. 
- e.g. : the specification 2$x, meaning "print argument number 2,
- which is an integral number, in hexa" for printf, merely means "print
- argument 2 with stream basefield flags set to hex" for
- format.</li>
-
- <li>%|spec| where spec is a printf format
- specification. 
- The brackets are introduced, to improve the readability of the
- format-string, but primarily, to make the type-conversion
- character optional in spec. This information is not necessary
- with C++ variables, but with direct printf syntax, it is necessary to
- always give a type-conversion character, merely because this character is
- crucial to determine the end of a format-specification. 
- e.g. : "%|-5|" will format the next variable with width set to 5, and
- left-alignment just like the following printf directives : "%-5g",
- "%-5f", "%-5s" ..</li>
-
- <li>%N% 
- This simple positional notation requests the formatting of the
- N-th argument - wihout any formatting option. 
- (It's merely a shortcut to Printf's positional directives (like
- "%N$s"), but a major benefit is that it's much more readable, and
- does not use a "type-conversion" character)</li>
- </ul>On top of the standard printf format specifications, new features were
- implemented, like centered alignment. See <a href="#new_directives">new
- format specification</a> for details. <a name="printf_directives" id=
- "printf_directives"></a>
-
- <h3>printf format specifications</h3>
-
- The printf format specifications supported by Boost.format follows the
- Unix98 <a href=
- "http://www.opengroup.org/onlinepubs/7908799/xsh/fprintf.html">Open-group
- printf</a> precise syntax, rather than the standard C printf, which does
- not support positional arguments. (Common flags have the same meaning in
- both, so it should not be a headache for anybody) 
- Note that it is an error to use positional format specifications
- (e.g. %3$+d) mixed with non-positional ones (e.g. %+d)
- in the same format string. 
- In the Open-group specification, referring to the same argument several
- times (e.g. "%1$d %1$d") has undefined behaviour. Boost.format's
- behaviour in such cases is to allow each argument to be reffered to any
- number of times. The only constraint is that it expects exactly P
- arguments, P being the maximum argument number used in the format
- string. (e.g., for "%1$d %10$d", P == 10 ). 
- Supplying more, or less, than P arguments raises an exception.
- (unless it was set otherwise, see exceptions)
-
- 
- 
- A specification spec has the form : [ N$ ] [
- flags ] [ width ] [ . precision ]
- type-char 
- 
- Fields insided square brackets are optional. Each of those fields are
- explained one by one in the following list :
-
- <ul>
- <li>N $ (optional field) specifies that the format
- specification applies to the N-th argument. (it is called a
- positional format specification) 
- If this is not present, arguments are taken one by one. (and it is then
- an error to later supply an argument number)</li>
-
- <li>
- flags is a sequences of any of those :
-
- <blockquote>
- <table border="1" cellpadding="5" summary="">
- <tr>
- <td>Flag</td>
-
- <td>Meaning</td>
-
- <td>effect on internal stream</td>
- </tr>
-
- <tr>
- <td>'-'</td>
-
- <td>left alignment</td>
-
- <td>N/A (applied later on the string)</td>
- </tr>
-
- <tr>
- <td>'='</td>
-
- <td>centered alignment</td>
-
- <td>N/A (applied later on the string) 
- - note : added feature, not in printf -</td>
- </tr>
-
- <tr>
- <td>'_'</td>
-
- <td>internal alignment</td>
-
- <td>sets internal alignment 
- - note : added feature, not in printf -</td>
- </tr>
-
- <tr>
- <td>'+'</td>
-
- <td>show sign even for positive numbers</td>
-
- <td>sets showpos</td>
- </tr>
-
- <tr>
- <td>'#'</td>
-
- <td>show numerical base, and decimal point</td>
-
- <td>sets showbase and showpoint</td>
- </tr>
-
- <tr>
- <td>'0'</td>
-
- <td>pad with 0's (inserted after sign or base indicator)</td>
-
- <td>if not left-aligned, calls setfill('0') and sets
- internal 
- Extra actions are taken after stream conversion to handle
- user-defined output.</td>
- </tr>
-
- <tr>
- <td>' '</td>
-
- <td>if the string does not begin with + or -,
- insert a space before the converted string</td>
-
- <td>N/A (applied later on the string) 
- Different to printf's behaviour : it is not affected by internal
- alignment</td>
- </tr>
- </table>
- </blockquote>
- </li>
-
- <li>width specifies a minimal width for the string resulting form
- the conversion. If necessary, the string will be padded with alignment
- and fill characters either set on the stream via manipulators, or
- specified by the format-string (e.g. flags '0', '-', ..) 
- Note that width is not just set on the conversion stream. To support
- output of user-defined types (that might call
- operator<< many times on several members), the width is
- handled after stream conversion of the whole argument object, in the
- format class code.</li>
-
- <li>
- precision (preceded by a point), sets the stream's
- precision
-
- <ul>
- <li>When outputting a floatting type number, it sets the maximum
- number of digits
-
- <ul>
- <li>after decimal point when in fixed or scientific mode</li>
-
- <li>in total when in default mode ('general mode', like
- %g)</li>
- </ul>
- </li>
-
- <li>When used with type-char s or S it takes another
- meaning : the conversion string is truncated to the precision
- first chars. (Note that the eventual padding to width is done
- after truncation.)</li>
- </ul>
- </li>
-
- <li>
- type-char. it does not impose the concerned argument to
- be of a restricted set of types, but merely sets the flags that are
- associated with this type specification.
-
- <blockquote>
- <table border="1" cellpadding="5" summary="">
- <tr>
- <td>Type-Char</td>
-
- <td>Meaning</td>
-
- <td>effect on stream</td>
- </tr>
-
- <tr>
- <td>p or x</td>
-
- <td>hexadecimal output</td>
-
- <td>sets hex</td>
- </tr>
-
- <tr>
- <td>o</td>
-
- <td>octal output</td>
-
- <td>sets oct</td>
- </tr>
-
- <tr>
- <td>e</td>
-
- <td>scientific float format</td>
-
- <td>sets floatfield bits to scientific</td>
- </tr>
-
- <tr>
- <td>f</td>
-
- <td>fixed float format</td>
-
- <td>sets floatfield bits to fixed</td>
- </tr>
-
- <tr>
- <td>g</td>
-
- <td>general -default- float format</td>
-
- <td>unset all floatfield bits</td>
- </tr>
-
- <tr>
- <td>X, E or G</td>
-
- <td>same effect as their lowercase counterparts, but using
- uppercase letters for number outputs. (exponents, hex digits,
- ..)</td>
-
- <td>same effects as 'x', 'e', or 'g',
- plus uppercase</td>
- </tr>
-
- <tr>
- <td>d, i or u</td>
-
- <td>decimal type output</td>
-
- <td>sets basefield bits to dec</td>
- </tr>
-
- <tr>
- <td>s or S</td>
-
- <td>string output</td>
-
- <td>precision specification is unset, and its value goes
- to an internal field for later 'truncation'. (see
- precision explanation above)</td>
- </tr>
-
- <tr>
- <td>c or C</td>
-
- <td>1-character output</td>
-
- <td>only the first character of the conversion string is
- used.</td>
- </tr>
-
- <tr>
- <td>%</td>
-
- <td>print the character %</td>
-
- <td>N/A</td>
- </tr>
- </table>
- </blockquote>
-
- Note that the 'n' type specification is ignored (and so is the
- corresponding argument), because it does not fit in this context. 
- Also, printf 'l', 'L', or 'h' modifiers (to indicate wide, long or
- short types) are supported (and simply have no effect on the internal
- stream).
- </li>
- </ul><a name="new_directives" id="new_directives"></a>
-
- <h3>new format-specifications</h3>
-
- <ul>
- <li>as stated in the flags table, centered and internal alignment flags
- (' = ', and ' _ ') were added.</li>
-
- <li>%{nt} , where n is a positive number,
- inserts an absolute tabulation. It means that format will, if
- needed, fill the string with characters, until the length of the string
- created so far reaches n characters. (see <a href=
- "#examples">examples</a> )</li>
-
- <li>%{nTX} inserts a tabulation in the
- same way, but using X as fill character instead of the current
- 'fill' char of the stream (which is space for a stream in default
- state)</li>
- </ul><a name="printf_differences" id="printf_differences"></a>
-
- <h2>Differences of behaviour vs printf</h2>Suppose you have variables
- x1, x2 (built_in types, supported by C's printf), 
- and a format string s intended for use with a printf function this
- way :
-
- <blockquote>
- <pre>
-printf(s, x1, x2);
-</pre>
- </blockquote> 
- In almost all cases, the result will be the same as with this command :
-
- <blockquote>
- <pre>
-cout << format(s) % x1 % x2;
-</pre>
- </blockquote>
-
- But because some printf format specifications don't translate well into
- stream formatting options, there are a few notable imperfections in the way
- Boost.format emulates printf. 
- In any case, the format class should quietly ignore the unsupported
- options, so that printf format-strings are always accepted by format and
- produce almost the same output as printf. 
- Here is the full list of such differences :
-
- <ul>
- <li>'0' and ' ' options : printf ignores these options for
- non numeric conversions, but format applies them to all types of
- variables. (so it is possible to use those options on user-defined types,
- e.g. a Rational class, etc..)</li>
-
- <li>precision for integral types arguments has a special meaning
- for printf : 
- printf( "(%5.3d)" , 7 ) ; prints « ( 007) » 
- While format, like streams, ignores the precision parameter for integral
- types conversions.</li>
-
- <li>the ' printf option (format with thousands grouping
- characters)) has no effect in format.</li>
-
- <li>Width or precision set to asterisk (*) are used by printf to
- read this field from an argument. e.g.
- printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec); 
- This class does not support this mechanism for now. so such precision or
- width fields are quietly ignored by the parsing.</li>
- </ul>Also, note that the special 'n' type-specification (used to
- tell printf to save in a variable the number of characters output by the
- formatting) has no effect in format. 
- Thus format strings containing this type-specification should produce the
- same converted string by printf or format. It will not cause differences in
- the formatted strings between printf and format. 
- To get the number of characters in the formatted string using Boost.Format,
- you can use the size() member function :
-
- <blockquote>
- <pre>
-format formatter("%+5d");
+ cout << format("%1%, %2%, %|40t|%3%\n") % names[i] % surname[i] % tel[i];
+</PRE>
+ For some std::vector names, surnames, and tel
+ (see sample_new_features.cpp) it prints :
+ 
+ <PRE STYLE="margin-right: 1cm">Marc-François Michel, Durand, +33 (0) 123 456 789
+Jean, de Lattre de Tassigny, +33 (0) 987 654 321</PRE>
+</UL>
+<HR>
+<H2>Sample Files</H2>
+The program sample_formats.cpp
+demonstrates simple uses of format.
+sample_new_features.cpp
+illustrates the few formatting features that were added to printf's
+syntax such as simple positional directives, centered alignment, and
+'tabulations'.
+sample_advanced.cpp
+demonstrates uses of advanced features, like reusing, and modifying,
+format objects, etc..
+And sample_userType.cpp
+shows the behaviour of the format library on user-defined
+types.
+<HR>
+<H2>Syntax</H2>
+boost::format( format-string ) % arg1 % arg2
+% ... % argN
+The format-string contains text in which special directives
+will be replaced by strings resulting from the formatting of the
+given arguments. The legacy syntax in the C and C++ worlds is the
+one used by printf, and thus format can use directly printf
+format-strings, and produce the same result (in almost all cases. see
+Incompatibilities with printf for
+details) This core syntax was extended, to allow new features, but
+also to adapt to the C++ streams context. Thus, format accepts
+several forms of directives in format-strings :
+<UL>
+ <LI>Legacy printf format strings :
+ %spec where spec is a <A HREF="#printf_directives">printf
+ format specification</A> spec passes formatting options,
+ like width, alignment, numerical base used for formatting numbers,
+ as well as other specific flags. But the classical
+ type-specification flag of printf has a weaker meaning in
+ format. It merely sets the appropriate flags on the internal stream,
+ and/or formatting parameters, but does not require the corresponding
+ argument to be of a specific type. e.g. : the specification 2$x,
+ meaning "print argument number 2, which is an integral number,
+ in hexa" for printf, merely means "print argument 2 with
+ stream basefield flags set to hex" for format.
+ 
+ <LI>%|spec| where
+ spec is a printf format specification. The enclosing pipes
+ are introduced, to improve the readability of the format-string, but
+ primarily, to make the type-conversion character optional in
+ spec. This information is not necessary with C++ variables,
+ but with direct printf syntax, it is necessary to always give a
+ type-conversion character, merely because this character is crucial
+ to determine the end of a format-specification. e.g. : "%|-5|"
+ will format the next variable with width set to 5, and
+ left-alignment just like the following printf directives : "%-5g",
+ "%-5f", "%-5s" ..
+ 
+ <LI>%N% This simple positional notation
+ requests the formatting of the N-th argument - wihout any
+ formatting option. (It's merely a shortcut to Printf's positional
+ directives (like "%N$s"), but a major benefit is
+ that it's much more readable, and does not use a "type-conversion"
+ character)
+ 
+</UL>
+On top of the standard printf format specifications, new features
+were implemented, like centered alignment. See <A HREF="#new_directives">new
+format specification</A> for details.
+
+<H3>printf format specifications</H3>
+The printf format specifications supported by Boost.format follows
+the Unix98 <A HREF="http://www.opengroup.org/onlinepubs/7908799/xsh/fprintf.html">Open-group
+printf</A> precise syntax, rather than the standard C printf, which
+does not support positional arguments. (Common flags have the same
+meaning in both, so it should not be a headache for anybody) Note
+that it is an error to use positional format specifications (e.g.
+%3$+d) mixed with non-positional ones (e.g. %+d)
+in the same format string. In the Open-group specification,
+referring to the same argument several times (e.g. "%1$d
+%1$d") has undefined behaviour. Boost.format's behaviour in
+such cases is to allow each argument to be reffered to any number of
+times. The only constraint is that it expects exactly P
+arguments, P being the maximum argument number used in the
+format string. (e.g., for "%1$d %10$d", P == 10
+). Supplying more, or less, than P arguments raises an
+exception. (unless it was set otherwise, see exceptions)
+ A specification spec has the form : [ N$
+] [ flags ] [ width ] [ . precision ]
+type-char Fields insided square brackets are optional.
+Each of those fields are explained one by one in the following list :
+<UL>
+ <LI>N $ (optional field)
+ specifies that the format specification applies to the N-th
+ argument. (it is called a positional format specification) If
+ this is not present, arguments are taken one by one. (and it is then
+ an error to later supply an argument number)
+ 
+ <LI>flags is a sequences of any of those :
+ 
+ <TABLE BORDER=1 CELLPADDING=5 CELLSPACING=2>
+ <TR>
+ <TD>
+ Flag
+ </TD>
+ <TD>
+ Meaning
+ </TD>
+ <TD>
+ effect on internal stream
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ '-'
+ </TD>
+ <TD>
+ left alignment
+ </TD>
+ <TD>
+ N/A (applied later on the string)
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ '='
+ </TD>
+ <TD>
+ centered alignment
+ </TD>
+ <TD>
+ N/A (applied later on the string) - note : added
+ feature, not in printf -
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ '_'
+ </TD>
+ <TD>
+ internal alignment
+ </TD>
+ <TD>
+ sets internal alignment - note : added feature, not in
+ printf -
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ '+'
+ </TD>
+ <TD>
+ show sign even for positive numbers
+ </TD>
+ <TD>
+ sets showpos
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ '#'
+ </TD>
+ <TD>
+ show numerical base, and decimal point
+ </TD>
+ <TD>
+ sets showbase and showpoint
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ '0'
+ </TD>
+ <TD>
+ pad with 0's (inserted after sign or base indicator)
+ </TD>
+ <TD>
+ if not left-aligned, calls setfill('0') and sets
+ internal Extra actions are taken after stream
+ conversion to handle user-defined output.
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ ' '
+ </TD>
+ <TD>
+ if the string does not begin with + or -, insert
+ a space before the converted string
+ </TD>
+ <TD>
+ N/A (applied later on the string) Different to printf's
+ behaviour : it is not affected by internal alignment
+ </TD>
+ </TR>
+ </TABLE>
+ <LI>width specifies a minimal
+ width for the string resulting form the conversion. If necessary,
+ the string will be padded with alignment and fill characters either
+ set on the stream via manipulators, or specified by the
+ format-string (e.g. flags '0', '-', ..) Note that width is not
+ just set on the conversion stream. To support output of <A HREF="#user-defined">user-defined
+ types</A> (that might call operator<< many times on
+ several members), the width is handled after stream conversion of
+ the whole argument object, in the format class code.
+ 
+ <LI>precision (preceded by a
+ point), sets the stream's precision
+ 
+ <UL>
+ <LI>When outputting a floatting type
+ number, it sets the maximum number of digits
+ 
+ <UL>
+ <LI>after decimal point when in
+ fixed or scientific mode
+ 
+ <LI>in total when in default mode
+ ('general mode', like %g)
+ 
+ </UL>
+ <LI>When used with type-char s
+ or S it takes another meaning : the conversion string is
+ truncated to the precision first chars. (Note that the
+ eventual padding to width is done after truncation.)
+ 
+ </UL>
+ <LI>type-char. it does not impose the concerned
+ argument to be of a restricted set of types, but merely sets the
+ flags that are associated with this type specification.
+ 
+ <TABLE BORDER=1 CELLPADDING=5 CELLSPACING=2>
+ <TR>
+ <TD>
+ Type-Char
+ </TD>
+ <TD>
+ Meaning
+ </TD>
+ <TD>
+ effect on stream
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ p or x
+ </TD>
+ <TD>
+ hexadecimal output
+ </TD>
+ <TD>
+ sets hex
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ o
+ </TD>
+ <TD>
+ octal output
+ </TD>
+ <TD>
+ sets oct
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ e
+ </TD>
+ <TD>
+ scientific float format
+ </TD>
+ <TD>
+ sets floatfield bits to scientific
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ f
+ </TD>
+ <TD>
+ fixed float format
+ </TD>
+ <TD>
+ sets floatfield bits to fixed
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ g
+ </TD>
+ <TD>
+ general -default- float format
+ </TD>
+ <TD>
+ unset all floatfield bits
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ X, E or G
+ </TD>
+ <TD>
+ same effect as their lowercase counterparts, but using
+ uppercase letters for number outputs. (exponents, hex digits, ..)
+ </TD>
+ <TD>
+ same effects as 'x', 'e', or 'g', plus
+ uppercase
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ d, i or u
+ </TD>
+ <TD>
+ decimal type output
+ </TD>
+ <TD>
+ sets basefield bits to dec
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ s or S
+ </TD>
+ <TD>
+ string output
+ </TD>
+ <TD>
+ precision specification is unset, and its value goes to
+ an internal field for later 'truncation'. (see precision
+ explanation above)
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ c or C
+ </TD>
+ <TD>
+ 1-character output
+ </TD>
+ <TD>
+ only the first character of the conversion string is used.
+ </TD>
+ </TR>
+ <TR>
+ <TD>
+ %
+ </TD>
+ <TD>
+ print the character %
+ </TD>
+ <TD>
+ N/A
+ </TD>
+ </TR>
+ </TABLE>
+ Note that the 'n' type specification is ignored (and so is the
+ corresponding argument), because it does not fit in this
+ context. Also, printf 'l', 'L', or 'h' modifiers (to indicate
+ wide, long or short types) are supported (and simply have no effect
+ on the internal stream).
+</UL>
+<H3><A NAME="new_directives"></A>new format-specifications</H3>
+<UL>
+ <LI>as stated in the flags table,
+ centered and internal alignment flags (' = ', and ' _
+ ') were added.
+ 
+ <LI>%|nt|
+ , where n is a positive number, inserts an absolute
+ tabulation. It means that format will, if needed, fill the
+ string with characters, until the length of the string created so
+ far reaches n characters. (see examples
+ )
+ 
+ <LI>%|nTX| inserts a
+ tabulation in the same way, but using X as fill character
+ instead of the current 'fill' char of the stream (which is space
+ for a stream in default state)
+ 
+</UL>
+<H2><A NAME="printf_differences"></A>Differences of behaviour vs
+printf</H2>
+Suppose you have variables x1, x2 (built_in types,
+supported by C's printf), and a format string s intended
+for use with a printf function this way :
+
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm; margin-bottom: 0.5cm">printf(s, x1, x2);</PRE>
+ In almost all cases, the result will be the same as with this
+command :
+
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm; margin-bottom: 0.5cm">cout << format(s) % x1 % x2;</PRE>
+But because some printf format specifications don't translate well
+into stream formatting options, there are a few notable imperfections
+in the way Boost.format emulates printf. In any case, the format
+class should quietly ignore the unsupported options, so that printf
+format-strings are always accepted by format and produce almost the
+same output as printf.
+ Here is the full list of such differences :
+
+<UL>
+ <LI>'0' and ' ' options
+ : printf ignores these options for non numeric conversions, but
+ format applies them to all types of variables. (so it is possible to
+ use those options on user-defined types, e.g. a Rational class,
+ etc..)
+ 
+ <LI>precision for integral
+ types arguments has a special meaning for printf : printf(
+ "(%5.3d)" , 7 ) ; prints « ( 007) » While
+ format, like streams, ignores the precision parameter for integral
+ types conversions.
+ 
+ <LI>the ' printf option (format
+ with thousands grouping characters)) has no effect in format.
+ 
+ <LI>Width or precision set to asterisk (*) are used by
+ printf to read this field from an argument. e.g.
+ printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min,
+ precision, sec); This class does not support this mechanism
+ for now. so such precision or width fields are quietly ignored by
+ the parsing.
+ 
+</UL>
+Also, note that the special 'n' type-specification (used to
+tell printf to save in a variable the number of characters output by
+the formatting) has no effect in format. Thus format strings
+containing this type-specification should produce the same converted
+string by printf or format. It will not cause differences in the
+formatted strings between printf and format. To get the number of
+characters in the formatted string using Boost.Format, you can use
+the size() member function :
+
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">format formatter("%+5d");
cout << formatter % x;
-unsigned int n = formatter.size();
-</pre>
- </blockquote><a name="user-defined" id="user-defined"></a>
- <hr>
-
- <h2>User-defined types output</h2>
-
- All flags which are translated into modification to the stream state act
- recursively within user-defined types. ( the flags remain active, and so
- does the desired format option, for each of the '<<' operations that
- might be called by the user-defined class)e.g., with a Rational class,
- we would have something like :
-
- <blockquote>
- <pre>
-Rational ratio(16,9);
-cerr << format("%#x \n") % ratio; // -> "0x10/0x9 \n"
-</pre>
- </blockquote>
-
- It's a different story for other formatting options. For example,
- setting width applies to the final output produced by the object, not to
- each of its internal outputs, and that's fortunate :
-
- <blockquote>
- <pre>
-cerr << format("%-8d") % ratio; // -> "16/9 " and not "16 /9 "
-cerr << format("%=8d") % ratio; // -> " 16/9 " and not " 16 / 9 "
-</pre>
- </blockquote>
-
- 
- But so does the 0 and ' ' options (contrarily to '+' which is directly
- translated to the stream state by showpos. But no such flags exist
- for the zero and space printf options) 
- and that is less natural :
-
- <blockquote>
- <pre>
-cerr << format("%+08d \n") % ratio; // -> "+00016/9"
-cerr << format("% 08d \n") % ratio; // -> "000 16/9"
-</pre>
- </blockquote>It is possible to obtain a better behaviour by carefully
- designing the Rational's operator<< to handle the stream's
- width, alignment and showpos paramaters by itself. This is
- demonstrated in <a href=
- "../example/sample_userType.cpp">sample_userType.cpp</a>. <a name=
- "manipulators" id="manipulators"></a>
- <hr>
-
- <h3>Manipulators, and internal stream state</h3>
-
- The internal stream state of format is saved before and restored
- after output of an argument; therefore, the modifiers are not sticky and
- affect only the argument they are applied to. 
- The default state for streams, as stated by the standard, is : precision 6,
- width 0, right alignment, and decimal flag set.
-
- The state of the internal format stream can be changed by
- manipulators passed along with the argument; via the group function,
- like that :
-
- <blockquote>
- <pre>
-cout << format("%1% %2% %1%\n") % group(hex, showbase, 40) % 50; // prints "0x28 50 0x28\n"
-</pre>
- </blockquote>
-
- 
- When passing N items inside a 'group' Boost.format needs to process
- manipulators diferently from regular argument, and thus using group is
- subject to the following constraints :
-
- <ol>
- <li>the object to be printed must be passed as the last item in the
- group</li>
-
- <li>the first N-1 items are treated as manipulators, and if they do
- produce output, it is discarded</li>
- </ol>
-
- Such manipulators are passed to the streams right before the following
- argument, at every occurence. Note that formatting options specified within
- the format string are overridden by stream state modifiers passed this way.
- For instance in the following code, the hex manipulator has priority
- over the d type-specification in the format-string which would set
- decimal output :
-
- <blockquote>
- <pre>
-cout << format("%1$d %2% %1%\n") % group(hex, showbase, 40) % 50;
-// prints "0x28 50 0x28\n"
-</pre>
- </blockquote><a name="alternatives" id="alternatives"></a>
-
- <h2>Alternatives</h2>
-
- <ul>
- <li>printf is the classical alternative, that is not type safe and
- not extendable to user-defined types.</li>
-
- <li>ofrstream.cc by Karl Nelson's design was a big source of inspiration
- to this format class.</li>
-
- <li>James Kanze's library has a format class (in
- srcode/Extended/format ) which looks very well polished. Its
- design has in common with this class the use of internal stream for the
- actual conversions, as well as using operators to pass arguments. (but
- his class, as ofrstream, uses operator<< rather than
- operator% )</li>
-
- <li><a href="http://groups.yahoo.com/group/boost/files/format3/">Karl
- Nelson's library</a> was intented as demonstration of alternative
- solutions in discussions on Boost's list for the design of
- Boost.format.</li>
- </ul><a name="exceptions" id="exceptions"></a>
- <hr>
-
- <h2>Exceptions</h2>
-
- Boost.format enforces a number of rules on the usage of format objects.
- The format-string must obeys the syntax described above, the user must
- supply exactly the right number of arguments before outputting to the final
- destination, and if using modify_item or bind_arg, items and arguments
- index must not be out of range. 
- When format detects that one of these rules is not satisfied, it raises a
- corresponding exception, so that the mistakes don't go unnoticed and
- unhandled. 
- But the user can change this behaviour to fit his needs, and select which
- types of errors may raise exceptions using the following functions :
-
- <blockquote>
- <pre>
-
+unsigned int n = formatter.size();</PRE>
+<HR>
+<H2>User-defined types output</H2>
+All flags which are translated into modification to the stream
+state act recursively within user-defined types. ( the flags remain
+active, and so does the desired format option, for each of the '<<'
+operations that might be called by the user-defined class)
+e.g., with a Rational class, we would have something like :
+
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">Rational ratio(16,9);
+cerr << format("%#x \n") % ratio; // -> "0x10/0x9 \n"</PRE>
+It's a different story for other formatting options. For example,
+setting width applies to the final output produced by the object, not
+to each of its internal outputs, and that's fortunate :
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">cerr << format("%-8d") % ratio; // -> "16/9 " and not "16 /9 "
+cerr << format("%=8d") % ratio; // -> " 16/9 " and not " 16 / 9 "</PRE>
+ But so does the 0 and ' ' options (contrarily to '+' which is
+directly translated to the stream state by showpos. But no
+such flags exist for the zero and space printf options) and that
+is less natural :
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">cerr << format("%+08d \n") % ratio; // -> "+00016/9"
+cerr << format("% 08d \n") % ratio; // -> "000 16/9"</PRE>
+It is possible to obtain a better behaviour by carefully designing
+the Rational's operator<< to handle the stream's width,
+alignment and showpos paramaters by itself. This is
+demonstrated in sample_userType.cpp.
+
+<HR>
+<H3>Manipulators, and internal stream state</H3>
+The internal stream state of format is saved before and
+restored after output of an argument; therefore, the modifiers are
+not sticky and affect only the argument they are applied to. The
+default state for streams, as stated by the standard, is : precision
+6, width 0, right alignment, and decimal flag set.
+The state of the internal format stream can be changed by
+manipulators passed along with the argument; via the group
+function, like that :
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm; margin-bottom: 0.5cm">cout << format("%1% %2% %1%\n") % group(hex, showbase, 40) % 50; // prints "0x28 50 0x28\n"</PRE>
+ When passing N items inside a 'group' Boost.format needs to
+process manipulators diferently from regular argument, and thus using
+group is subject to the following constraints :
+<OL>
+ <LI>the object to be printed must be
+ passed as the last item in the group
+ 
+ <LI>the first N-1 items are treated as manipulators, and if they
+ do produce output, it is discarded
+ 
+</OL>
+Such manipulators are passed to the streams right before the
+following argument, at every occurence. Note that formatting options
+specified within the format string are overridden by stream state
+modifiers passed this way. For instance in the following code, the
+hex manipulator has priority over the d
+type-specification in the format-string which would set decimal
+output :
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">cout << format("%1$d %2% %1%\n") % group(hex, showbase, 40) % 50;
+// prints "0x28 50 0x28\n"</PRE><H2>
+Alternatives</H2>
+<UL>
+ <LI>printf is the classical
+ alternative, that is not type safe and not extendable to
+ user-defined types.
+ 
+ <LI>ofrstream.cc by Karl Nelson's
+ design was a big source of inspiration to this format class.
+ 
+ <LI>James Kanze's library has a format
+ class (in srcode/Extended/format ) which looks very well
+ polished. Its design has in common with this class the use of
+ internal stream for the actual conversions, as well as using
+ operators to pass arguments. (but his class, as ofrstream, uses
+ operator<< rather than operator% )
+ 
+ <LI><A HREF="http://groups.yahoo.com/group/boost/files/format3/">Karl
+ Nelson's library</A> was intented as demonstration of alternative
+ solutions in discussions on Boost's list for the design of
+ Boost.format.
+ 
+</UL>
+<HR>
+<H2>Exceptions</H2>
+Boost.format enforces a number of rules on the usage of format
+objects. The format-string must obeys the syntax described above, the
+user must supply exactly the right number of arguments before
+outputting to the final destination, and if using modify_item or
+bind_arg, items and arguments index must not be out of range. When
+format detects that one of these rules is not satisfied, it raises a
+corresponding exception, so that the mistakes don't go unnoticed and
+unhandled. But the user can change this behaviour to fit his
+needs, and select which types of errors may raise exceptions using
+the following functions :
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">
unsigned char exceptions(unsigned char newexcept); // query and set
unsigned char exceptions() const; // just query
-
-</pre>
- </blockquote>
-
- The user can compute the argument newexcept by combining the
- following atoms using binary arithmetic :
-
- <ul>
- <li>boost::io::bad_format_string_bit selects errors due to
- ill-formed format-strings.</li>
-
- <li>boost::io::too_few_args_bit selects errors due to asking for
- the srting result before all arguments are passed.</li>
-
- <li>boost::io::too_many_args_bit selects errors due to passing too
- many arguments.</li>
-
- <li>boost::io::out_of_range_bit select errors due to out of range
- index supplied by the user when calling modify_item or other
- functions taking an item index (or an argument index)</li>
-
- <li>boost::io::all_error_bits selects all errors</li>
-
- <li>boost::io::no_error_bits selects no error.</li>
- </ul>
-
- For instance, if you don't want Boost.format to detect bad number of
- arguments, you can define a specific wrapper function for building format
- objects with the right exceptions settings :
-
- <blockquote>
- <pre>
-
+</PRE>
+The user can compute the argument newexcept by combining the
+following atoms using binary arithmetic :
+<UL>
+ <LI>boost::io::bad_format_string_bit
+ selects errors due to ill-formed format-strings.
+ 
+ <LI>boost::io::too_few_args_bit
+ selects errors due to asking for the srting result before all
+ arguments are passed.
+ 
+ <LI>boost::io::too_many_args_bit
+ selects errors due to passing too many arguments.
+ 
+ <LI>boost::io::out_of_range_bit
+ select errors due to out of range index supplied by the user when
+ calling modify_item or other functions taking an item index
+ (or an argument index)
+ 
+ <LI>boost::io::all_error_bits
+ selects all errors
+ 
+ <LI>boost::io::no_error_bits selects no error.
+ 
+</UL>
+For instance, if you don't want Boost.format to detect bad number
+of arguments, you can define a specific wrapper function for building
+format objects with the right exceptions settings :
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">
boost::format my_fmt(const std::string & f_string) {
 using namespace boost::io;
 format fmter(f_string);
 fmter.exceptions( all_error_bits ^ ( too_many_args_bit | too_few_args_bit ) );
 return fmter;
}
-
-</pre>
- </blockquote>It is then allowed to give more arguments than needed (they
- are simply ignored) :
-
- <blockquote>
- <pre>
-
-cout << my_fmt(" %1% %2% \n") % 1 % 2 % 3 % 4 % 5;
-
-</pre>
- </blockquote>And if we ask for the result before all arguments are
- supplied, the corresponding part of the result is simply empty
-
- <blockquote>
- <pre>
-
-cout << my_fmt(" _%2%_ _%1%_ \n") % 1 ;
-// prints " __ _1_ \n"
-
-</pre>
- </blockquote><a name="performance" id="performance"></a>
- <hr>
-
- <h2>A Note about performance</h2>
-
- The performance of boost::format for formatting a few builtin type
- arguments with reordering can be compared to that of Posix-printf, and of
- the equivalent stream manual operations to give a measure of the overhead
- incurred. The result may greatly depend on the compiler, standard library
- implementation, and the precise choice of format-string and arguments.
-
- Since common stream implementations eventually call functions of the
- printf family for the actual formatting of numbers, in general printf will
- be noticeably faster than the direct stream operations And due to to the
- reordering overhead (allocations to store the pieces of string, stream
- initialisation at each item formatting, ..) the direct stream operations
- would be faster than boost::format, (one cas expect a ratio ranging from 2
- to 5 or more)
-
- When iterated formattings are a performance bottleneck, performance can
- be slightly increased by parsing the format string into a format object,
- and copying it at each formatting, in the following way.
-
- <blockquote>
- <pre>
- const boost::format fmter(fstring);
- dest << boost::format(fmter) % arg1 % arg2 % arg3 ;
-</pre>
- </blockquote>
-
- As an example of performance results, the author measured the time of
- execution of iterated formattings with 4 different methods
-
- <ol>
- <li>posix printf</li>
-
- <li>manual stream output (to a dummy nullStream stream sending the
- bytes into oblivion)</li>
-
- <li>boost::format copied from a const object as shown above</li>
-
- <li>the straigt boost::format usage</li>
- </ol>
-
- the test was compiled with g++-3.3.3 and the following timings were
- measured (in seconds, and ratios) :
-
- <blockquote>
- <pre>
-string fstring="%3$0#6x %1$20.10E %2$g %3$0+5d \n";
+</PRE>
+It is then allowed to give more arguments than needed (they are
+simply ignored) :
+
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">
+cout << my_fmt(" %1% %2% \n") % 1 % 2 % 3 % 4 % 5;
+</PRE>
+And if we ask for the result before all arguments are supplied, the
+corresponding part of the result is simply empty
+
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">
+cout << my_fmt(" _%2%_ _%1%_ \n") % 1 ;
+// prints " __ _1_ \n"
+</PRE>
+<HR>
+<H2>A Note about performance</H2>
+The performance of boost::format for formatting a few builtin type
+arguments with reordering can be compared to that of Posix-printf,
+and of the equivalent stream manual operations to give a measure of
+the overhead incurred. The result may greatly depend on the compiler,
+standard library implementation, and the precise choice of
+format-string and arguments.
+Since common stream implementations eventually call functions of
+the printf family for the actual formatting of numbers, in general
+printf will be noticeably faster than the direct stream operations
+And due to to the reordering overhead (allocations to store the
+pieces of string, stream initialisation at each item formatting, ..)
+the direct stream operations would be faster than boost::format, (one
+cas expect a ratio ranging from 2 to 5 or more)
+When iterated formattings are a performance bottleneck,
+performance can be slightly increased by parsing the format string
+into a format object, and copying it at each formatting, in the
+following way.
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm"> const boost::format fmter(fstring);
+ dest << boost::format(fmter) % arg1 % arg2 % arg3 ;</PRE>
+As an example of performance results, the author measured the time of
+execution of iterated formattings with 4 different methods
+<OL>
+ <LI>posix printf
+ 
+ <LI>manual stream output (to a dummy
+ nullStream stream sending the bytes into oblivion)
+ 
+ <LI>boost::format copied from a const
+ object as shown above
+ 
+ <LI>the straigt boost::format usage
+ 
+</OL>
+the test was compiled with g++-3.3.3 and the following timings
+were measured (in seconds, and ratios) :
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">string fstring="%3$0#6x %1$20.10E %2$g %3$0+5d \n";
double arg1=45.23;
double arg2=12.34;
int arg3=23;
@@ -916,16 +826,10 @@
printf : 2.12
nullStream : 3.69, = 1.74057 * printf
boost::format copied :10.02, = 4.72642 * printf , = 2.71545 * nullStream
-boost::format straight :17.03, = 8.03302 * printf , = 4.61518 * nullStream
-</pre>
- </blockquote><a name="extract" id="extract"></a>
- <hr>
-
- <h2>Class Interface Extract</h2>
-
- <blockquote>
- <pre>
-namespace boost {
+boost::format straight :17.03, = 8.03302 * printf , = 4.61518 * nullStream</PRE>
+<HR>
+<H2>Class Interface Extract</H2>
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">namespace boost {

template<class charT, class Traits=std::char_traits<charT> >
class basic_format
@@ -971,60 +875,52 @@
}

-} // namespace boost
-</pre>
- </blockquote>
- <hr>
- <a name="rationale" id="rationale"></a>
-
- <h2>Rationale</h2>
-
- This class's goal is to bring a better, C++, type-safe and
- type-extendable printf equivalent to be used with
- streams.Precisely, format was designed to provide the following
- features :
-
- <ul>
- <li>support positional arguments (required for internationalisation)</li>
-
- <li>accept an unlimited number of arguments.</li>
-
- <li>make formatting commands visually natural.</li>
-
- <li>support the use of manipulators to modify the display of an argument.
- in addition to the format-string syntax.</li>
-
- <li>accept any types of variables, by relying on streams for the actual
- conversion to string. This specifically concerns user-defined types, for
- which the formatting options effects should be intuitively natural.</li>
-
- <li>provide printf-compatibility, as much as it makes sense in a
- type-safe and type-extendable context.</li>
- </ul>
-
- In the process of the design, many issues were faced, and some choices
- were made, that might not be intuitively right. But in each case they were
- taken for some reasons.
- <hr>
-
- <h2>Credits</h2>
-
- The author of Boost format is Samuel Krempp.   He used ideas from
- Rüdiger Loos' format.hpp and Karl Nelson's formatting classes.
- <hr>
-
- <a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
- "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
- height="31" width="88"></a>
-
- Revised
- 02 December, 2006
-
- Copyright © 2002 Samuel Krempp
-
- Distributed under the Boost Software License, Version 1.0. (See
- accompanying file LICENSE_1_0.txt or
- copy at <a href=
- "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt>)
-</body>
-</html>
+} // namespace boost</PRE>
+<HR>
+<H2>Rationale</H2>
+This class's goal is to bring a better, C++, type-safe and
+type-extendable printf equivalent to be used with streams.
+Precisely, format was designed to provide the following
+features :
+
+<UL>
+ <LI>support positional arguments
+ (required for internationalisation)
+ 
+ <LI>accept an unlimited number of
+ arguments.
+ 
+ <LI>make formatting commands visually
+ natural.
+ 
+ <LI>support the use of manipulators to
+ modify the display of an argument. in addition to the format-string
+ syntax.
+ 
+ <LI>accept any types of variables, by
+ relying on streams for the actual conversion to string. This
+ specifically concerns user-defined types, for which the formatting
+ options effects should be intuitively natural.
+ 
+ <LI>provide printf-compatibility, as much as it makes sense in a
+ type-safe and type-extendable context.
+ 
+</UL>
+In the process of the design, many issues were faced, and some
+choices were made, that might not be intuitively right. But in each
+case they were taken for some reasons.
+<HR>
+<H2>Credits</H2>
+The author of Boost format is Samuel Krempp.   He used ideas
+from Rüdiger Loos' format.hpp and Karl Nelson's formatting
+classes.
+<HR>
+
+Revised
+02 December, 2006
+Copyright © 2002 Samuel Krempp
+Distributed under the Boost Software License, Version 1.0. (See
+accompanying file LICENSE_1_0.txt
+or copy at http://www.boost.org/LICENSE_1_0.txt)
+</BODY>
+</HTML>
\ No newline at end of file

Next message: Samuel.Krempp_at_[hidden]: "[Boost-commit] svn:boost r57671 - trunk/libs/format/doc"
Previous message: xushiweizh_at_[hidden]: "[Boost-commit] svn:boost r57669 - sandbox/memory/boost/memory"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk