Synesis Software STLSoft - ... Robust, Lightweight, Cross-platform, Template Software ...

What is FastFormat?

Version 0.4.4

Introduction | License | Authors
Installing FastFormat | Building the library for your compiler(s) | Portability and Dependencies
Examples | Training | Contact & Feedback

Introduction

FastFormat is a flexible, efficient, C++ output/formatting library that eliminates the problems suffered by existing standard and third-party libraries: lack of type-safety, lack of speed, lack of I18N/L10N support

It is able to work in format (fmt()) or write (write()) mode, as in:

  #include <fastformat/fastformat.hpp>
  #include <fastformat/sinks/ostream.hpp>

  // prints: "This formats the remaining arguments based on their order - in this case we put 1 before zero, followed by 1 again"
  fastformat::fmt(std::cout, "This formats the remaining arguments based on their order - in this case we put {1} before {0}, followed by {1} again", "zero", 1);

  // prints: "This writes each argument in the order, so first zero followed by 1"
  fastformat::write(std::cout, "This writes each argument in the order, so first ", "zero", " followed by ", 1);

More and better examples will be provided soon. For the moment, consider the following program, which demonstrates some of the modes of the library:

int main()
{
    // Case 1:
    //

    {
        std::string             sink;

        char const*             arg0    =   "arg0";
        std::string             arg1    =   "arg1";
        int                     arg2    =   10;

        sink.erase();
        fastformat::fmt(sink, "A c-style string: {0}", arg0);

        sink.erase();
        fastformat::fmt(sink, "A std::string: {0}", arg1);

        sink.erase();
        fastformat::fmt(sink, "A c-style string: {0}, and a std::string: {1}", arg0, arg1);

        sink.erase();
        fastformat::fmt(sink, "A c-style string: {1}, and an int: {0}", arg2, arg0);
    }

    // Case 2:
    //

    {
        stlsoft::simple_string  sink;

        std::string             fmt0("A c-style string: {0}");
        std::string             fmt1("A std::string: {0}");
        std::string             fmt2("A c-style string: {0}, and a std::string: {1}");
        std::string             fmt3("A c-style string: {1}, and an int: {0}");

        char const*             arg0    =   "arg0";
        std::string             arg1    =   "arg1";
        int                     arg2    =   10;

        sink.clear();
        fastformat::fmt(sink, fmt0, arg0);

        sink.clear();
        fastformat::fmt(sink, fmt1, arg1);

        sink.clear();
        fastformat::fmt(sink, fmt2, arg0, arg1);

        sink.clear();
        fastformat::fmt(sink, fmt3, arg2, arg0);
    }

    // Case 3:
    //

    {
        std::ostream&           sink = std::cout;

        std::string             fmt0("A c-style string: {0}");
        std::string             fmt1("A std::string: {0}");
        std::string             fmt2("A c-style string: {0}, and a std::string: {1}");
        std::string             fmt3("A c-style string: {1}, and an int: {0}");

        char const*             arg0    =   "arg0";
        std::string             arg1    =   "arg1";
        int                     arg2    =   10;

        sink.clear();
        fastformat::fmtln(sink, fmt0, arg0);

        sink.clear();
        fastformat::fmtln(sink, fmt1, arg1);

        sink.clear();
        fastformat::fmtln(sink, fmt2, arg0, arg1);

        sink.clear();
        fastformat::fmtln(sink, fmt3, arg2, arg0);
    }

#ifdef __AFX_H__
    // Case 4:
    //

    {
        CString                 sink;

        stlsoft::simple_string  fmt0("A c-style string: {0}");
        stlsoft::simple_string  fmt1("A stlsoft::simple_string: {0}");
        stlsoft::simple_string  fmt2("A c-style string: {0}, and a stlsoft::simple_string: {1}");
        stlsoft::simple_string  fmt3("A c-style string: {1}, and an int: {0}");

        char const*             arg0    =   "arg0";
        CString                 arg1    =   "arg1";
        int                     arg2    =   10;

        sink.Empty();
        fastformat::fmt(sink, fmt0, arg0);

        sink.Empty();
        fastformat::fmt(sink, fmt1, arg1);

        sink.Empty();
        fastformat::fmt(sink, fmt2, arg0, arg1);

        sink.Empty();
        fastformat::fmt(sink, fmt3, arg2, arg0);
    }
#endif /* __AFX_H__ */

#ifdef PLATFORMSTL_OS_IS_WINDOWS
    // Case 5:
    //

    {
        std::ostream&           sink = std::cout;

        comstl::variant         fmt0( "A c-style string: {0}");
        comstl::variant         fmt1(L"A VARIANT: {0}");
        comstl::variant         fmt2( "A c-style string: {0}, and a VARIANT: {1}");
        comstl::variant         fmt3(L"A c-style string: {1}, and an unsigned short: {0}");

        char const*             arg0    =   "arg0";
        comstl::variant         arg1    =   "arg1";
        unsigned short          arg2    =   10;

        fastformat::fmt(sink, fmt0, arg0);

        fastformat::fmt(sink, fmt1, arg1);

        fastformat::fmt(sink, fmt2, arg0, arg1);

        fastformat::fmt(sink, fmt3, arg2, arg0);
    }
#endif /* OS */

    return EXIT_SUCCESS;
}

