The
<boost/format.hpp>
format class provides printf-like formatting, in a type-safe manner which allows output of
user-defined types.
(It does not depend on other boost libraries)
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.
cout << boost::format("writing %1%, x=%2% : %3%-th try") % "toto" % 40.23 % 50; // prints "writing toto, x=40.230 : 50-th try"
or later on, as incout << format("%2% %1%") % 36 % 77 )
you feed variables into the formatter.format fmter("%2% %1%"); fmter % 36; fmter % 77;
// fmter was previously created and fed arguments, it can print the result : cout << fmter ; // You can take the string result : string s = fmter.str(); // possibly several times : s = fmter.str( ); // You can also do all steps at once : cout << boost::format("%2% %1%") % 36 % 77; string s2 = boost::io::str( format("%2% %1%") % 36 % 77 );
using namespace std; using boost::format; using boost::io::group; using boost::io::str;
It prints : "11 22 333 22 11 \n"cout << format("%1% %2% %3% %2% %1% \n") % "11" % "22" % "333"; // 'simple' style.
It prints : "(x,y) = ( -23, +35) \n"cout << format("(x,y) = (%1$+5d,%2$+5d) \n") % -23 % 35; // Posix-Printf style
It prints : "writing toto, x=40.23 : 50-th step \n"cout << format("writing %s, x=%s : %d-th step \n") % "toto" % 40.23 % 50;
all those print : "(x,y) = ( -23, +35) \n"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;
Both print the same : "_ +101_ 101 \n"format fmter("_%1$+5d_ %1$d \n"); format fmter2("_%1%_ %1% \n"); fmter2.modify_item(1, group(showpos, setw(5)) ); cout << fmter % 101 ; cout << fmter2 % 101 ;
The manipulators are applied at each occurence of %1%, and thus it prints : "_ +101_ +101 \n"cout << format("_%1%_ %1% \n") % group(showpos, setw(5), 101);
For some vector names, surnames, and tel (see sample_new_features.cpp) it prints :for(unsigned int i=0; i < names.size(); ++i) cout << format("%1%, %2%, %|40t|%3%\n") % names[i] % surname[i] % tel[i];
Marc-François Michel, Durand, +33 (0) 123 456 789 Jean, de Lattre de Tassigny, +33 (0) 987 654 321
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.
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 :
The printf format specifications supported by Boost.format follows the Unix98
Open-group printf
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 :
Flag Meaning effect on internal stream '-' left alignment N/A (applied later on the string) '=' centered alignment N/A (applied later on the string)
Inexistent in printf (added feature)'+' show sign even for positive numbers sets showpos '#' show numerical base, and decimal point sets showbase and showpoint '0' pad with 0's (inserted after sign or base indicator) if not left-aligned, calls setfill('0') and sets internal
Extra actions are taken after stream conversion to handle user-defined output.' ' if the string does not begin with + or -, insert a space before the converted string N/A (applied later on the string)
Different to printf's behaviour : it is not affected by internal alignment- 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.- precision (preceded by a point), sets the stream's precision
- When outputting a floatting type number, it sets the maximum number of digits
- after decimal point when in fixed or scientific mode
- in total when in default mode ('general mode', like %g)
- 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.)
- 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.
Type-Char Meaning effect on stream p or x hexadecimal output sets hex o octal output sets oct e scientific float format sets floatfield bits to scientific f fixed float format sets floatfield bits to fixed g general -default- float format unset all floatfield bits X, E or G same effect as their lowercase counterparts, but using uppercase letters for number outputs. (exponents, hex digits, ..) same effects as 'x', 'e', or 'g', plus uppercase d, i or u decimal type output sets basefield bits to dec s or S string output precision specification is unset, and its value goes to an internal field for later 'truncation'. (see precision explanation above) c or C 1-character output only the first character of the conversion string is used. % print the character % N/A 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).
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 :
printf(s, x1, x2);
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.cout << format(s) % x1 % x2;
format formatter("%+5d"); cout << formatter % x; unsigned int n = formatter.str().size();
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 reasonable class Rational, we would have something like :
Rational ratio(16,9); cerr << format("%#x \n") % ratio; // -> "0x10/0x9 \n"
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 :
cerr << format("%-8d") % ratio; // -> "16/9 " and not "16 /9 " cerr << format("%=8d") % ratio; // -> " 16/9 " and not " 16 / 9 "
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 :
cerr << format("%+08d \n") % ratio; // -> "+00016/9" cerr << format("% 08d \n") % ratio; // -> "000 16/9"
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 :
cout << format("%1% %2% %1%\n") % group(hex, showbase, 40) % 50; // prints "0x28 50 0x28\n"
cout << format("%1$d %2% %1%\n") % group(hex, showbase, 40) % 50; // prints "0x28 50 0x28\n"
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 :
unsigned char exceptions(unsigned char newexcept); // query and set unsigned char exceptions() const; // just query
The user can compute the argument newexcept by combining the following atoms using binary arithmetic :
It is then allowed to give more arguments than needed (they are simply ignored) :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; }
And if we ask for the result before all arguments are supplied, the corresponding part of the result is simply emptycout << my_fmt(" %1% %2% \n") % 1 % 2 % 3 % 4 % 5;
cout << my_fmt(" _%2%_ _%1%_ \n") % 1 ; // prints " __ _1_ \n"
namespace boost { template<class charT, class Traits=std::char_traits<charT> > class basic_format { public: typedef std::basic_string<charT, Traits> string_t, basic_format(const charT* str); basic_format(const charT* str, const std::locale & loc); basic_format(const string_t& s); basic_format(const string_t& s, const std::locale & loc); string_t str() const; // pass arguments through those operators : template<class T> basic_format& operator%(T& x); template<class T> basic_format& operator%(const T& x); // dump buffers to ostream : friend std::basic_ostream<charT, Traits>& operator<< <> ( std::basic_ostream<charT, Traits>& , basic_format& ); // ............ this is just an extract ....... }; // basic_format typedef basic_format<char > format; typedef basic_format<wchar_t > wformat; namespace io { // free function for ease of use : template<class charT, class Traits> std::basic_string<charT,Traits> str(const basic_format<charT,Traits>& f) { return f.str(); } } //namespace io } // namespace boost
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 :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.
The author of Boost format is Samuel Krempp. He used ideas from both Rüdiger Loos' and Karl Nelson's formatting classes.
February 19, 2002
© Copyright Samuel Krempp 2002. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.