Format

NAME
SYNOPSIS
DESCRIPTION
LIMITS
EXAMPLES
NOTES
INTERNALS
AUTHOR
SEE ALSO

NAME

format - typesafe string formating in printf style in C++

SYNOPSIS

#include <Format.hh>

std::string format( std::string format-string, ... );

class Format::Error { public: std::string err };

DESCRIPTION

The Format library supports formating messages in printf style, by being typesafe. The only function you have to use at this library is the format function.

format-string

The format string style is the same as printf(3) uses.

Return value

The function returns a std::string

Thrown errors

On an error the Format::Error class will be thrown. The only errors that are reportet, are mistakes on %*, %*m$, %.*, %.*m$,... (see printf(3) for details.)

For example, if you try to use a string as an integer:

cout << format( "%*d", "wrong", 5 ) << endl;

LIMITS

The number of values that are given to the format function after the format string is limited to 6

%n is not supported.

EXAMPLES

To print Pi to five decimal places:

#include <Format.hh>
#include <cmath.h>
#include <iostream>

try {
std::cout
    << format("pi = %.5f", 4 * std::atan(1.0))
    << std::endl;
} catch( Format::Error error ) {
  std::cout << "Error: " << error.err << std::endl;
}

The Format library is detecting itself the type of the parameters. This example will work without any problems. But if you try this with the printf function the programm will crash.

#include <Format.hh>
#include <iostream>

std::cout << format( "%s", 5 ) << std::endl;

NOTES

Since errors are only thrown if there is a parameter type mismatch you only have to use the try - catch mechanism if you are using a %*, or %.* format string. Cause only there a parameter has to be an integer.

Example

This will work:

std::cout << format("%0*f", 6, 32.32) << std::endl;

The output string will look like this:

32.320000

But this example will not work. It will throw an exception.

try{
  std::cout << format("%0*f", 32.32, 6)
            << std::endl;
} catch( Format::Error error ) {
  std::cout << "Error: " << error.err
            << std::endl;
}

The output string will look like this:.

Error: expecting int arg

format will try to use 32.32 as the field width, detects that this is not an integer value and will throw an exception.

Be careful, cause this example will also not work:

try{
  float f = 6;
  std::cout << format("%0*f", f, 32.32)
            << std::endl;
} catch( Format::Error error ) {
  std::cout << "Error: " << error.err
            << std::endl;
}

The output string will look like this:

Error: expecting int arg

format will never cast a value itself. You have to take care of the type of the values. The class uses a std::strstream. By overloading the << operator, user defined types can be converted to a string by the format class.

INTERNALS

Library

The main part of the library is a class template und a sub class. The sub class formats the std::ostream and this part of the code is really located at the dynamic library. The main part and the main work is done by the class template that is located in the header file Format.hh.

AUTHOR

King Leo (Martin Oberzalek) <kingleo@gmx.at>