1Overview 2======== 3 4**{fmt}** is an open-source formatting library providing a fast and safe 5alternative to C stdio and C++ iostreams. 6 7.. raw:: html 8 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 13 aa long time. I’ve used both <code>boost::format</code> and 14 <code>loki::SPrintf</code>, and neither felt like the right answer. 15 This does. 16 </div> 17 </div> 18 19.. _format-api-intro: 20 21Format API 22---------- 23 24The format API is similar in spirit to the C ``printf`` family of function but 25is safer, simpler and serveral times `faster 26<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_ 27than common standard library implementations. 28The `format string syntax <syntax.html>`_ is similar to the one used by 29`str.format <http://docs.python.org/3/library/stdtypes.html#str.format>`_ in 30Python: 31 32.. code:: c++ 33 34 fmt::format("The answer is {}.", 42); 35 36The ``fmt::format`` function returns a string "The answer is 42.". You can use 37``fmt::memory_buffer`` to avoid constructing ``std::string``: 38 39.. code:: c++ 40 41 fmt::memory_buffer out; 42 format_to(out, "For a moment, {} happened.", "nothing"); 43 out.data(); // returns a pointer to the formatted data 44 45The ``fmt::print`` function performs formatting and writes the result to a stream: 46 47.. code:: c++ 48 49 fmt::print(stderr, "System error code = {}\n", errno); 50 51The file argument can be omitted in which case the function prints to 52``stdout``: 53 54.. code:: c++ 55 56 fmt::print("Don't {}\n", "panic"); 57 58The Format API also supports positional arguments useful for localization: 59 60.. code:: c++ 61 62 fmt::print("I'd rather be {1} than {0}.", "right", "happy"); 63 64Named arguments can be created with ``fmt::arg``. This makes it easier to track 65what goes where when multiple arguments are being formatted: 66 67.. code:: c++ 68 69 fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.", 70 fmt::arg("name", "World"), fmt::arg("number", 42)); 71 72If your compiler supports C++11 user-defined literals, the suffix ``_a`` offers 73an alternative, slightly terser syntax for named arguments: 74 75.. code:: c++ 76 77 using namespace fmt::literals; 78 fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.", 79 "name"_a="World", "number"_a=42); 80 81.. _safety: 82 83Safety 84------ 85 86The library is fully type safe, automatic memory management prevents buffer 87overflow, errors in format strings are reported using exceptions or at compile 88time. For example, the code 89 90.. code:: c++ 91 92 fmt::format("The answer is {:d}", "forty-two"); 93 94throws a ``format_error`` exception with description "unknown format code 'd' for 95string", because the argument ``"forty-two"`` is a string while the format code 96``d`` only applies to integers, while 97 98.. code:: c++ 99 100 format(FMT_STRING("The answer is {:d}"), "forty-two"); 101 102reports a compile-time error for the same reason on compilers that support 103relaxed ``constexpr``. See `here <api.html#c.fmt>`_ for details. 104 105The following code 106 107.. code:: c++ 108 109 fmt::format("Cyrillic letter {}", L'\x42e'); 110 111produces a compile-time error because wide character ``L'\x42e'`` cannot be 112formatted into a narrow string. You can use a wide format string instead: 113 114.. code:: c++ 115 116 fmt::format(L"Cyrillic letter {}", L'\x42e'); 117 118For comparison, writing a wide character to ``std::ostream`` results in 119its numeric value being written to the stream (i.e. 1070 instead of letter 'ю' 120which is represented by ``L'\x42e'`` if we use Unicode) which is rarely what is 121needed. 122 123Compact Binary Code 124------------------- 125 126The library is designed to produce compact per-call compiled code. For example 127(`godbolt <https://godbolt.org/g/TZU4KF>`_), 128 129.. code:: c++ 130 131 #include <fmt/core.h> 132 133 int main() { 134 fmt::print("The answer is {}.", 42); 135 } 136 137compiles to just 138 139.. code:: asm 140 141 main: # @main 142 sub rsp, 24 143 mov qword ptr [rsp], 42 144 mov rcx, rsp 145 mov edi, offset .L.str 146 mov esi, 17 147 mov edx, 2 148 call fmt::v5::vprint(fmt::v5::basic_string_view<char>, fmt::v5::format_args) 149 xor eax, eax 150 add rsp, 24 151 ret 152 .L.str: 153 .asciz "The answer is {}." 154 155.. _portability: 156 157Portability 158----------- 159 160The library is highly portable and relies only on a small set of C++11 features: 161 162* variadic templates 163* type traits 164* rvalue references 165* decltype 166* trailing return types 167* deleted functions 168* alias templates 169 170These are available since GCC 4.8, Clang 3.0 and MSVC 19.0 (2015). For older 171compilers use {fmt} `version 4.x 172<https://github.com/fmtlib/fmt/releases/tag/4.1.0>`_ which continues to be 173maintained and only requires C++98. 174 175The output of all formatting functions is consistent across platforms. In 176particular, formatting a floating-point infinity always gives ``inf`` while the 177output of ``printf`` is platform-dependent. For example, 178 179.. code:: 180 181 fmt::print("{}", std::numeric_limits<double>::infinity()); 182 183always prints ``inf``. 184 185.. _ease-of-use: 186 187Ease of Use 188----------- 189 190{fmt} has a small self-contained code base with the core library consisting of 191just three header files and no external dependencies. 192A permissive MIT `license <https://github.com/fmtlib/fmt#license>`_ allows 193using the library both in open-source and commercial projects. 194 195.. raw:: html 196 197 <a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a> 198 199 <div class="section footer"> 200 <iframe src="http://ghbtns.com/github-btn.html?user=fmtlib&repo=fmt&type=watch&count=true" 201 class="github-btn" width="100" height="20"></iframe> 202 </div> 203