1. Syntax


The "destination" is the part of the expression that defines where the content goes to and also the return type. Many destinations are supported and you can create your own one. However, for convenience, most code samples in this tutorial use to_string:

#include <strf/to_string.hpp>

void sample() {
    int x = 200;
    std::string str = strf::to_string(x, " in hexadecimal is ", strf::hex(x));
    assert(str == "200 in hexadecimal is c8");

You can see that there is no format string here, as there is in printf. Instead, format functions ( like hex above ) specify formatting. The expression strf::hex(x) is equivalent to strf::fmt(x).hex(). The return of strf::fmt(x) is an object containing the value of x in addition to format information which can edited with member ( format ) functions following the named paramenter idiom ( like this: strf::fmt(255).hex().p(4).fill(U'.') > 10 )

To use a translation tools like gettext, instead of operator(), you need to use the tr function, which employs what is called here as the tr-string:

auto s = strf::to_string.tr("{} in hexadecimal is {}", x, strf::hex(x));

The reserve, no_reseve and reserve_calc functions are only available for some destinations — those that allocate memory, which is the case of to_string. Using reserve(size) causes the destination to reserve enough space to store size characters. reserve_calc() has the same effect, except that it calculates the number of characters for you. Actually, reserve_calc() is currently the default, but this may change in future.

1.1. Facets

Finally, there is the with function, where you inject facet objects. Facets somehow complement format functions. Both aim to change how the data is printed. A facet example is the lettercase enumeration, which affects numeric and boolean values.

namespace strf {
  enum class lettercase { /* ... */ };
  constexpr lettercase lowercase = /* ... */;
  constexpr lettercase mixedcase = /* ... */;
  constexpr lettercase uppercase = /* ... */;
auto str_uppercase = strf::to_string.with(strf::uppercase)
    ( true, ' '*strf::hex(0xab), ' ', 1.0e+50 );

auto str_mixedcase = strf::to_string.with(strf::mixedcase)
    ( true, ' '*strf::hex(0xab), ' ', 1.0e+50 );

assert(str_uppercase == "TRUE 0XAB 1E+50");
assert(str_mixedcase == "True 0xAB 1e+50");

1.2. Constrained facets

You can constrain facets to a set of input types:

auto str = strf::to_string
    ( true, ' '*strf::hex(0xab), ' ', 1.0e+50 );

assert(str == "true 0xab 1E+50");

, or to a set of arguments:

auto str = strf::to_string
    ( true, ' ', 1.0e+50, " / "
    , strf::with(strf::uppercase) (true, ' ' 1.0e+50, " / ")
    , true, ' ', 1.0e+50 );

assert(str == "true 1e+50 / TRUE 1E+50 / true 1e+50 );

When there are multiple facets objects of the same category, the order matters. The later one wins:

auto fa = strf::mixedcase;
auto fb = std::constrain<std::is_floating_point>(strf::uppercase);

using namespace strf;
auto str_ab = to_string .with(fa, fb) (true, ' ', *hex(0xab), ' ', 1e+9);
auto str_ba = to_string .with(fb, fa) (true, ' ', *hex(0xab), ' ', 1e+9);

// In str_ab, fb overrides fa, but only for floating points
// In str_ba, ba overrides fb for all types, so fb has no effect.

assert(str_ab == "True 0xAB 1E+9");
assert(str_ba == "True 0xAB 1e+9");

1.3. Facets categories

But what does it mean for two facet objects to belong to same facet category? In this library, the term facet always refers to types. So the type strf::lettercase is a facet, while strf::uppercase is a facet value. In addition, a facet is always associated to one, and only one, facet category. However, several facets can "belong" to the same category.

For each facet category there is class or struct with a public static member function get_default() which returns the default facet value of such facet category. By convention, the name of such class or a struct is the name of the category, and it has the “_c” suffix. For example, the category of strf::lettercase is strf::lettercase_c, and strf::lettercase_c::get_default() returns strf::lowercase.

Informaly ( perhaps in future it will be formal thanks to C++20 Concepts ) for each facet category there is a list of requirements a type must satisfy to be a facet of the category. In the case of strf::lettercase_c, the requirement is, well, to be the strf::lettercase type, since this is only facet of this category by design. However other categories require the facet to contain member functions with specified signatures, effects, preconditions, posconditions and so on.

The design of the facets varies a lot according to their categories. But all facets currently available in the library have something in common: they all are small types ( in terms of sizeof() ) and provide a fast copy constructor. In addition, most of them can be instantiated as constexpr values.

In case you are wondering, the library uses the facet_traits struct template to get the category the facets.

1.4. Facets packs

To avoid retyping all the facets object that you commonly use, you can store them into a facets_pack, which you create with the pack function template:

constexpr auto my_facets = strf::pack
    ( strf::mixedcase
    , std::constrain<strf::is_bool>(strf::uppercase)
    , strf::numpunct<10>{3}.thousands_sep(U'.').decimal_point(U',')
    , strf::numpunct<16>{4}.thousands_sep(U'\'')
    , strf::windows_1252<char>() );

auto str1 = strf::to_string.with(my_facets) (/* ... */);
// ...
auto str2 = strf::to_string.with(my_facets) (/* ... */);
// ...

Any value that can be passed to the with function, can also be passed to pack, and vice-versa. This means a facets_pack can contain another facets_pack.

So the expression:

destination .with(f1, f2, f3, f4, f5) (/* args... */);

is equivalent to

destination .with(strf::pack(f1, strf::pack(f2, f3), f4), f5) (/* args... */);

It is also equivalent to:

destination .with(f1).with(f2).with(f3).with(f4).with(f5) (/* args... */);

1.5. Locales

Strf is a locale-independent library. When you don’t specify any facet object, everything is printed as in "C" locale. However, the header <strf/locale.hpp> provides the function locale_numpuct that returns a numpunct<10> object that reflects the numeric punctuation of the current locale ( decimal point, thousands separator and digits grouping ). locale_numpunct() is not thread safe. Actually using locales in general is not thread safe. However, once you store its returned value into a facet object, that object is not affected anymore when the locale changes.

#include <strf/locale.hpp>
#include <strf/to_string.hpp>

void sample() {
    if (setlocale(LC_NUMERIC, "de_DE")) {
        const auto punct_de = strf::locale_numpunct();
        auto str = strf::to_string.with(punct_de) (*strf::fixed(10000.5))
        assert(str == "10.000,5");

        // Changing locale does not affect punct_de
        // So using it is thread safe
        setlocale(LC_NUMERIC, "C");
        auto str2 = strf::to_string.with(punct_de) (*strf::fixed(20000.5));
        assert(str2 == "20.000,5");

2. Other destinations

Up to here, we only covered things that define the content to be printed, not where it is printed. Strf provides other expressions besides to_string to select the destination. Many of them are overloads of the to function template. You can just replace the to_string expression by to(dest), where dest can be, for example, an array of char:

#include <strf.hpp> // another header !

void sample() {
    int x = 200;
    char buff[200];
    auto res = strf::to(buff) (x, " in hexadecimal is ", strf::hex(x));
    assert(0 == strcmp(buff, "200 in hexadecimal is c8");
    assert(strlen(buff) == (res.ptr - buff));
    assert( ! res.truncated);

    //now with a buffer that is too small
    char small_buff[16];
    auto res = strf::to(small_buff) (x, " in hexadecimal is ", strf::hex(x));
    assert(res.ptr == small_buff + 15);
    assert(*res.ptr == '\0');
    assert(0 == strcmp(small_buff, "200 in hexadeci");

However, there is another overload of to that deserves a special mention: the one that writes to basic_outbuff:

namespace strf {

template <typename CharT>
class basic_outbuff;

using     outbuff = basic_outbuff<char>;
using   u8outbuff = basic_outbuff<char8_t>;
using  u16outbuff = basic_outbuff<char16_t>;
using  u32outbuff = basic_outbuff<char32_t>;
using    woutbuff = basic_outbuff<wchar_t>;
using bin_outbuff = basic_outbuff<std::byte>;

template <typename CharT>
/* ... */ to(strf::basic_outbuff<CharT>&);


For every destination, there is a concrete class that derives from the basic_outbuff abstract class template. For example, when you use to_string, the library internally instantiates a string_maker. In the case of writting to a raw string, it is a cstr_writer.

So the statement:

std::string str = strf::to_string(arg1, arg2, arg3, arg4);

is equivalent to:

strf::string_maker str_maker;
strf::to(str_maker) (arg1, arg2, arg3, arg4);
std::string str = str_maker.finish()

What makes the second form so interesting is that it doesn’t impose you to pass all arguments in a single statement. So you have the same flexibility as when writting into a std::ostream:

strf::string_maker str_maker;
auto print = str_maker.with(f1, f2, f3);

if (condition1) {
    print(arg1, arg2);
while (condition2) {
    print(arg3, arg4, arg5);
print.with(f4) (arg6, arg7);
// ...
auto str = str_maker.finish()

Another reason to use basic_outbuff is when you don’t want to commit yourself to a destination type. Suppose you need to create a function that provides a textual message whose content and size are known only at run time.

Instead of returning a string object:

std::string get_message();

, or writting to caller-supplied char*:

void get_message(char* dest, std::size_t dest_size);

, you can design your function like this:

void get_message(strf::outbuff& dest);

This way you let the caller to decide which outbuff implementation to use. It could be the string_maker or cstr_writer or another one. There is no significant performance difference between writing into a cstr_writer and directly into a char*.

However, when writing to a string — either a raw string or a std::string — note that such string need to be further sent to some other destination — a file, a log system, or whatever — otherwise it is useless, right? So what the caller can also do is to implement a new outbuff that writes directly into such final destination, thus avoiding both heap allocation and the risk of content trucation.

3. Error handling policy

Strf does not throw exceptions. When there is something wrong, the usual approach is the library to print the replacement character ( or the question mark when the encoding can’t represent it ). There are two situations when this can happen: when using the tr-string and when converting a string from one encoding to another ( see encoding conversion ). In addition, for each of these cases there is a facet category (tr_error_notifier_c and invalid_seq_notifier_c) that enables you to specify a callback that is called in the error events, which can thus throw an exception if you want.

4. What’s next ?

The quick reference should explain most of things you need know about the library. This is the document you will probably use most of the time.

For more specific things, there are the header references:


This is lighweight header can be used in freestanding environments and is the cornerstone of library. All other headers include it.


Defines most of the library, including the main usage syntax , all printable types and all facets.


Provides utilities to write to std::basic_string. Includes <strf.hpp>.


Provides utilities to write to std::basic_streambuf. Includes <strf.hpp>.


Provides utilities to write to FILE*. Includes <strf.hpp>.