- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages
- Examples

# What is FastFormat?

### Version 0.6.1-alpha-1

Introduction | License | Authors | Donations
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:
        //
    sink:      std::stringformat:    C-style stringarguments: C-style string, std::string, int

        {
            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:
        //
    sink:      stlsoft::simple_stringformat:    std::stringarguments: C-style string, std::string, int

        {
            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:
        //
    sink:      std::coutformat:    std::stringarguments: C-style string, std::string, int

        {
            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:
        //
    sink:      CStringformat:    stlsoft::simple_stringarguments: C-style string, CString, int

        {
            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:
        //
    sink:      std::coutformat:    VARIANTarguments: C-style string, VARIANT, unsigned short

        {
            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.

## Donations

If you value the diligence and effort that's gone into bringing you this production-quality software, please make a donation to the project, via:

http://sourceforge.net/project/project_donations.php?group_id=177382

## 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:

- STLSoft, version 1.9.79, or later. STLSoft is used for compiler discrimination, detection of language feature support, contract programming primitives, and an implementation of the shared_ptr class template. STLSoft is a 100% header-only library, so there is no requirement to have STLSoft installed in order to use FastFormat.

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

- xTests, version 0.12.1, or later. xTests is a unit-/component-testing library.
- shwild, version 0.9.18, or later. shwild is a pattern matching library.

FastFormat Library documentation © Matthew Wilson, 2006-2009 |