1Overview 2======== 3 4**fmt** (formerly cppformat) is an open-source formatting library. 5It can be used as a safe alternative to printf or as a fast 6alternative 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. It’s been a hole in C++ for a long 14 time. I’ve 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 21Format API 22---------- 23 24The 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>`_. 27The `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>`_ 29in Python: 30 31.. code:: c++ 32 33 fmt::format("The answer is {}", 42); 34 35The ``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 44The ``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 50The 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 57If your compiler supports C++11, then the formatting functions are implemented 58with variadic templates. Otherwise variadic functions are emulated by generating 59a set of lightweight wrappers. This ensures compatibility with older compilers 60while providing a natural API. 61 62The 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 68Named arguments can be created with ``fmt::arg``. This makes it easier to track 69what 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 76If your compiler supports C++11 user-defined literals, the suffix ``_a`` offers 77an 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 84The ``_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 90Other 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 92literal 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 98Write API 99--------- 100 101The concatenation-based Write API (experimental) provides a `fast 102<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_ 103stateless 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 112Safety 113------ 114 115The library is fully type safe, automatic memory management prevents buffer 116overflow, errors in format strings are reported using exceptions. For example, 117the code 118 119.. code:: c++ 120 121 fmt::format("The answer is {:d}", "forty-two"); 122 123throws 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`` 126only applies to integers. 127 128Where possible, errors are caught at compile time. For example, the code 129 130.. code:: c++ 131 132 fmt::format("Cyrillic letter {}", L'\x42e'); 133 134produces a compile-time error because wide character ``L'\x42e'`` cannot be 135formatted 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 141For comparison, writing a wide character to ``std::ostream`` results in 142its numeric value being written to the stream (i.e. 1070 instead of letter 'ю' 143which is represented by ``L'\x42e'`` if we use Unicode) which is rarely what is 144needed. 145 146.. _portability: 147 148Portability 149----------- 150 151The library is highly portable. Here is an incomplete list of operating systems 152and 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 167Although the library uses C++11 features when available, it also works with 168older compilers and standard library implementations. The only thing to keep in 169mind 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 179The output of all formatting functions is consistent across platforms. In 180particular, formatting a floating-point infinity always gives ``inf`` while the 181output of ``printf`` is platform-dependent in this case. For example, 182 183.. code:: 184 185 fmt::print("{}", std::numeric_limits<double>::infinity()); 186 187always prints ``inf``. 188 189.. _ease-of-use: 190 191Ease of Use 192----------- 193 194fmt has a small self-contained code base with the core library consisting of 195a single header file and a single source file and no external dependencies. 196A permissive BSD `license <https://github.com/fmtlib/fmt#license>`_ allows 197using 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