Lumiera  0.pre.03
»edityourfreedom«
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
format-string.hpp File Reference

Go to the source code of this file.

Description

Front-end for printf-style string template interpolation.

While the actual implementation just delegates to boost::format, this front-end hides the direct dependency, additionally invokes a custom toSting conversion whenever possible, provides a direct automatic conversion to the formatted result to string and catches any exceptions.

This front-end is used pervasively for diagnostics and logging, so keeping down the compilation and object size cost and reliably handling any error is more important than the (small) performance gain of directly invoking boost::format (which is known to be 10 times slower than printf anyway).

Implementation notes

To perform the formatting, usually a _Fmt object is created as an anonymous temporary, but it may as well be stored into a variable. Copying is not permitted. Individual parameters are then fed for formatting through the '' operator. Each instance of _Fmt uses its own embedded boost::format object for implementation, but this formatter resides within an opaque buffer embedded into the frontend object. The rationale for this admittedly tricky approach is to confine any usage of boost::format to the implementation translation unit (format-string.cpp).

The implementation is invoked by the frontend through a set of explicit specialisations for all the relevant primitive data types. For custom types, we prefer to invoke operator string() if possible, which is determined by a simple metaprogramming test, which is defined in lib/meta/util.pp, without relying on boost. As a fallback, for all other types without built-in or custom string conversion, we use the mangled type string produced by RTTI.

The compile time and object size overhead incurred by using this header was verified to be negligible, in comparison to using boost::format. When compiling a demo example on x86_64, the following executable sizes could be observed:

                                     |debug | stripped

-------------------------------------—:|-—: | —: just string concatenation ... | 42k | 8.8k including and using format-string.hpp ...| 50k | 9.4k including and using boost::format ... | 420k | 140k

In addition, we need to take the implementation translation unit (format-string.cpp) into account, which is required once per application and contains the specialisations for all primitive types. In the test showed above, the corresponding object file had a size of 1300k (with debug information) resp. 290k (stripped).

Usage

The syntax of the format string is defined by boost::format and closely mimics the printf formatting directives. The notable difference is that boost::format uses the C++ stream output framework, and thus avoids the perils of printf. The individual formatting placeholders just set the corresponding flags on an embedded string stream, thus the actual parameter types cause the selection of a suitable format, not the definitions within the format string.

An illegal format string will raise an error::Fatal. Any other error during usage of the formatter is caught, logged and suppressed, inserting an error indicator into the formatted result instead

A formatter is usually created as an anonymous object, at places where a string is expected. An arbitrary number of parameters is then supplied using the '' operator. The result can be obtained

  • by string conversion
  • by feeding into an output stream.

Code example:

double total = 22.9499;
const char * currency = "€";
cout << _Fmt("price %+5.2f %s") % total % currency << endl;
Remarks
See the unit-test for extensive usage examples and corner cases. The header format-obj.hpp provides an alternative string conversion, using a bit of type traits and boost lexical_cast, but no boost::format.
Warning
not suited for performance critical code. About 10 times slower than printf.
See also
FormatString_test
format-util.hpp
format-obj.hpp

Definition in file format-string.hpp.

#include "lib/error.hpp"
#include "lib/nocopy.hpp"
#include "lib/meta/util.hpp"
#include "lib/meta/size-trait.hpp"
#include <string>

Classes

class  _Fmt
 A front-end for using printf-style formatting. More...
 
singleton  basic_ostream< Char >
 STL class.
 
struct  char_traits< C >
 
struct  _Fmt::Converter< VAL, SEL >
 helper to prepare parameters for inclusion More...
 
struct  _Fmt::Converter< VAL, SEL >
 helper to prepare parameters for inclusion More...
 
struct  _Fmt::Converter< bool >
 
struct  _Fmt::Converter< const char * >
 
struct  _Fmt::Converter< lib::Literal >
 
struct  _Fmt::Converter< lib::Symbol >
 
struct  _Fmt::Converter< SP, lib::meta::enable_if< _shall_show_smartWrapper< SP > > >
 
struct  _Fmt::Converter< VAL * >
 
struct  _Fmt::Converter< VAL, lib::meta::enable_if< _shall_convert_toString< VAL > > >
 some custom types explicitly provide a string representation More...
 
struct  _Fmt::Converter< VAL, lib::meta::enable_if< _shall_format_directly< VAL > > >
 some basic types are directly forwarded down to the implementation; More...
 
struct  _Fmt::Converter< void * >
 

Typedefs

typedef unsigned char uchar
 

Functions

 LUMIERA_ERROR_DECLARE (FORMAT_SYNTAX)
 "Syntax error in format string for boost::format" More...
 
bool operator== (_Fmt const &left, _Fmt const &right)
 
bool operator== (_Fmt const &fmt, string const &str)
 
bool operator== (_Fmt const &fmt, const char *const cString)
 
bool operator== (string const &str, _Fmt const &fmt)
 
bool operator== (const char *const cString, _Fmt const &fmt)
 

Namespaces

 lib
 Implementation namespace for support and library code.
 
 util