1 Overview 2 ======== 3 4 **fmt** (formerly cppformat) is an open-source formatting library. 5 It can be used as a safe alternative to printf or as a fast 6 alternative to C++ IOStreams. 7 8 .. raw:: html 9 10 <div class="panel panel-default"> 11 <div class="panel-heading">What users say:</div> 12 <div class="panel-body"> 13 Thanks for creating this library. Its been a hole in C++ for a long 14 time. Ive used both boost::format and loki::SPrintf, and neither felt 15 like the right answer. This does. 16 </div> 17 </div> 18 19 .. _format-api: 20 21 Format API 22 ---------- 23 24 The replacement-based Format API provides a safe alternative to ``printf``, 25 ``sprintf`` and friends with comparable or `better performance 26 <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_. 27 The `format string syntax <syntax.html>`_ is similar to the one used by 28 `str.format <http://docs.python.org/2/library/stdtypes.html#str.format>`_ 29 in Python: 30 31 .. code:: c++ 32 33 fmt::format("The answer is {}", 42); 34 35 The ``fmt::format`` function returns a string "The answer is 42". You can use 36 ``fmt::MemoryWriter`` to avoid constructing ``std::string``: 37 38 .. code:: c++ 39 40 fmt::MemoryWriter w; 41 w.write("Look, a {} string", 'C'); 42 w.c_str(); // returns a C string (const char*) 43 44 The ``fmt::print`` function performs formatting and writes the result to a file: 45 46 .. code:: c++ 47 48 fmt::print(stderr, "System error code = {}\n", errno); 49 50 The file argument can be omitted in which case the function prints to 51 ``stdout``: 52 53 .. code:: c++ 54 55 fmt::print("Don't {}\n", "panic"); 56 57 If your compiler supports C++11, then the formatting functions are implemented 58 with variadic templates. Otherwise variadic functions are emulated by generating 59 a set of lightweight wrappers. This ensures compatibility with older compilers 60 while providing a natural API. 61 62 The Format API also supports positional arguments useful for localization: 63 64 .. code:: c++ 65 66 fmt::print("I'd rather be {1} than {0}.", "right", "happy"); 67 68 Named arguments can be created with ``fmt::arg``. This makes it easier to track 69 what goes where when multiple values are being inserted: 70 71 .. code:: c++ 72 73 fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.", 74 fmt::arg("name", "World"), fmt::arg("number", 42)); 75 76 If your compiler supports C++11 user-defined literals, the suffix ``_a`` offers 77 an alternative, slightly terser syntax for named arguments: 78 79 .. code:: c++ 80 81 fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.", 82 "name"_a="World", "number"_a=42); 83 84 The ``_format`` suffix may be used to format string literals similar to Python: 85 86 .. code:: c++ 87 88 std::string message = "{0}{1}{0}"_format("abra", "cad"); 89 90 Other than the placement of the format string on the left of the operator, 91 ``_format`` is functionally identical to ``fmt::format``. In order to use the 92 literal operators, they must be made visible with the directive 93 ``using namespace fmt::literals;``. Note that this brings in only ``_a`` and 94 ``_format`` but nothing else from the ``fmt`` namespace. 95 96 .. _write-api: 97 98 Write API 99 --------- 100 101 The concatenation-based Write API (experimental) provides a `fast 102 <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_ 103 stateless alternative to IOStreams: 104 105 .. code:: c++ 106 107 fmt::MemoryWriter out; 108 out << "The answer in hexadecimal is " << hex(42); 109 110 .. _safety: 111 112 Safety 113 ------ 114 115 The library is fully type safe, automatic memory management prevents buffer 116 overflow, errors in format strings are reported using exceptions. For example, 117 the code 118 119 .. code:: c++ 120 121 fmt::format("The answer is {:d}", "forty-two"); 122 123 throws a ``FormatError`` exception with description 124 "unknown format code 'd' for string", because the argument 125 ``"forty-two"`` is a string while the format code ``d`` 126 only applies to integers. 127 128 Where possible, errors are caught at compile time. For example, the code 129 130 .. code:: c++ 131 132 fmt::format("Cyrillic letter {}", L'\x42e'); 133 134 produces a compile-time error because wide character ``L'\x42e'`` cannot be 135 formatted into a narrow string. You can use a wide format string instead: 136 137 .. code:: c++ 138 139 fmt::format(L"Cyrillic letter {}", L'\x42e'); 140 141 For comparison, writing a wide character to ``std::ostream`` results in 142 its numeric value being written to the stream (i.e. 1070 instead of letter '' 143 which is represented by ``L'\x42e'`` if we use Unicode) which is rarely what is 144 needed. 145 146 .. _portability: 147 148 Portability 149 ----------- 150 151 The library is highly portable. Here is an incomplete list of operating systems 152 and compilers where it has been tested and known to work: 153 154 * 64-bit (amd64) GNU/Linux with GCC 4.4.3, 155 `4.6.3 <https://travis-ci.org/fmtlib/fmt>`_, 4.7.2, 4.8.1, and Intel C++ 156 Compiler (ICC) 14.0.2 157 158 * 32-bit (i386) GNU/Linux with GCC 4.4.3, 4.6.3 159 160 * Mac OS X with GCC 4.2.1 and Clang 4.2, 5.1.0 161 162 * 64-bit Windows with Visual C++ 2010, 2013 and 163 `2015 <https://ci.appveyor.com/project/vitaut/fmt>`_ 164 165 * 32-bit Windows with Visual C++ 2010 166 167 Although the library uses C++11 features when available, it also works with 168 older compilers and standard library implementations. The only thing to keep in 169 mind for C++98 portability: 170 171 * Variadic templates: minimum GCC 4.4, Clang 2.9 or VS2013. This feature allows 172 the Format API to accept an unlimited number of arguments. With older 173 compilers the maximum is 15. 174 175 * User-defined literals: minimum GCC 4.7, Clang 3.1 or VS2015. The suffixes 176 ``_format`` and ``_a`` are functionally equivalent to the functions 177 ``fmt::format`` and ``fmt::arg``. 178 179 The output of all formatting functions is consistent across platforms. In 180 particular, formatting a floating-point infinity always gives ``inf`` while the 181 output of ``printf`` is platform-dependent in this case. For example, 182 183 .. code:: 184 185 fmt::print("{}", std::numeric_limits<double>::infinity()); 186 187 always prints ``inf``. 188 189 .. _ease-of-use: 190 191 Ease of Use 192 ----------- 193 194 fmt has a small self-contained code base with the core library consisting of 195 a single header file and a single source file and no external dependencies. 196 A permissive BSD `license <https://github.com/fmtlib/fmt#license>`_ allows 197 using the library both in open-source and commercial projects. 198 199 .. raw:: html 200 201 <a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a> 202 203 <div class="section footer"> 204 <iframe src="http://ghbtns.com/github-btn.html?user=fmtlib&repo=fmt&type=watch&count=true" 205 class="github-btn" width="100" height="20"></iframe> 206 </div> 207
