| Overview |
| ======== |
| |
| **fmt** (formerly cppformat) is an open-source formatting library. |
| It can be used as a safe alternative to printf or as a fast |
| alternative to C++ IOStreams. |
| |
| .. raw:: html |
| |
| <div class="panel panel-default"> |
| <div class="panel-heading">What users say:</div> |
| <div class="panel-body"> |
| Thanks for creating this library. It’s been a hole in C++ for a long |
| time. I’ve used both boost::format and loki::SPrintf, and neither felt |
| like the right answer. This does. |
| </div> |
| </div> |
| |
| .. _format-api: |
| |
| Format API |
| ---------- |
| |
| The replacement-based Format API provides a safe alternative to ``printf``, |
| ``sprintf`` and friends with comparable or `better performance |
| <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_. |
| The `format string syntax <syntax.html>`_ is similar to the one used by |
| `str.format <http://docs.python.org/2/library/stdtypes.html#str.format>`_ |
| in Python: |
| |
| .. code:: c++ |
| |
| fmt::format("The answer is {}", 42); |
| |
| The ``fmt::format`` function returns a string "The answer is 42". You can use |
| ``fmt::MemoryWriter`` to avoid constructing ``std::string``: |
| |
| .. code:: c++ |
| |
| fmt::MemoryWriter w; |
| w.write("Look, a {} string", 'C'); |
| w.c_str(); // returns a C string (const char*) |
| |
| The ``fmt::print`` function performs formatting and writes the result to a file: |
| |
| .. code:: c++ |
| |
| fmt::print(stderr, "System error code = {}\n", errno); |
| |
| The file argument can be omitted in which case the function prints to |
| ``stdout``: |
| |
| .. code:: c++ |
| |
| fmt::print("Don't {}\n", "panic"); |
| |
| If your compiler supports C++11, then the formatting functions are implemented |
| with variadic templates. Otherwise variadic functions are emulated by generating |
| a set of lightweight wrappers. This ensures compatibility with older compilers |
| while providing a natural API. |
| |
| The Format API also supports positional arguments useful for localization: |
| |
| .. code:: c++ |
| |
| fmt::print("I'd rather be {1} than {0}.", "right", "happy"); |
| |
| Named arguments can be created with ``fmt::arg``. This makes it easier to track |
| what goes where when multiple values are being inserted: |
| |
| .. code:: c++ |
| |
| fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.", |
| fmt::arg("name", "World"), fmt::arg("number", 42)); |
| |
| If your compiler supports C++11 user-defined literals, the suffix ``_a`` offers |
| an alternative, slightly terser syntax for named arguments: |
| |
| .. code:: c++ |
| |
| fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.", |
| "name"_a="World", "number"_a=42); |
| |
| The ``_format`` suffix may be used to format string literals similar to Python: |
| |
| .. code:: c++ |
| |
| std::string message = "{0}{1}{0}"_format("abra", "cad"); |
| |
| Other than the placement of the format string on the left of the operator, |
| ``_format`` is functionally identical to ``fmt::format``. In order to use the |
| literal operators, they must be made visible with the directive |
| ``using namespace fmt::literals;``. Note that this brings in only ``_a`` and |
| ``_format`` but nothing else from the ``fmt`` namespace. |
| |
| .. _write-api: |
| |
| Write API |
| --------- |
| |
| The concatenation-based Write API (experimental) provides a `fast |
| <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_ |
| stateless alternative to IOStreams: |
| |
| .. code:: c++ |
| |
| fmt::MemoryWriter out; |
| out << "The answer in hexadecimal is " << hex(42); |
| |
| .. _safety: |
| |
| Safety |
| ------ |
| |
| The library is fully type safe, automatic memory management prevents buffer |
| overflow, errors in format strings are reported using exceptions. For example, |
| the code |
| |
| .. code:: c++ |
| |
| fmt::format("The answer is {:d}", "forty-two"); |
| |
| throws a ``FormatError`` exception with description |
| "unknown format code 'd' for string", because the argument |
| ``"forty-two"`` is a string while the format code ``d`` |
| only applies to integers. |
| |
| Where possible, errors are caught at compile time. For example, the code |
| |
| .. code:: c++ |
| |
| fmt::format("Cyrillic letter {}", L'\x42e'); |
| |
| produces a compile-time error because wide character ``L'\x42e'`` cannot be |
| formatted into a narrow string. You can use a wide format string instead: |
| |
| .. code:: c++ |
| |
| fmt::format(L"Cyrillic letter {}", L'\x42e'); |
| |
| For comparison, writing a wide character to ``std::ostream`` results in |
| its numeric value being written to the stream (i.e. 1070 instead of letter 'ю' |
| which is represented by ``L'\x42e'`` if we use Unicode) which is rarely what is |
| needed. |
| |
| .. _portability: |
| |
| Portability |
| ----------- |
| |
| The library is highly portable. Here is an incomplete list of operating systems |
| and compilers where it has been tested and known to work: |
| |
| * 64-bit (amd64) GNU/Linux with GCC 4.4.3, |
| `4.6.3 <https://travis-ci.org/fmtlib/fmt>`_, 4.7.2, 4.8.1, and Intel C++ |
| Compiler (ICC) 14.0.2 |
| |
| * 32-bit (i386) GNU/Linux with GCC 4.4.3, 4.6.3 |
| |
| * Mac OS X with GCC 4.2.1 and Clang 4.2, 5.1.0 |
| |
| * 64-bit Windows with Visual C++ 2010, 2013 and |
| `2015 <https://ci.appveyor.com/project/vitaut/fmt>`_ |
| |
| * 32-bit Windows with Visual C++ 2010 |
| |
| Although the library uses C++11 features when available, it also works with |
| older compilers and standard library implementations. The only thing to keep in |
| mind for C++98 portability: |
| |
| * Variadic templates: minimum GCC 4.4, Clang 2.9 or VS2013. This feature allows |
| the Format API to accept an unlimited number of arguments. With older |
| compilers the maximum is 15. |
| |
| * User-defined literals: minimum GCC 4.7, Clang 3.1 or VS2015. The suffixes |
| ``_format`` and ``_a`` are functionally equivalent to the functions |
| ``fmt::format`` and ``fmt::arg``. |
| |
| The output of all formatting functions is consistent across platforms. In |
| particular, formatting a floating-point infinity always gives ``inf`` while the |
| output of ``printf`` is platform-dependent in this case. For example, |
| |
| .. code:: |
| |
| fmt::print("{}", std::numeric_limits<double>::infinity()); |
| |
| always prints ``inf``. |
| |
| .. _ease-of-use: |
| |
| Ease of Use |
| ----------- |
| |
| fmt has a small self-contained code base with the core library consisting of |
| a single header file and a single source file and no external dependencies. |
| A permissive BSD `license <https://github.com/fmtlib/fmt#license>`_ allows |
| using the library both in open-source and commercial projects. |
| |
| .. raw:: html |
| |
| <a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a> |
| |
| <div class="section footer"> |
| <iframe src="http://ghbtns.com/github-btn.html?user=fmtlib&repo=fmt&type=watch&count=true" |
| class="github-btn" width="100" height="20"></iframe> |
| </div> |