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
What users say:
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.
.. _format-api-intro: Format API ---------- The replacement-based Format API provides a safe alternative to ``printf``, ``sprintf`` and friends with comparable or `better performance `_. The `format string syntax `_ is similar to the one used by `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. .. _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. Note that fmt does not use the value of the ``errno`` global to communicate errors to the user, but it may call system functions which set ``errno``. Since fmt does not attempt to preserve the value of ``errno``, users should not make any assumptions about it and always set it to ``0`` before making any system calls that convey error information via ``errno``. .. _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 `_, 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 `_ * 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::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 `_ allows using the library both in open-source and commercial projects. .. raw:: html GitHub Repository