ichthyo/LUMIERA.clone
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

document the new formatting helper, based on boost::format

Browse source
This commit is contained in:
Fischlurch 2011-12-31 07:54:16 +01:00
parent 2d1e098d2c
commit adc120fecb
2 changed files with 63 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/technical/howto/UsingBoost.txt
View file

@ -92,7 +92,9 @@ formatted output -- but typesafe, using defined conversion operators and without
the plain-C `printf` famility of functions. But beware: `boost::format` is implemented on top of
the C++ output stream operations (`<<` and manipulators), which in turn are implemented based
on `printf` -- you can expect it to be 5 to 10 times slower than the latter, and it has
quite some compilation overhead.
quite some compilation overhead and size impact (-> see our own
link:http://git.lumiera.org/gitweb?p=lumiera/ichthyo;a=blob;f=src/lib/format-string.hpp;h=716aa0e3d23f09269973b7659910d74b3ee334ea;hb=37384f1b681f5bbfa7dc4d50b8588ed801fbddb3[formatting front-end]
to reduce this overhead)
.variant and any
These library provide a nice option for building data structures able to hold a mixture of

62
doc/technical/overview.txt
View file

@ -434,11 +434,33 @@ Library
The Lumiera support library contains lots of helper functionality
factored out from the internals and re-used. It is extended as we go.
practical shortcuts
~~~~~~~~~~~~~~~~~~~
The header 'lib/util.hpp' defines some shortcuts heavily used throughout
the code base. The idea is to highlight a common semantic meaning, while
hide differentiation on the technical details.
isnil:: indicate a _missing value_, irrespective if this is a NULL pointer,
an empty string or an empty container. Several of our custom wrappers also
support this notion.
contains:: indicate that a value is _somehow contained_ within a collection,
irrespective if this is a set, a map, a vector or string (substring test)
sanitise:: make any string usable as identifier.
In a similar vein, the header 'lib/util-foreach.hpp' provides a generic
``for-each-element'' mechanism, which works for all STL containers, but
also for all _Lumiera Forward Iterators_. The loop body is provided
as a functor. In case this functor is a predicate (boolean result),
the +and_all+ and +has_any+ functions allow to test for conjunction
and disjunction.
Locking
~~~~~~~
Based on object monitors. Performance critical code
uses mutexes, condition vars and rwlocks direcly.
General purpose Locking is based on object monitors. Performance critical code
in the backend uses mutexes, condition vars and rwlocks direcly.
Intentionally no semaphores.
- C++ locks are managed by scoped automatic variables
@ -661,6 +683,42 @@ Itertools
_tbw_
Front-end for boost::format
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Formatting values with `printf` is a notorious source for intricate errors.
Additionally, using (s|n)`printf` can be clunky in practice, and it doesn't
support custom defined string conversions, which are an important diagnostic
aid when working with objects. We might
link:{ldoc}/technical/howto/UsingBoost.html[use Boost], which provides the
`boost::format` library to address those problems. Unfortunately including this
header-only library solution incurs a significant overhead, both in terms of
compilation time and code size. While maybe still acceptable at the implementation
level, using boost::format is thus certainly a ``no go'' for any code residing
in headers frequently included.
To work around these problems, we provide a front-end wrapper, defined in
'lib/format-string.hpp'. This allows to keep the actual boost::format based
implementation confined to a single translation unit, while still being able
to use all primitive types as usual with boost::format or printf. Additionally,
our frontend automatically invokes a custom or built-in string conversion, if
applicable, it dereferences pointers and catches all errors encountered while
the formatting. So it's well suited for usage in error handling code.
[source,C]
------------------------------------------------------------
#include "lib/format-string.hpp"
using util::_Fmt;
double total = 22.9499;
const char * currency = "€";
cout << _Fmt("price %+5.2f %s") % total % currency << endl;
------------------------------------------------------------
WARNING: `boost::format` is known to be about 10 times slower than `printf` --
best to avoid it for performance critical code.
Wrappers and Opaque Holders
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.smart handle