fmt/doc/index.rst

199 lines
5.3 KiB
ReStructuredText
Raw Normal View History

2015-03-09 14:37:27 +00:00
Overview
========
2019-11-28 16:09:46 +00:00
**{fmt}** is an open-source formatting library providing a fast and safe
alternative to C stdio and C++ iostreams.
2012-12-18 14:49:18 +00:00
.. raw:: html
<div class="panel panel-default">
<div class="panel-heading">What users say:</div>
<div class="panel-body">
2019-11-28 16:09:46 +00:00
Thanks for creating this library. Its been a hole in C++ for
2019-12-13 23:49:40 +00:00
a long time. Ive used both <code>boost::format</code> and
2019-11-28 16:09:46 +00:00
<code>loki::SPrintf</code>, and neither felt like the right answer.
This does.
</div>
</div>
2018-05-13 15:04:39 +00:00
.. _format-api-intro:
2015-03-09 14:37:27 +00:00
Format API
----------
2019-11-28 16:09:46 +00:00
The format API is similar in spirit to the C ``printf`` family of function but
2020-07-02 14:29:38 +00:00
is safer, simpler and several times `faster
2020-10-01 00:21:07 +00:00
<https://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_
2019-11-28 16:09:46 +00:00
than common standard library implementations.
2016-06-16 18:18:40 +00:00
The `format string syntax <syntax.html>`_ is similar to the one used by
2020-12-05 14:41:38 +00:00
`str.format <https://docs.python.org/3/library/stdtypes.html#str.format>`_ in
2019-11-28 16:09:46 +00:00
Python:
2015-03-09 14:37:27 +00:00
.. code:: c++
2021-06-02 14:46:26 +00:00
std::string s = fmt::format("The answer is {}.", 42);
2015-03-09 14:37:27 +00:00
2018-05-21 00:10:34 +00:00
The ``fmt::format`` function returns a string "The answer is 42.". You can use
2018-05-13 19:42:55 +00:00
``fmt::memory_buffer`` to avoid constructing ``std::string``:
2015-03-09 14:37:27 +00:00
.. code:: c++
2021-06-02 14:46:26 +00:00
auto out = fmt::memory_buffer();
fmt::format_to(std::back_inserter(out),
2021-06-02 14:46:26 +00:00
"For a moment, {} happened.", "nothing");
auto data = out.data(); // pointer to the formatted data
auto size = out.size(); // size of the formatted data
2015-03-09 14:37:27 +00:00
The ``fmt::print`` function performs formatting and writes the result to a stream:
2015-03-09 14:37:27 +00:00
.. code:: c++
fmt::print(stderr, "System error code = {}\n", errno);
2020-10-01 00:38:28 +00:00
If you omit the file argument the function will print to ``stdout``:
2015-03-09 14:37:27 +00:00
.. code:: c++
fmt::print("Don't {}\n", "panic");
2020-10-01 00:38:28 +00:00
The format API also supports positional arguments useful for localization:
2015-03-09 14:37:27 +00:00
.. code:: c++
fmt::print("I'd rather be {1} than {0}.", "right", "happy");
2020-10-01 00:38:28 +00:00
You can pass named arguments with ``fmt::arg``:
2015-10-11 00:34:20 +00:00
.. 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++
2019-11-28 16:09:46 +00:00
using namespace fmt::literals;
2015-10-11 00:34:20 +00:00
fmt::print("Hello, {name}! The answer is {number}. Goodbye, {name}.",
"name"_a="World", "number"_a=42);
2015-03-09 14:37:27 +00:00
.. _safety:
Safety
------
2016-07-21 16:00:23 +00:00
The library is fully type safe, automatic memory management prevents buffer
2018-05-21 00:10:34 +00:00
overflow, errors in format strings are reported using exceptions or at compile
time. For example, the code
2015-03-09 14:37:27 +00:00
.. code:: c++
fmt::format("The answer is {:d}", "forty-two");
2020-10-01 00:38:28 +00:00
throws the ``format_error`` exception because the argument ``"forty-two"`` is a
string while the format code ``d`` only applies to integers.
The code
2015-03-09 14:37:27 +00:00
2018-05-21 00:10:34 +00:00
.. code:: c++
2019-11-28 16:09:46 +00:00
format(FMT_STRING("The answer is {:d}"), "forty-two");
2018-05-21 00:10:34 +00:00
2020-10-01 00:38:28 +00:00
reports a compile-time error on compilers that support relaxed ``constexpr``.
See `here <api.html#compile-time-format-string-checks>`_ for details.
2018-05-21 00:10:34 +00:00
The following code
2015-03-09 14:37:27 +00:00
.. code:: c++
fmt::format("Cyrillic letter {}", L'\x42e');
produces a compile-time error because wide character ``L'\x42e'`` cannot be
2021-06-02 14:46:26 +00:00
formatted into a narrow string. 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.
2015-03-09 14:37:27 +00:00
2019-05-18 15:56:49 +00:00
Compact Binary Code
2018-05-13 19:42:55 +00:00
-------------------
2020-10-01 00:38:28 +00:00
The library produces compact per-call compiled code. For example
2018-05-13 19:42:55 +00:00
(`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
2020-10-01 00:38:28 +00:00
mov edx, 1
call fmt::v7::vprint(fmt::v7::basic_string_view<char>, fmt::v7::format_args)
2018-05-13 19:42:55 +00:00
xor eax, eax
add rsp, 24
ret
.L.str:
.asciz "The answer is {}."
2015-03-09 14:37:27 +00:00
.. _portability:
Portability
-----------
2018-05-21 00:10:34 +00:00
The library is highly portable and relies only on a small set of C++11 features:
2015-10-11 00:34:20 +00:00
2018-05-21 00:10:34 +00:00
* variadic templates
* type traits
* rvalue references
* decltype
* trailing return types
* deleted functions
* alias templates
2015-10-11 00:34:20 +00:00
These are available in GCC 4.8, Clang 3.4, MSVC 19.0 (2015) and more recent
2020-10-01 00:38:28 +00:00
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.
2015-03-09 14:37:27 +00:00
2020-10-01 00:38:28 +00:00
The output of all formatting functions is consistent across platforms.
For example,
2015-03-09 14:37:27 +00:00
.. code::
fmt::print("{}", std::numeric_limits<double>::infinity());
2020-10-01 00:38:28 +00:00
always prints ``inf`` while the output of ``printf`` is platform-dependent.
2015-03-09 14:37:27 +00:00
.. _ease-of-use:
Ease of Use
-----------
2019-11-28 16:09:46 +00:00
{fmt} has a small self-contained code base with the core library consisting of
2018-05-21 00:10:34 +00:00
just three header files and no external dependencies.
2019-11-28 16:09:46 +00:00
A permissive MIT `license <https://github.com/fmtlib/fmt#license>`_ allows
2016-07-21 16:00:23 +00:00
using the library both in open-source and commercial projects.
2015-03-09 14:37:27 +00:00
2020-12-02 14:30:09 +00:00
`Learn more... <contents.html>`_
2015-03-09 14:37:27 +00:00
.. raw:: html
2016-04-27 15:35:59 +00:00
<a class="btn btn-success" href="https://github.com/fmtlib/fmt">GitHub Repository</a>
2015-03-09 14:37:27 +00:00
<div class="section footer">
2020-12-05 14:41:38 +00:00
<iframe src="https://ghbtns.com/github-btn.html?user=fmtlib&amp;repo=fmt&amp;type=watch&amp;count=true"
2015-03-09 14:37:27 +00:00
class="github-btn" width="100" height="20"></iframe>
</div>