545 lines
20 KiB
ReStructuredText
545 lines
20 KiB
ReStructuredText
.. image:: https://user-images.githubusercontent.com/
|
||
576385/156254208-f5b743a9-88cf-439d-b0c0-923d53e8d551.png
|
||
:width: 25%
|
||
:alt: {fmt}
|
||
|
||
.. image:: https://github.com/fmtlib/fmt/workflows/linux/badge.svg
|
||
:target: https://github.com/fmtlib/fmt/actions?query=workflow%3Alinux
|
||
|
||
.. image:: https://github.com/fmtlib/fmt/workflows/macos/badge.svg
|
||
:target: https://github.com/fmtlib/fmt/actions?query=workflow%3Amacos
|
||
|
||
.. image:: https://github.com/fmtlib/fmt/workflows/windows/badge.svg
|
||
:target: https://github.com/fmtlib/fmt/actions?query=workflow%3Awindows
|
||
|
||
.. image:: https://oss-fuzz-build-logs.storage.googleapis.com/badges/fmt.svg
|
||
:alt: fmt is continuously fuzzed at oss-fuzz
|
||
:target: https://bugs.chromium.org/p/oss-fuzz/issues/list?\
|
||
colspec=ID%20Type%20Component%20Status%20Proj%20Reported%20Owner%20\
|
||
Summary&q=proj%3Dfmt&can=1
|
||
|
||
.. image:: https://img.shields.io/badge/stackoverflow-fmt-blue.svg
|
||
:alt: Ask questions at StackOverflow with the tag fmt
|
||
:target: https://stackoverflow.com/questions/tagged/fmt
|
||
|
||
.. image:: https://api.securityscorecards.dev/projects/github.com/fmtlib/fmt/badge
|
||
:target: https://securityscorecards.dev/viewer/?uri=github.com/fmtlib/fmt
|
||
|
||
**{fmt}** is an open-source formatting library providing a fast and safe
|
||
alternative to C stdio and C++ iostreams.
|
||
|
||
If you like this project, please consider donating to one of the funds that
|
||
help victims of the war in Ukraine: https://www.stopputin.net/.
|
||
|
||
`Documentation <https://fmt.dev>`__
|
||
|
||
`Cheat Sheets <https://hackingcpp.com/cpp/libs/fmt.html>`__
|
||
|
||
Q&A: ask questions on `StackOverflow with the tag fmt
|
||
<https://stackoverflow.com/questions/tagged/fmt>`_.
|
||
|
||
Try {fmt} in `Compiler Explorer <https://godbolt.org/z/Eq5763>`_.
|
||
|
||
Features
|
||
--------
|
||
|
||
* Simple `format API <https://fmt.dev/latest/api.html>`_ with positional arguments
|
||
for localization
|
||
* Implementation of `C++20 std::format
|
||
<https://en.cppreference.com/w/cpp/utility/format>`__
|
||
* `Format string syntax <https://fmt.dev/latest/syntax.html>`_ similar to Python's
|
||
`format <https://docs.python.org/3/library/stdtypes.html#str.format>`_
|
||
* Fast IEEE 754 floating-point formatter with correct rounding, shortness and
|
||
round-trip guarantees using the `Dragonbox <https://github.com/jk-jeon/dragonbox>`_
|
||
algorithm
|
||
* Portable Unicode support
|
||
* Safe `printf implementation
|
||
<https://fmt.dev/latest/api.html#printf-formatting>`_ including the POSIX
|
||
extension for positional arguments
|
||
* Extensibility: `support for user-defined types
|
||
<https://fmt.dev/latest/api.html#formatting-user-defined-types>`_
|
||
* High performance: faster than common standard library implementations of
|
||
``(s)printf``, iostreams, ``to_string`` and ``to_chars``, see `Speed tests`_
|
||
and `Converting a hundred million integers to strings per second
|
||
<http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_
|
||
* Small code size both in terms of source code with the minimum configuration
|
||
consisting of just three files, ``core.h``, ``format.h`` and ``format-inl.h``,
|
||
and compiled code; see `Compile time and code bloat`_
|
||
* Reliability: the library has an extensive set of `tests
|
||
<https://github.com/fmtlib/fmt/tree/master/test>`_ and is `continuously fuzzed
|
||
<https://bugs.chromium.org/p/oss-fuzz/issues/list?colspec=ID%20Type%20
|
||
Component%20Status%20Proj%20Reported%20Owner%20Summary&q=proj%3Dfmt&can=1>`_
|
||
* Safety: the library is fully type-safe, errors in format strings can be
|
||
reported at compile time, automatic memory management prevents buffer overflow
|
||
errors
|
||
* Ease of use: small self-contained code base, no external dependencies,
|
||
permissive MIT `license
|
||
<https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_
|
||
* `Portability <https://fmt.dev/latest/index.html#portability>`_ with
|
||
consistent output across platforms and support for older compilers
|
||
* Clean warning-free codebase even on high warning levels such as
|
||
``-Wall -Wextra -pedantic``
|
||
* Locale independence by default
|
||
* Optional header-only configuration enabled with the ``FMT_HEADER_ONLY`` macro
|
||
|
||
See the `documentation <https://fmt.dev>`_ for more details.
|
||
|
||
Examples
|
||
--------
|
||
|
||
**Print to stdout** (`run <https://godbolt.org/z/Tevcjh>`_)
|
||
|
||
.. code:: c++
|
||
|
||
#include <fmt/core.h>
|
||
|
||
int main() {
|
||
fmt::print("Hello, world!\n");
|
||
}
|
||
|
||
**Format a string** (`run <https://godbolt.org/z/oK8h33>`_)
|
||
|
||
.. code:: c++
|
||
|
||
std::string s = fmt::format("The answer is {}.", 42);
|
||
// s == "The answer is 42."
|
||
|
||
**Format a string using positional arguments** (`run <https://godbolt.org/z/Yn7Txe>`_)
|
||
|
||
.. code:: c++
|
||
|
||
std::string s = fmt::format("I'd rather be {1} than {0}.", "right", "happy");
|
||
// s == "I'd rather be happy than right."
|
||
|
||
**Print chrono durations** (`run <https://godbolt.org/z/K8s4Mc>`_)
|
||
|
||
.. code:: c++
|
||
|
||
#include <fmt/chrono.h>
|
||
|
||
int main() {
|
||
using namespace std::literals::chrono_literals;
|
||
fmt::print("Default format: {} {}\n", 42s, 100ms);
|
||
fmt::print("strftime-like format: {:%H:%M:%S}\n", 3h + 15min + 30s);
|
||
}
|
||
|
||
Output::
|
||
|
||
Default format: 42s 100ms
|
||
strftime-like format: 03:15:30
|
||
|
||
**Print a container** (`run <https://godbolt.org/z/MxM1YqjE7>`_)
|
||
|
||
.. code:: c++
|
||
|
||
#include <vector>
|
||
#include <fmt/ranges.h>
|
||
|
||
int main() {
|
||
std::vector<int> v = {1, 2, 3};
|
||
fmt::print("{}\n", v);
|
||
}
|
||
|
||
Output::
|
||
|
||
[1, 2, 3]
|
||
|
||
**Check a format string at compile time**
|
||
|
||
.. code:: c++
|
||
|
||
std::string s = fmt::format("{:d}", "I am not a number");
|
||
|
||
This gives a compile-time error in C++20 because ``d`` is an invalid format
|
||
specifier for a string.
|
||
|
||
**Write a file from a single thread**
|
||
|
||
.. code:: c++
|
||
|
||
#include <fmt/os.h>
|
||
|
||
int main() {
|
||
auto out = fmt::output_file("guide.txt");
|
||
out.print("Don't {}", "Panic");
|
||
}
|
||
|
||
This can be `5 to 9 times faster than fprintf
|
||
<http://www.zverovich.net/2020/08/04/optimal-file-buffer-size.html>`_.
|
||
|
||
**Print with colors and text styles**
|
||
|
||
.. code:: c++
|
||
|
||
#include <fmt/color.h>
|
||
|
||
int main() {
|
||
fmt::print(fg(fmt::color::crimson) | fmt::emphasis::bold,
|
||
"Hello, {}!\n", "world");
|
||
fmt::print(fg(fmt::color::floral_white) | bg(fmt::color::slate_gray) |
|
||
fmt::emphasis::underline, "Hello, {}!\n", "мир");
|
||
fmt::print(fg(fmt::color::steel_blue) | fmt::emphasis::italic,
|
||
"Hello, {}!\n", "世界");
|
||
}
|
||
|
||
Output on a modern terminal:
|
||
|
||
.. image:: https://user-images.githubusercontent.com/
|
||
576385/88485597-d312f600-cf2b-11ea-9cbe-61f535a86e28.png
|
||
|
||
Benchmarks
|
||
----------
|
||
|
||
Speed tests
|
||
~~~~~~~~~~~
|
||
|
||
================= ============= ===========
|
||
Library Method Run Time, s
|
||
================= ============= ===========
|
||
libc printf 0.91
|
||
libc++ std::ostream 2.49
|
||
{fmt} 9.1 fmt::print 0.74
|
||
Boost Format 1.80 boost::format 6.26
|
||
Folly Format folly::format 1.87
|
||
================= ============= ===========
|
||
|
||
{fmt} is the fastest of the benchmarked methods, ~20% faster than ``printf``.
|
||
|
||
The above results were generated by building ``tinyformat_test.cpp`` on macOS
|
||
12.6.1 with ``clang++ -O3 -DNDEBUG -DSPEED_TEST -DHAVE_FORMAT``, and taking the
|
||
best of three runs. In the test, the format string ``"%0.10f:%04d:%+g:%s:%p:%c:%%\n"``
|
||
or equivalent is filled 2,000,000 times with output sent to ``/dev/null``; for
|
||
further details refer to the `source
|
||
<https://github.com/fmtlib/format-benchmark/blob/master/src/tinyformat-test.cc>`_.
|
||
|
||
{fmt} is up to 20-30x faster than ``std::ostringstream`` and ``sprintf`` on
|
||
IEEE754 ``float`` and ``double`` formatting (`dtoa-benchmark <https://github.com/fmtlib/dtoa-benchmark>`_)
|
||
and faster than `double-conversion <https://github.com/google/double-conversion>`_ and
|
||
`ryu <https://github.com/ulfjack/ryu>`_:
|
||
|
||
.. image:: https://user-images.githubusercontent.com/576385/
|
||
95684665-11719600-0ba8-11eb-8e5b-972ff4e49428.png
|
||
:target: https://fmt.dev/unknown_mac64_clang12.0.html
|
||
|
||
Compile time and code bloat
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The script `bloat-test.py
|
||
<https://github.com/fmtlib/format-benchmark/blob/master/bloat-test.py>`_
|
||
from `format-benchmark <https://github.com/fmtlib/format-benchmark>`_
|
||
tests compile time and code bloat for nontrivial projects.
|
||
It generates 100 translation units and uses ``printf()`` or its alternative
|
||
five times in each to simulate a medium-sized project. The resulting
|
||
executable size and compile time (Apple LLVM version 8.1.0 (clang-802.0.42),
|
||
macOS Sierra, best of three) is shown in the following tables.
|
||
|
||
**Optimized build (-O3)**
|
||
|
||
============= =============== ==================== ==================
|
||
Method Compile Time, s Executable size, KiB Stripped size, KiB
|
||
============= =============== ==================== ==================
|
||
printf 2.6 29 26
|
||
printf+string 16.4 29 26
|
||
iostreams 31.1 59 55
|
||
{fmt} 19.0 37 34
|
||
Boost Format 91.9 226 203
|
||
Folly Format 115.7 101 88
|
||
============= =============== ==================== ==================
|
||
|
||
As you can see, {fmt} has 60% less overhead in terms of resulting binary code
|
||
size compared to iostreams and comes pretty close to ``printf``. Boost Format
|
||
and Folly Format have the largest overheads.
|
||
|
||
``printf+string`` is the same as ``printf`` but with an extra ``<string>``
|
||
include to measure the overhead of the latter.
|
||
|
||
**Non-optimized build**
|
||
|
||
============= =============== ==================== ==================
|
||
Method Compile Time, s Executable size, KiB Stripped size, KiB
|
||
============= =============== ==================== ==================
|
||
printf 2.2 33 30
|
||
printf+string 16.0 33 30
|
||
iostreams 28.3 56 52
|
||
{fmt} 18.2 59 50
|
||
Boost Format 54.1 365 303
|
||
Folly Format 79.9 445 430
|
||
============= =============== ==================== ==================
|
||
|
||
``libc``, ``lib(std)c++``, and ``libfmt`` are all linked as shared libraries to
|
||
compare formatting function overhead only. Boost Format is a
|
||
header-only library so it doesn't provide any linkage options.
|
||
|
||
Running the tests
|
||
~~~~~~~~~~~~~~~~~
|
||
|
||
Please refer to `Building the library`__ for instructions on how to build
|
||
the library and run the unit tests.
|
||
|
||
__ https://fmt.dev/latest/usage.html#building-the-library
|
||
|
||
Benchmarks reside in a separate repository,
|
||
`format-benchmarks <https://github.com/fmtlib/format-benchmark>`_,
|
||
so to run the benchmarks you first need to clone this repository and
|
||
generate Makefiles with CMake::
|
||
|
||
$ git clone --recursive https://github.com/fmtlib/format-benchmark.git
|
||
$ cd format-benchmark
|
||
$ cmake .
|
||
|
||
Then you can run the speed test::
|
||
|
||
$ make speed-test
|
||
|
||
or the bloat test::
|
||
|
||
$ make bloat-test
|
||
|
||
Migrating code
|
||
--------------
|
||
|
||
`clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`_ v17 (not yet
|
||
released) provides the `modernize-use-std-print
|
||
<https://clang.llvm.org/extra/clang-tidy/checks/modernize/use-std-print.html>`_
|
||
check that is capable of converting occurrences of ``printf`` and
|
||
``fprintf`` to ``fmt::print`` if configured to do so. (By default it
|
||
converts to ``std::print``.)
|
||
|
||
Projects using this library
|
||
---------------------------
|
||
|
||
* `0 A.D. <https://play0ad.com/>`_: a free, open-source, cross-platform
|
||
real-time strategy game
|
||
|
||
* `AMPL/MP <https://github.com/ampl/mp>`_:
|
||
an open-source library for mathematical programming
|
||
|
||
* `Aseprite <https://github.com/aseprite/aseprite>`_:
|
||
animated sprite editor & pixel art tool
|
||
|
||
* `AvioBook <https://www.aviobook.aero/en>`_: a comprehensive aircraft
|
||
operations suite
|
||
|
||
* `Blizzard Battle.net <https://battle.net/>`_: an online gaming platform
|
||
|
||
* `Celestia <https://celestia.space/>`_: real-time 3D visualization of space
|
||
|
||
* `Ceph <https://ceph.com/>`_: a scalable distributed storage system
|
||
|
||
* `ccache <https://ccache.dev/>`_: a compiler cache
|
||
|
||
* `ClickHouse <https://github.com/ClickHouse/ClickHouse>`_: an analytical database
|
||
management system
|
||
|
||
* `Contour <https://github.com/contour-terminal/contour/>`_: a modern terminal emulator
|
||
|
||
* `CUAUV <https://cuauv.org/>`_: Cornell University's autonomous underwater
|
||
vehicle
|
||
|
||
* `Drake <https://drake.mit.edu/>`_: a planning, control, and analysis toolbox
|
||
for nonlinear dynamical systems (MIT)
|
||
|
||
* `Envoy <https://lyft.github.io/envoy/>`_: C++ L7 proxy and communication bus
|
||
(Lyft)
|
||
|
||
* `FiveM <https://fivem.net/>`_: a modification framework for GTA V
|
||
|
||
* `fmtlog <https://github.com/MengRao/fmtlog>`_: a performant fmtlib-style
|
||
logging library with latency in nanoseconds
|
||
|
||
* `Folly <https://github.com/facebook/folly>`_: Facebook open-source library
|
||
|
||
* `GemRB <https://gemrb.org/>`_: a portable open-source implementation of
|
||
Bioware’s Infinity Engine
|
||
|
||
* `Grand Mountain Adventure
|
||
<https://store.steampowered.com/app/1247360/Grand_Mountain_Adventure/>`_:
|
||
a beautiful open-world ski & snowboarding game
|
||
|
||
* `HarpyWar/pvpgn <https://github.com/pvpgn/pvpgn-server>`_:
|
||
Player vs Player Gaming Network with tweaks
|
||
|
||
* `KBEngine <https://github.com/kbengine/kbengine>`_: an open-source MMOG server
|
||
engine
|
||
|
||
* `Keypirinha <https://keypirinha.com/>`_: a semantic launcher for Windows
|
||
|
||
* `Kodi <https://kodi.tv/>`_ (formerly xbmc): home theater software
|
||
|
||
* `Knuth <https://kth.cash/>`_: high-performance Bitcoin full-node
|
||
|
||
* `libunicode <https://github.com/contour-terminal/libunicode/>`_: a modern C++17 Unicode library
|
||
|
||
* `MariaDB <https://mariadb.org/>`_: relational database management system
|
||
|
||
* `Microsoft Verona <https://github.com/microsoft/verona>`_:
|
||
research programming language for concurrent ownership
|
||
|
||
* `MongoDB <https://mongodb.com/>`_: distributed document database
|
||
|
||
* `MongoDB Smasher <https://github.com/duckie/mongo_smasher>`_: a small tool to
|
||
generate randomized datasets
|
||
|
||
* `OpenSpace <https://openspaceproject.com/>`_: an open-source
|
||
astrovisualization framework
|
||
|
||
* `PenUltima Online (POL) <https://www.polserver.com/>`_:
|
||
an MMO server, compatible with most Ultima Online clients
|
||
|
||
* `PyTorch <https://github.com/pytorch/pytorch>`_: an open-source machine
|
||
learning library
|
||
|
||
* `quasardb <https://www.quasardb.net/>`_: a distributed, high-performance,
|
||
associative database
|
||
|
||
* `Quill <https://github.com/odygrd/quill>`_: asynchronous low-latency logging library
|
||
|
||
* `QKW <https://github.com/ravijanjam/qkw>`_: generalizing aliasing to simplify
|
||
navigation, and executing complex multi-line terminal command sequences
|
||
|
||
* `redis-cerberus <https://github.com/HunanTV/redis-cerberus>`_: a Redis cluster
|
||
proxy
|
||
|
||
* `redpanda <https://vectorized.io/redpanda>`_: a 10x faster Kafka® replacement
|
||
for mission-critical systems written in C++
|
||
|
||
* `rpclib <http://rpclib.net/>`_: a modern C++ msgpack-RPC server and client
|
||
library
|
||
|
||
* `Salesforce Analytics Cloud
|
||
<https://www.salesforce.com/analytics-cloud/overview/>`_:
|
||
business intelligence software
|
||
|
||
* `Scylla <https://www.scylladb.com/>`_: a Cassandra-compatible NoSQL data store
|
||
that can handle 1 million transactions per second on a single server
|
||
|
||
* `Seastar <http://www.seastar-project.org/>`_: an advanced, open-source C++
|
||
framework for high-performance server applications on modern hardware
|
||
|
||
* `spdlog <https://github.com/gabime/spdlog>`_: super fast C++ logging library
|
||
|
||
* `Stellar <https://www.stellar.org/>`_: financial platform
|
||
|
||
* `Touch Surgery <https://www.touchsurgery.com/>`_: surgery simulator
|
||
|
||
* `TrinityCore <https://github.com/TrinityCore/TrinityCore>`_: open-source
|
||
MMORPG framework
|
||
|
||
* `🐙 userver framework <https://userver.tech/>`_: open-source asynchronous
|
||
framework with a rich set of abstractions and database drivers
|
||
|
||
* `Windows Terminal <https://github.com/microsoft/terminal>`_: the new Windows
|
||
terminal
|
||
|
||
`More... <https://github.com/search?q=fmtlib&type=Code>`_
|
||
|
||
If you are aware of other projects using this library, please let me know
|
||
by `email <mailto:victor.zverovich@gmail.com>`_ or by submitting an
|
||
`issue <https://github.com/fmtlib/fmt/issues>`_.
|
||
|
||
Motivation
|
||
----------
|
||
|
||
So why yet another formatting library?
|
||
|
||
There are plenty of methods for doing this task, from standard ones like
|
||
the printf family of function and iostreams to Boost Format and FastFormat
|
||
libraries. The reason for creating a new library is that every existing
|
||
solution that I found either had serious issues or didn't provide
|
||
all the features I needed.
|
||
|
||
printf
|
||
~~~~~~
|
||
|
||
The good thing about ``printf`` is that it is pretty fast and readily available
|
||
being a part of the C standard library. The main drawback is that it
|
||
doesn't support user-defined types. ``printf`` also has safety issues although
|
||
they are somewhat mitigated with `__attribute__ ((format (printf, ...))
|
||
<https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ in GCC.
|
||
There is a POSIX extension that adds positional arguments required for
|
||
`i18n <https://en.wikipedia.org/wiki/Internationalization_and_localization>`_
|
||
to ``printf`` but it is not a part of C99 and may not be available on some
|
||
platforms.
|
||
|
||
iostreams
|
||
~~~~~~~~~
|
||
|
||
The main issue with iostreams is best illustrated with an example:
|
||
|
||
.. code:: c++
|
||
|
||
std::cout << std::setprecision(2) << std::fixed << 1.23456 << "\n";
|
||
|
||
which is a lot of typing compared to printf:
|
||
|
||
.. code:: c++
|
||
|
||
printf("%.2f\n", 1.23456);
|
||
|
||
Matthew Wilson, the author of FastFormat, called this "chevron hell". iostreams
|
||
don't support positional arguments by design.
|
||
|
||
The good part is that iostreams support user-defined types and are safe although
|
||
error handling is awkward.
|
||
|
||
Boost Format
|
||
~~~~~~~~~~~~
|
||
|
||
This is a very powerful library that supports both ``printf``-like format
|
||
strings and positional arguments. Its main drawback is performance. According to
|
||
various benchmarks, it is much slower than other methods considered here. Boost
|
||
Format also has excessive build times and severe code bloat issues (see
|
||
`Benchmarks`_).
|
||
|
||
FastFormat
|
||
~~~~~~~~~~
|
||
|
||
This is an interesting library that is fast, safe, and has positional arguments.
|
||
However, it has significant limitations, citing its author:
|
||
|
||
Three features that have no hope of being accommodated within the
|
||
current design are:
|
||
|
||
* Leading zeros (or any other non-space padding)
|
||
* Octal/hexadecimal encoding
|
||
* Runtime width/alignment specification
|
||
|
||
It is also quite big and has a heavy dependency, STLSoft, which might be too
|
||
restrictive for using it in some projects.
|
||
|
||
Boost Spirit.Karma
|
||
~~~~~~~~~~~~~~~~~~
|
||
|
||
This is not a formatting library but I decided to include it here for
|
||
completeness. As iostreams, it suffers from the problem of mixing verbatim text
|
||
with arguments. The library is pretty fast, but slower on integer formatting
|
||
than ``fmt::format_to`` with format string compilation on Karma's own benchmark,
|
||
see `Converting a hundred million integers to strings per second
|
||
<http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_.
|
||
|
||
License
|
||
-------
|
||
|
||
{fmt} is distributed under the MIT `license
|
||
<https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_.
|
||
|
||
Documentation License
|
||
---------------------
|
||
|
||
The `Format String Syntax <https://fmt.dev/latest/syntax.html>`_
|
||
section in the documentation is based on the one from Python `string module
|
||
documentation <https://docs.python.org/3/library/string.html#module-string>`_.
|
||
For this reason, the documentation is distributed under the Python Software
|
||
Foundation license available in `doc/python-license.txt
|
||
<https://raw.github.com/fmtlib/fmt/master/doc/python-license.txt>`_.
|
||
It only applies if you distribute the documentation of {fmt}.
|
||
|
||
Maintainers
|
||
-----------
|
||
|
||
The {fmt} library is maintained by Victor Zverovich (`vitaut
|
||
<https://github.com/vitaut>`_) with contributions from many other people.
|
||
See `Contributors <https://github.com/fmtlib/fmt/graphs/contributors>`_ and
|
||
`Releases <https://github.com/fmtlib/fmt/releases>`_ for some of the names.
|
||
Let us know if your contribution is not listed or mentioned incorrectly and
|
||
we'll make it right.
|