Overview — fmt 6.2.1 documentation
Author: Victor Zverovich
Description: Small, safe and fast formatting library
Keywords: C++, formatting, printf, string, library

# {fmt}

A modern formatting library

Download

# Overview

{fmt} is an open-source formatting library providing a fast and safe alternative to C stdio and C++ iostreams.

What users say:
Thanks for creating this library. It’s been a hole in C++ for a long time. I’ve used both `boost::format` and `loki::SPrintf`, and neither felt like the right answer. This does.

## Format API

The format API is similar in spirit to the C `printf` family of function but is safer, simpler and serveral times faster than common standard library implementations. The format string syntax is similar to the one used by str.format in Python:

    fmt::format("The answer is {}.", 42);

The `fmt::format` function returns a string “The answer is 42.”. You can use `fmt::memory_buffer` to avoid constructing `std::string`:

    fmt::memory_buffer out;
    format_to(out, "For a moment, {} happened.", "nothing");
    out.data(); // returns a pointer to the formatted data

The `fmt::print` function performs formatting and writes the result to a stream:

    fmt::print(stderr, "System error code = {}\n", errno);

The file argument can be omitted in which case the function prints to `stdout`:

    fmt::print("Don't {}\n", "panic");

The Format API also supports positional arguments useful for localization:

    fmt::print("I'd rather be {1} than {0}.", "right", "happy");

Named arguments can be created with `fmt::arg`. This makes it easier to track what goes where when multiple arguments are being formatted:

    fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
               fmt::arg("name", "World"), fmt::arg("number", 42));

If your compiler supports C++11 user-defined literals, the suffix `_a` offers an alternative, slightly terser syntax for named arguments:

    using namespace fmt::literals;
    fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
               "name"_a="World", "number"_a=42);

## Safety

The library is fully type safe, automatic memory management prevents buffer overflow, errors in format strings are reported using exceptions or at compile time. For example, the code

    fmt::format("The answer is {:d}", "forty-two");

throws a `format_error` exception with description “unknown format code ‘d’ for string”, because the argument `"forty-two"` is a string while the format code `d` only applies to integers, while

    format(FMT_STRING("The answer is {:d}"), "forty-two");

reports a compile-time error for the same reason on compilers that support relaxed `constexpr`. See here for details.

The following code

    fmt::format("Cyrillic letter {}", L'\x42e');

produces a compile-time error because wide character `L'\x42e'` cannot be formatted into a narrow string. You can use a wide format string instead:

    fmt::format(L"Cyrillic letter {}", L'\x42e');

For comparison, writing a wide character to `std::ostream` results in its numeric value being written to the stream (i.e. 1070 instead of letter ‘ю’ which is represented by `L'\x42e'` if we use Unicode) which is rarely what is needed.

## Compact Binary Code

The library is designed to produce compact per-call compiled code. For example (godbolt),

    #include <fmt/core.h>

    int main() {
      fmt::print("The answer is {}.", 42);
    }

compiles to just

    main: # @main
      sub rsp, 24
      mov qword ptr [rsp], 42
      mov rcx, rsp
      mov edi, offset .L.str
      mov esi, 17
      mov edx, 2
      call fmt::v5::vprint(fmt::v5::basic_string_view<char>, fmt::v5::format_args)
      xor eax, eax
      add rsp, 24
      ret
    .L.str:
      .asciz "The answer is {}."

## Portability

The library is highly portable and relies only on a small set of C++11 features:

- variadic templates
- type traits
- rvalue references
- decltype
- trailing return types
- deleted functions
- alias templates

These are available since GCC 4.8, Clang 3.0 and MSVC 19.0 (2015). For older compilers use {fmt} version 4.x which continues to be maintained and only requires C++98.

The output of all formatting functions is consistent across platforms. In particular, formatting a floating-point infinity always gives `inf` while the output of `printf` is platform-dependent. For example,

    fmt::print("{}", std::numeric_limits<double>::infinity());

always prints `inf`.

## Ease of Use

{fmt} has a small self-contained code base with the core library consisting of just three header files and no external dependencies. A permissive MIT license allows using the library both in open-source and commercial projects.

GitHub Repository