4 **fmt** (formerly cppformat) is an open-source formatting library.
5 It can be used as a fast and safe alternative to printf and IOStreams.
9 <div class="panel panel-default">
10 <div class="panel-heading">What users say:</div>
11 <div class="panel-body">
12 Thanks for creating this library. It’s been a hole in C++ for a long
13 time. I’ve used both boost::format and loki::SPrintf, and neither felt
14 like the right answer. This does.
23 The replacement-based Format API provides a safe alternative to ``printf``,
24 ``sprintf`` and friends with comparable or `better performance
25 <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
26 The `format string syntax <syntax.html>`_ is similar to the one used by
27 `str.format <http://docs.python.org/3/library/stdtypes.html#str.format>`_
32 fmt::format("The answer is {}.", 42);
34 The ``fmt::format`` function returns a string "The answer is 42.". You can use
35 ``fmt::memory_buffer`` to avoid constructing ``std::string``:
39 fmt::memory_buffer out;
40 format_to(out, "For a moment, {} happened.", "nothing");
41 out.data(); // returns a pointer to the formatted data
43 The ``fmt::print`` function performs formatting and writes the result to a stream:
47 fmt::print(stderr, "System error code = {}\n", errno);
49 The file argument can be omitted in which case the function prints to
54 fmt::print("Don't {}\n", "panic");
56 The Format API also supports positional arguments useful for localization:
60 fmt::print("I'd rather be {1} than {0}.", "right", "happy");
62 Named arguments can be created with ``fmt::arg``. This makes it easier to track
63 what goes where when multiple values are being inserted:
67 fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
68 fmt::arg("name", "World"), fmt::arg("number", 42));
70 If your compiler supports C++11 user-defined literals, the suffix ``_a`` offers
71 an alternative, slightly terser syntax for named arguments:
75 fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
76 "name"_a="World", "number"_a=42);
78 The ``_format`` suffix may be used to format string literals similar to Python:
82 std::string message = "{0}{1}{0}"_format("abra", "cad");
84 Other than the placement of the format string on the left of the operator,
85 ``_format`` is functionally identical to ``fmt::format``. In order to use the
86 literal operators, they must be made visible with the directive
87 ``using namespace fmt::literals;``. Note that this brings in only ``_a`` and
88 ``_format`` but nothing else from the ``fmt`` namespace.
95 The library is fully type safe, automatic memory management prevents buffer
96 overflow, errors in format strings are reported using exceptions or at compile
97 time. For example, the code
101 fmt::format("The answer is {:d}", "forty-two");
103 throws a ``format_error`` exception with description "unknown format code 'd' for
104 string", because the argument ``"forty-two"`` is a string while the format code
105 ``d`` only applies to integers, while
109 format(fmt("The answer is {:d}"), "forty-two");
111 reports a compile-time error for the same reason on compilers that support
112 relaxed ``constexpr``.
118 fmt::format("Cyrillic letter {}", L'\x42e');
120 produces a compile-time error because wide character ``L'\x42e'`` cannot be
121 formatted into a narrow string. You can use a wide format string instead:
125 fmt::format(L"Cyrillic letter {}", L'\x42e');
127 For comparison, writing a wide character to ``std::ostream`` results in
128 its numeric value being written to the stream (i.e. 1070 instead of letter 'ю'
129 which is represented by ``L'\x42e'`` if we use Unicode) which is rarely what is
135 The library is designed to produce compact per-call compiled code. For example
136 (`godbolt <https://godbolt.org/g/TZU4KF>`_),
140 #include <fmt/core.h>
143 fmt::print("The answer is {}.", 42);
152 mov qword ptr [rsp], 42
154 mov edi, offset .L.str
157 call fmt::v5::vprint(fmt::v5::basic_string_view<char>, fmt::v5::format_args)
162 .asciz "The answer is {}."
169 The library is highly portable and relies only on a small set of C++11 features:
175 * trailing return types
178 These are available since GCC 4.4, Clang 2.9 and MSVC 18.0 (2013). For older
179 compilers use fmt `version 4.x
180 <https://github.com/fmtlib/fmt/releases/tag/4.1.0>`_ which continues to be
181 maintained and only requires C++98.
183 The output of all formatting functions is consistent across platforms. In
184 particular, formatting a floating-point infinity always gives ``inf`` while the
185 output of ``printf`` is platform-dependent in this case. For example,
189 fmt::print("{}", std::numeric_limits<double>::infinity());
191 always prints ``inf``.
198 fmt has a small self-contained code base with the core library consisting of
199 just three header files and no external dependencies.
200 A permissive BSD `license <https://github.com/fmtlib/fmt#license>`_ allows
201 using the library both in open-source and commercial projects.
205 <a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a>
207 <div class="section footer">
208 <iframe src="http://ghbtns.com/github-btn.html?user=fmtlib&repo=fmt&type=watch&count=true"
209 class="github-btn" width="100" height="20"></iframe>