The formatters here simply format various input types to a specified text format. They can be used with most streaming types (including both ecl and stl streams).
The formatters here simply format various input types to a specified text format. If you wish to just do fast type to text conversion without formatting, use the converters supplied in ecl_utilities.
Type to text formatting is usually bundled with both streaming and
device manipulation. Although this makes it very simple to do the
most basic of type formatting, it also has the unfortunate consequence
in that the formatter types (printf, sprintf, iostreams) are very
heavyweight and subsequently slow. Especially for a simple task, they
bring a sledge hammer when all that is needed is a gentle push.
What the formatters attempt to do is to split the functionality
of formatting from the concepts of device manipulation,
streaming. This ensures that any simple task is not overdone with a
heavyweight object (really important for logging) and it greatly enhances
the efficiency and speed. The classes here also bring in type safety,
something which is not guaranteed by either printf or sprintf.
Include the following at the top of any translation unit which
requires this library:
You will also need to link to -lecl_formatters.
Formatters are functors - functions with state. You instantiate a formatter
type and then make use of it as if it were a function call.
The format parameters can be changed singly with appropriately named
setters, or collectively via:: a bundled operator () call. Sometimes
common combinations are also provided with a convenient setter via the operator ().
Changing the format parameters in this way will set the default formatting for any input values given to the formatter in the future.
The formatters are primarily intended to be used with streams. For convenience
they have been designed to be used with any stream that implemenents the
<< operator. Subsequently they are useful with either TextStreams (ECL-IO) or
the usual c++ streams. When used in conjunction with TextStreams they provide
a very fast streaming interface.
To format with the parameters stored in the formatter, you simply
provide the formatter with the input value. Note that the formatter will
only accept a value of the type specified in the formatter's template
argument.
For convenience, you can also change the format parameter on the fly (this is recorded permanently).
Occasionally you will only need to change the format for one instance.
To effect a temporary change in this way, supply the input value
along with the specified formatting options.
Always check the formatter's interface to see what setters are
available to the type you wish to format. Although there are common
formatting parameters, they are few and these will usually vary from type
to type.
Some results from tests on a 64 bit gentoo installed on a dual core II computer
while formatting both integer and float types indicate that when used in conjunction
with TextStream, the formatters are 7-30x faster than their printf and
iostream equivalents (which perform roughly as well as each other).
Run the test program for evaluation on your machine.
There are some awkward aspects of streaming that make it difficult for the formatters to
function perfectly. Without going into the details, there are various issues with
the unspecifiedness of function arguments that mean its impossible to format several
objects on the same line differently, and expect the result to come back in the
correct order. I haven't currently got a solution for this, so there are two
options:
- 1) Leave the formatters as they are and ensure that only one
formatter is used on each line (abort/throw if this occurs), or
- 2) Push the formatters back into TextStream.
The second option is no good - it just turns TextStream into a heavyweight iostream.
A priority for us is fast logging, so we must keep TextStream lightweight and since
1) is merely a coding style issue, that's easy to handle so long as we are aware of
it.
In debug mode, formatters use an exception throwing assert to check that multiple formatters aren't used in the one line when streaming.
Formatters cover all the basic fundamental types (char, float, double, int...). They
also cover a few special types, including arrays - refer to the documentation for ecl_containers
for more information.
Formatters must implement
- Formatting setters
- Input value operator
- Temporary formatting operators
- Streaming friend function
Note that the setters and operators must return the formatter so that the friend function can implement the formatting.
For the Format<Type> class to automagically find this formatter, you can implement one of two methods. If you have access to the class's internals, simply typedef it as "Formatter" inside the class, otherwise simply specialise the Format<> class for your type and inherit the formatter.
Each standard formatter is a template specialisation of the form Format<inputType> where the available input types are:
- integral types (char, short, int, long, long long and their unsigned equivalents)
- float types (float, double)
- string
- fixed size arrays/stencils
Note, as with any string based object, avoid it if you need speed with your streaming.
- src/examples/formatters.cpp : not a google unit test, but does coverage.
- <b>Sep 10</b> : Moved container arrays to the ecl_containers class. - <b>Mar 10</b> : Char stencils can now use the same formatter as their underlying array. - <b>May 09</b> : Added width formatting capabilities to float containers. - <b>May 09</b> : Added formatters for fixed size char, float and double arrays. - <b>May 09</b> : Fixed speed issues by converting to an underlying snprintf implementation (temp. hack). - <b>May 09</b> : Added formatters for fundamental number types and strings.