Format(3)

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>

SEE ALSO
printf(3)