GitHub access

FastFormat GitHub access now at: https://github.com/synesissoftware/FastFormat

Fork away!

FastFormat 0.7.1 released

FastFormat is an Open Source C/C++ Output/Formatting library, whose design parameters are 100% type-safety, efficiency, genericity and extensibility. It is simple to use and extend, expressive, flexible, and highly-portable (platform and compiler-independent).

FastFormat supports output/formatting of statements of arbitrary complexity, consisting of heterogeneous types.

FastFormat writes to output "sinks", which can be of arbitrary type. It implicitly supports any type that is structurally conformant with the standard library's string, and the library includes adaptors to allow writing to std::ostream, FILE*, speech (currently Windows-only), STLSoft's auto_buffer, C-style string buffers, and character buffers. Adaptation to a new type merely requires the definition of a single function.

FastFormat is robust. Both APIs are 100% type-safe - something neither IOStreams nor Boost.Format can claim - and with the Write API it is impossible to compile defective code.

FastFormat is fast. The processing of each statement involves at most one memory allocation to hold the entire statement, and each statement element is measured and copied exactly once. As a consequence, the library is on a par with (the type-unsafe) C's Streams (printf()-family) of functions, faster than C++'s IOStreams (by 2-5x) and Loki.SafeFormat (by 1-5x), and considerably faster than Boost.Format (by 5-17x).

FastFormat supports I18N/L10N by using numbered arguments, enabling reordering of arguments by exchanging format strings. The library comes with a number of resource bundles, classes whose instances can load sets of localised resource strings for use as format strings.

FastFormat does not contain any compiler-specific or platform-specific constructs. It supports UNIX (including Linux and Mac OS-X), and Windows, and should work with any operating system. It is known to be compatible with Clang, Comeau (4.3.3+), GCC (3.4+), Intel (8+), Metrowerks (8+), Microsoft Visual C++ (6.0+), and should work with any reasonably modern C++ compiler.

FastFormat is completely free and includes source released under a BSD-style license. Commercial customisations and related consultancy are provided by Synesis Software Pty Ltd; http://synesis.com.au/contact.html\)

FastFormat Training is provided by Synesis Software Pty Ltd; details at http://synesis.com.au/training.html

Release 0.7.1 contains the following changes:
Clang-compatibilityVC++ 11/12/14-compatibility
NOTE: bundles shwild 0.10.1NOTE: bundles xTests 0.18.3
* NOTE: depends on STLSoft 1.9.121 (not bundled)
Download from: http://sourceforge.net/projects/fastformat/files/fastformat/
Discuss at: http://sourceforge.net/forum/forum.php?forum_id=612781
Donate at: http://sourceforge.net/project/project_donations.php?group_id=177382
FastFormat website: http://fastformat.org/
Note: this release of FastFormat requires STLSoft 1.9.121, or later. Download from http://stlsoft.org/

Wide String Shims for std::exception

The new release of STLSoft supports seamless use of exceptions with FastFormat (and Pantheios) in wide-string builds; described on this post on the STLSoft project blog.

fmt::flush

As discussed in the latest instalment of Quality Matters, having flushing output streams and verifying their status is a pre-requisite of writing a robust program. Doing this with the IOStreams is a somewhat onerous task; see the column for details. Using the new flush() function, introduced in version 0.6.2, makes doing so with FastFormat a breeze, as in:

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

#include <iostream>

int main()
{
 ff::flush(ff::writeln(std::cout, "Hello, world!"));

 return 0;
}

FastFormat 0.6.2 released

I've just released version 0.6.2 of FastFormat, containing a number of improvements and several new features, which will be detailed in a series of forthcoming posts on this blog. The new features include the flush() function, whose purpose and behaviour is described in the latest instalment of my Quality Matters column in October's instalment of ACCU's Overload.

FastFormat 0.6.1 (alpha 1) released

I'm currently releasing version 0.6.1 (alpha 1) of FastFormat. Although 0.6 will contain a number of new additions, the first alpha release contains no functional changes. It's entirely about releasing some performance improvements that I've had in the bag for a long time, but keep overlooking.