License

FastFormat is released under the simplified BSD license, which basically means its free for any use, but you can't claim it's yours.

Authors

FastFormat is written by Matthew Wilson. Matthew is an author and development consultant.

Installing FastFormat

The distribution is in the form of a zip file, e.g. fastformat-0.4.1.zip which you should extract (recursively) to a location of your choice, e.g. c:\opensrc\fastformat\0.4, or ~/opensrc/fastformat/0.4, and we recommend that you define the FASTFORMAT_ROOT environment variable to be this directory.

FastFormat depends on one other project, STLSoft, which is 100% header-only. If you wish to build the example and test programs included in the distribution using the makefiles supplied, you will need to have defined the STLSOFT environment variable to be the root directory of the STLSoft include files.

Building the library for your compiler(s)

Via makefile

Makefiles for all the main supported compilers are included in the subdirectories of the build directory. For example, the makefile for Borland C/C++ v5.6 is in build/bc56. Since Borland is only supported on Windows, there is a single makefile called makefile.

Hence, to build FastFormat for Borland C/C++ 5.6 you need open a Windows command box (with the environment set up for the compiler and linker) and execute the following command:

  <FASTFORMAT-install-dir>\build\bc56> make -f makefile

or just:

  <FASTFORMAT-install-dir>\build\bc56> make

Note:
For compilers that are supported on more than one platform, there are several makefiles located in the build sub-directory. For example, for GNU C/C++ v3.4 (in <FASTFORMAT-install-dir>/build/gcc34) both makefile.unix and makefile.win32 are provided. Most make tools require that you explicitly specify the makefile name (using -f) to use such makefiles, e.g. make -f makefile.unix.

With the Visual C++ 6.0 project files

Also included are Visual C++ 6.0 project files for the libraries and example and test programs. These files can be read (and converted) by any later version of Visual C++.

Just open the workspace file FastFormat.vc6.dsw, located in the root directory (i.e. <FASTFORMAT-install-dir>), and select the Build-All option.

Note:
You need to have the STLSOFT environment variable set up correctly.

Portability and Dependencies

FastFormat is written in standard C++, and should be compilable with any modern C/C++ compiler that provides an implementation of the C & C++ standard libraries.

The implementation of FastFormat is dependent on the following open-source libraries:

In addition, the following open-source libraries are required by one the test programs, and are bundled in with the FastFormat distribution:


FastFormat Library documentation Matthew Wilson, 2006-2009 SourceForge.net Logo