| Overview |
| ======== |
| |
| **{fmt}** is an open-source formatting library providing a fast and safe |
| alternative to C stdio and 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 <code>boost::format</code> and |
| <code>loki::SPrintf</code>, and neither felt like the right answer. |
| This does. |
| </div> |
| </div> |
| |
| .. _format-api-intro: |
| |
| Format API |
| ---------- |
| |
| The format API is similar in spirit to the C ``printf`` family of function but |
| is safer, simpler and several times `faster |
| <https://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_ |
| than common standard library implementations. |
| The `format string syntax <syntax.html>`_ is similar to the one used by |
| `str.format <http://docs.python.org/3/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::memory_buffer`` to avoid constructing ``std::string``: |
| |
| .. code:: c++ |
| |
| fmt::memory_buffer out; |
| format_to(out, "For a moment, {} happened.", "nothing"); |
| out.data(); // returns a pointer to the formatted data |
| |
| The ``fmt::print`` function performs formatting and writes the result to a stream: |
| |
| .. code:: c++ |
| |
| fmt::print(stderr, "System error code = {}\n", errno); |
| |
| If you omit the file argument the function will print to ``stdout``: |
| |
| .. code:: c++ |
| |
| fmt::print("Don't {}\n", "panic"); |
| |
| The format API also supports positional arguments useful for localization: |
| |
| .. code:: c++ |
| |
| fmt::print("I'd rather be {1} than {0}.", "right", "happy"); |
| |
| You can pass named arguments with ``fmt::arg``: |
| |
| .. 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++ |
| |
| using namespace fmt::literals; |
| fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.", |
| "name"_a="World", "number"_a=42); |
| |
| .. _safety: |
| |
| Safety |
| ------ |
| |
| The library is fully type safe, automatic memory management prevents buffer |
| overflow, errors in format strings are reported using exceptions or at compile |
| time. For example, the code |
| |
| .. code:: c++ |
| |
| fmt::format("The answer is {:d}", "forty-two"); |
| |
| throws the ``format_error`` exception because the argument ``"forty-two"`` is a |
| string while the format code ``d`` only applies to integers. |
| |
| The code |
| |
| .. code:: c++ |
| |
| format(FMT_STRING("The answer is {:d}"), "forty-two"); |
| |
| reports a compile-time error on compilers that support relaxed ``constexpr``. |
| See `here <api.html#c.fmt>`_ for details. |
| |
| The following 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 |
| desirable. |
| |
| Compact Binary Code |
| ------------------- |
| |
| The library produces compact per-call compiled code. For example |
| (`godbolt <https://godbolt.org/g/TZU4KF>`_), |
| |
| .. code:: c++ |
| |
| #include <fmt/core.h> |
| |
| int main() { |
| fmt::print("The answer is {}.", 42); |
| } |
| |
| compiles to just |
| |
| .. code:: asm |
| |
| main: # @main |
| sub rsp, 24 |
| mov qword ptr [rsp], 42 |
| mov rcx, rsp |
| mov edi, offset .L.str |
| mov esi, 17 |
| mov edx, 1 |
| call fmt::v7::vprint(fmt::v7::basic_string_view<char>, fmt::v7::format_args) |
| xor eax, eax |
| add rsp, 24 |
| ret |
| .L.str: |
| .asciz "The answer is {}." |
| |
| .. _portability: |
| |
| Portability |
| ----------- |
| |
| The library is highly portable and relies only on a small set of C++11 features: |
| |
| * variadic templates |
| * type traits |
| * rvalue references |
| * decltype |
| * trailing return types |
| * deleted functions |
| * alias templates |
| |
| These are available in GCC 4.8, Clang 3.0, MSVC 19.0 (2015) and more recent |
| compiler version. For older compilers use {fmt} `version 4.x |
| <https://github.com/fmtlib/fmt/releases/tag/4.1.0>`_ which is maintained and |
| only requires C++98. |
| |
| The output of all formatting functions is consistent across platforms. |
| For example, |
| |
| .. code:: |
| |
| fmt::print("{}", std::numeric_limits<double>::infinity()); |
| |
| always prints ``inf`` while the output of ``printf`` is platform-dependent. |
| |
| .. _ease-of-use: |
| |
| Ease of Use |
| ----------- |
| |
| {fmt} has a small self-contained code base with the core library consisting of |
| just three header files and no external dependencies. |
| A permissive MIT `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> |