index.rst
1 Overview 2 ======== 3 4 **{fmt}** is an open-source formatting library providing a fast and safe 5 alternative 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 21 Format API 22 ---------- 23 24 The format API is similar in spirit to the C ``printf`` family of function but 25 is safer, simpler and several times `faster 26 <https://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_ 27 than common standard library implementations. 28 The `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 30 Python: 31 32 .. code:: c++ 33 34 std::string s = fmt::format("The answer is {}.", 42); 35 36 The ``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 47 The ``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 53 If you omit the file argument the function will print to ``stdout``: 54 55 .. code:: c++ 56 57 fmt::print("Don't {}\n", "panic"); 58 59 The 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 65 You 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 72 If your compiler supports C++11 user-defined literals, the suffix ``_a`` offers 73 an 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 83 Safety 84 ------ 85 86 The library is fully type safe, automatic memory management prevents buffer 87 overflow, errors in format strings are reported using exceptions or at compile 88 time. For example, the code 89 90 .. code:: c++ 91 92 fmt::format("The answer is {:d}", "forty-two"); 93 94 throws the ``format_error`` exception because the argument ``"forty-two"`` is a 95 string while the format code ``d`` only applies to integers. 96 97 The code 98 99 .. code:: c++ 100 101 format(FMT_STRING("The answer is {:d}"), "forty-two"); 102 103 reports a compile-time error on compilers that support relaxed ``constexpr``. 104 See `here <api.html#compile-time-format-string-checks>`_ for details. 105 106 The following code 107 108 .. code:: c++ 109 110 fmt::format("Cyrillic letter {}", L'\x42e'); 111 112 produces a compile-time error because wide character ``L'\x42e'`` cannot be 113 formatted 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 116 use Unicode) which is rarely desirable. 117 118 Compact Binary Code 119 ------------------- 120 121 The 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 132 compiles 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 152 Portability 153 ----------- 154 155 The 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 165 These are available in GCC 4.8, Clang 3.4, MSVC 19.0 (2015) and more recent 166 compiler version. For older compilers use {fmt} `version 4.x 167 <https://github.com/fmtlib/fmt/releases/tag/4.1.0>`_ which is maintained and 168 only requires C++98. 169 170 The output of all formatting functions is consistent across platforms. 171 For example, 172 173 .. code:: 174 175 fmt::print("{}", std::numeric_limits<double>::infinity()); 176 177 always prints ``inf`` while the output of ``printf`` is platform-dependent. 178 179 .. _ease-of-use: 180 181 Ease of Use 182 ----------- 183 184 {fmt} has a small self-contained code base with the core library consisting of 185 just three header files and no external dependencies. 186 A permissive MIT `license <https://github.com/fmtlib/fmt#license>`_ allows 187 using 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>