The reason I'm doing so now is, in part, that there's been a thread on the FastFormat Help Forum concerning one potential user's assertion that FastFormat (and some of the STLSoft components upon which it relies) is not as quick as my previous claims have indicated. Thankfully, it was easy to perform some simple tests and ascertain that, so far, nothing's overtaken it in terms of performance. In one of the tests I added FastFormat (both write() and fmt()) and STLSoft's integer_to_string to an integer-to-string conversion test that included, amongst other things, Boost.Spirit.Karma. I'm pleased to report - with Visual C++ 9, at least (haven't had time to use other compilers yet) - that FastFormat holds its own, and with the new optimisations in 0.6 it is the fastest of the possible format components, including ~10% faster than Karma.

The only thing faster is the low-level stlsoft::integer_to_string() function that FastFormat uses internally, which is a good 30-40% faster than the rest. (Not that I'd advocate using it in application code, of course, since it's not so expressive, and requires pointer and buffer-length parameters.)

I owe thanks to the OP for causing me to look again and confirm FastFormat's performance advantages, and to release the long-awaited optimisations.

FastFormat 0.5.8 released

FastFormat 0.5.8 is released, containing a fix to ensure that a replacement parameter with a maximum width of 0 truncates (completely) the resulting field. For example:

    string_t sink;

    ff::fmt(sink, "{0,,0}", "abc");

    assert("" == sink);

format_iterator on Dr Dobb's

Dr. Dobb's have just published a new article, "C++ and format_iterator", describing the design and implementation of the FastFormat library's format_iterator component.

The article describes how FastFormat's flexiblity, expressiveness and type-safety has been combined with the output iterator concept  to produce the fastformat::format_iterator component. Applying STL-extension techniques described in Extended STL, volume 1, the format_iterator() component is able to create an output iterator that can receive arbitrate types, apply a format string or arbitrary complexity, and write to an arbitrary sink, as in:

 #include <fastformat/ff.hpp>
 #include <fastformat/iterators/format_iterator.hpp>
 #include <fastformat/sinks/ostream.hpp>

 int          numbers[] = { -2, -1, 0, 1, 2 };
 char const*  strings[] = { "abc", "def", "ghi" };
 std::string  prefix = "\t";
 char const*  suffix = "\n";


 std::copy(
   numbers, numbers + 5
 , ff::format_iterator(std::cout, "[{0}]"));

 // outputs "[-2][-1][0][1][2]"


 std::copy(
   strings, strings + 3
 , ff::format_iterator(std::cout, "{1}'{0}'{2}", prefix, suffix));

 // outputs:
 //     'abc'
 //     'def'
 //     'ghi'


This is the fourth article on the FastFormat library, following on from the introductory series of three published in ACCU's Overload magazine:

• An Introduction to FastFormat, part 1: The State of the Art
• An Introduction to FastFormat, part 2: Custom Argument and Sink Types
• An Introduction to FastFormat, part 3: Solving Real Problems, Quickly

Beware of the \r\n gotcha on Windows

If (as I have just done) you decide to FastFormat to prepare intermediate text for output, and your program runs on Windows, beware of the writeln() and fmtln() API functions. Consider the following code

std::string s;

ff::writeln(s, "hello"); // s => "hello\r\n"

ff::write(std::cout, s); // writes "hello\r\r\n"

This occurs because the underlying C standard library expands each standard end-of-line (EOL) character \n to the Windows-specific EOL sequence \r\n.

Instead, use the *ln() functions on the output, as in:

ff::write(s, "hello"); // s => "hello"

ff::writeln(std::cout, s); // writes "hello\r\n"

Remember that FastFormat "appends" to sinks

A user recently posted a note on the Help forum, suggesting that FastFormat was up to 100 times slower than MFC's CString::Format(). Thankfully that's not the case, and FastFormat appears to be faster than CString::Format() in even the simple case suggested.

The reason this appeared to be so was because the test program reused the same CString instance in each call to fastformat::fmt(), resulting in concatenation to a huge size. The fault here is no doubt mine, for not having made the nature of FastFormat's formatting more clear in the documentation. So I'll try and do so briefly now.


All FastFormat formatting is appending, and this is a deliberate design decision. In part, this is to achieve consistency between immediate sinks such as strings, and stream sinks (such as std::cout, stdout, ...). Also, it's useful to be able to break apart large or complex formatting operations into statements, without sacrificing performance or expressiveness. (Note: there'll always a small performance penalty for such things, but it will be insignificant in most cases where the size and complexity of the statement demands breaking up.) Consider the following example:

