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 a 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 several times `faster 26<https://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_ 27than common standard library implementations. 28The `format string syntax <syntax.html>`_ is similar to the one used by 29`str.format <https://docs.python.org/3/library/stdtypes.html#str.format>`_ in 30Python: 31 32.. code:: c++ 33 34 std::string s = 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 auto out = fmt::memory_buffer(); 42 fmt::format_to(std::back_inserter(out), 43 "For a moment, {} happened.", "nothing"); 44 auto data = out.data(); // pointer to the formatted data 45 auto size = out.size(); // size of the formatted data 46 47The ``fmt::print`` function performs formatting and writes the result to a stream: 48 49.. code:: c++ 50 51 fmt::print(stderr, "System error code = {}\n", errno); 52 53If you omit the file argument the function will print to ``stdout``: 54 55.. code:: c++ 56 57 fmt::print("Don't {}\n", "panic"); 58 59The format API also supports positional arguments useful for localization: 60 61.. code:: c++ 62 63 fmt::print("I'd rather be {1} than {0}.", "right", "happy"); 64 65You can pass named arguments with ``fmt::arg``: 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 the ``format_error`` exception because the argument ``"forty-two"`` is a 95string while the format code ``d`` only applies to integers. 96 97The code 98 99.. code:: c++ 100 101 format(FMT_STRING("The answer is {:d}"), "forty-two"); 102 103reports a compile-time error on compilers that support relaxed ``constexpr``. 104See `here <api.html#compile-time-format-string-checks>`_ for details. 105 106The following code 107 108.. code:: c++ 109 110 fmt::format("Cyrillic letter {}", L'\x42e'); 111 112produces a compile-time error because wide character ``L'\x42e'`` cannot be 113formatted into a narrow string. For comparison, writing a wide character to 114``std::ostream`` results in its numeric value being written to the stream 115(i.e. 1070 instead of letter 'ю' which is represented by ``L'\x42e'`` if we 116use Unicode) which is rarely desirable. 117 118Compact Binary Code 119------------------- 120 121The library produces compact per-call compiled code. For example 122(`godbolt <https://godbolt.org/g/TZU4KF>`_), 123 124.. code:: c++ 125 126 #include <fmt/core.h> 127 128 int main() { 129 fmt::print("The answer is {}.", 42); 130 } 131 132compiles to just 133 134.. code:: asm 135 136 main: # @main 137 sub rsp, 24 138 mov qword ptr [rsp], 42 139 mov rcx, rsp 140 mov edi, offset .L.str 141 mov esi, 17 142 mov edx, 1 143 call fmt::v7::vprint(fmt::v7::basic_string_view<char>, fmt::v7::format_args) 144 xor eax, eax 145 add rsp, 24 146 ret 147 .L.str: 148 .asciz "The answer is {}." 149 150.. _portability: 151 152Portability 153----------- 154 155The library is highly portable and relies only on a small set of C++11 features: 156 157* variadic templates 158* type traits 159* rvalue references 160* decltype 161* trailing return types 162* deleted functions 163* alias templates 164 165These are available in GCC 4.8, Clang 3.4, MSVC 19.0 (2015) and more recent 166compiler version. For older compilers use {fmt} `version 4.x 167<https://github.com/fmtlib/fmt/releases/tag/4.1.0>`_ which is maintained and 168only requires C++98. 169 170The output of all formatting functions is consistent across platforms. 171For example, 172 173.. code:: 174 175 fmt::print("{}", std::numeric_limits<double>::infinity()); 176 177always prints ``inf`` while the output of ``printf`` is platform-dependent. 178 179.. _ease-of-use: 180 181Ease of Use 182----------- 183 184{fmt} has a small self-contained code base with the core library consisting of 185just three header files and no external dependencies. 186A permissive MIT `license <https://github.com/fmtlib/fmt#license>`_ allows 187using the library both in open-source and commercial projects. 188 189`Learn more... <contents.html>`_ 190 191.. raw:: html 192 193 <a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a> 194 195 <div class="section footer"> 196 <iframe src="https://ghbtns.com/github-btn.html?user=fmtlib&repo=fmt&type=watch&count=true" 197 class="github-btn" width="100" height="20"></iframe> 198 </div> 199