Boost.Format final submission (-pre1 :)

From: Samuel Krempp (krempp_at_[hidden])
Date: 2002-02-21 22:00:37

I finally wrote the pending modifs, both to sources and to the docs, and
uploaded it to the vault as version 1.39.

Although I carefully followed MSVC compatibilty constraints, I am still
waiting for getting access to a MSVC6 SP5 compiler, and thus the current
code will probably fail until I try it and adapt it.
This is why I consider this a pre-final submission : I will modify it
once I can try it on MSVC6
But except for that, I believe it is ready for submission, and I'd like
to know your comments, critics, and suggestions.

The doc, is uptodate, and improved. (added a new section 'examples', and
one on exceptions, and reworked many parts of the other sections)
It still lacks a description of some details, like :
1. the basic_format template and its constructors (rather than just the
format / wformat frontends)
2. bind_arg(..) / clear_bind(..) 
3. modify_item(..) is only succintly documented.

And I shall finalize those minor points if the library is not vetoed
from acceptance.

Here are the main changes in the code since the review candidate
(version '1.30') :

(already implemented in the previous versions:)
1. possibility to choose which errors will raise exceptions and which
won't
2. re-factored the headers, and re-structured the code
(MSVC requires special attention for member templates)

(completely new :)
3. chosen the syntax : printf-compatible, plus "%|stuff|", plus "%N%"

4. replaced ' % manip(hex) % manip(showbase) % 1 '

by  	    ' % group(hex, showbase, 1) ' 

in a similar way as format3.

manipulators (all but the last item in the group) are passed by value,
the last one is passed by reference (const, or not const when the
compiler supports that kind of overload). So we avoid copying user
objects.

At first I had rejected this way of passing manipulators - all at once
together with the argument, because it is not straightforward to make it
work with the complex printf directives (which requires handling width
specifications by hand rather than letting the stream do it)

But is feasible when requiring that when passing a group of N items to
format,
1. the object to be printed is passed as the last item in the group
2. the first N-1 are treated as manipulators, and if they do produce
output, it is discarded

And then it is much nicer than the individual 'manip'-wrapper solution.

About performance, the benchmark source present in the package is
provided for information mostly, as it won't compile without
modification anyplace other than my box.

Results with gcc-3.0.3 -O are :
printf time         :1.16
ostream time        :1.94,  = 1.67241 * printf 
stored format time  :3.68,  = 1.89691 * stream 
format time         :6.31,  = 3.25258 * stream 
format3 time        :9.04,  = 4.65979 * stream 

(the format-string used is : "%3$#x %1$20.10E %2$s %3$d \n")

so the overhead is quite acceptable.
(Though, the distribute function currently has quadratic behaviour on
the number of the items in the format-string, while a simple reverse
index would make it linear. My guess is that the extra allocations
required would make it slower on all real-life uses. But then if someone
wants to format 10.000 arguments in one go, the quadratic behaviour
there might become observable)

-- 
Samuel