std::string s;

ff::fmt(s, "{0};{1};{2}|{3};{4};{5}|{6};{7};{8}|{9};{10};{11}|", a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11);

The same can be achieved as follows:

std::string s;

ff::fmt(s, "{0};{1};{2}|", a0, a1, a2);

ff::fmt(s, "{0};{1};{2}|", a3, a4, a5);

ff::fmt(s, "{0};{1};{2}|", a6, a7, a8);

ff::fmt(s, "{0};{1};{2}|", a9, a10, a11);

In real-world cases, such clarity may be worth paying a few more extra cycles for.

Sink creator function

Just started working on a creator function, called to_sink(), which will allow sinks to be generated in situ from free functions. A little like a bind, just not as complicated (I hope).

An example of use would be:

std::copy(files.begin(), files.end()
  , ff::format_iterator(ff::to_sink(::OutputDebugString)

                      , "\t{0}\n"));

Hopefully I should have something releasable in the next week or so.

FastFormat 0.5.4 released: VC++ 10 support

FastFormat now supports Visual C++ 10. Note that it requires STLSoft 1.9.96 (or later).

VC++ 10 support imminent

Currently adding VC++ support to STLSoft. Should have FastFormat up and working automatically.

FastFormat 0.5.3 released

Just released the latest version of FastFormat, fixing some minor compilation defects encountered on Fedora.

The problem was my omission of an explicit inclusion of limits.h, required for use of INT_MIN (and INT_MAX) in test.component.inserter.integer.cpp and test.scratch.inserter.integer.cpp. Now fixed.

Thanks to yozara.

FastFormat 0.5.1 (alpha 1) released

The latest version of FastFormat, 0.5.1 (alpha 1), is released. Along with a bunch of minor changes, the main addition is the support for hex integer conversion, via to_x()/to_X(), as in:

    ff::fmtln(stm, "i={0}", ff::to_x(123456)); // i=1e240
    ff::fmtln(stm, "i={0}", ff::to_x(123456, 0, 10)); // i=000001e240

and, if you want it uppercase:


    ff::fmtln(stm, "i={0}", ff::to_X(123456)); // i=1E240
    ff::fmtln(stm, "i={0}", ff::to_X(123456, 0, 10)); // i=000001E240

Now accepting donations

FastFormat is production-quality software. If you find FastFormat useful, you are asked to make a modest donation, to ensure that the project continues to be supported and enhanced.

FastFormat introductory article series #3 published in Overload

The June issue of the ACCU's Overload magazine contains An Introduction to FastFormat, part 3: Solving Real Problems, Quickly. This is the third in a series of three articles about FastFormat that examine the current alternatives in C++ formatting, and demonstrate how FastFormat provides an optimal mix of robustness, efficiency, flexibility, expressiveness and other software quality measures.

Starting off ...

Just a first post to get us started.

This blog is going to be about the day-to-day work involved in the FastFormat project.

The current release line is 0.3, and the latest version, 0.3.5 offers production quality support for built in. Read more about it here.

There aren't many more plans for 0.3, except perhaps to add a makefile for Mac OS-X 64-bit.

Then new things will be on the cards with 0.4 ...

FastFormat introductory article series #2 published in Overload

The April issue of the ACCU's Overload magazine contains An Introduction to FastFormat, part 2: Custom Argument and Sink Types. This is the second in a series of three articles about FastFormat that examine the current alternatives in C++ formatting, and demonstrate how FastFormat provides an optimal mix of robustness, efficiency, flexibility, expressiveness and other software quality measures.

FastFormat introductory article series #1 published in Overload

The February issue of the ACCU's Overload magazine contains An Introduction to FastFormat, part 1: The State of the Art. This is the first in a series of three articles about FastFormat that examine the current alternatives in C++ formatting, and demonstrate how FastFormat provides an optimal mix of robustness, efficiency, flexibility, expressiveness and other software quality measures.