2022-03-02 00:48:54 +03:00
.. image :: https://user-images.githubusercontent.com/
576385/156254208-f5b743a9-88cf-439d-b0c0-923d53e8d551.png
:width: 25%
:alt: {fmt}
2012-12-07 20:26:46 +04:00
2020-11-03 21:45:16 +03:00
.. image :: https://github.com/fmtlib/fmt/workflows/linux/badge.svg
2020-11-03 22:02:49 +03:00
:target: https://github.com/fmtlib/fmt/actions?query=workflow%3Alinux
2020-11-03 21:45:16 +03:00
.. image :: https://github.com/fmtlib/fmt/workflows/macos/badge.svg
2020-11-03 22:02:49 +03:00
:target: https://github.com/fmtlib/fmt/actions?query=workflow%3Amacos
2020-11-03 21:45:16 +03:00
.. image :: https://github.com/fmtlib/fmt/workflows/windows/badge.svg
2020-11-03 22:02:49 +03:00
:target: https://github.com/fmtlib/fmt/actions?query=workflow%3Awindows
2020-11-03 21:42:06 +03:00
2020-10-17 18:27:21 +03:00
.. image :: https://oss-fuzz-build-logs.storage.googleapis.com/badges/fmt.svg
2020-07-08 18:01:36 +03:00
:alt: fmt is continuously fuzzed at oss-fuzz
2020-07-04 18:27:57 +03:00
:target: https://bugs.chromium.org/p/oss-fuzz/issues/list?\
2020-07-04 19:37:27 +03:00
colspec=ID%20Type%20Component%20Status%20Proj%20Reported%20Owner%20\
2020-10-16 16:46:39 +03:00
Summary&q=proj%3Dfmt&can=1
2019-09-19 07:47:11 +03:00
2019-11-26 19:33:16 +03:00
.. image :: https://img.shields.io/badge/stackoverflow-fmt-blue.svg
:alt: Ask questions at StackOverflow with the tag fmt
2019-12-17 17:48:27 +03:00
:target: https://stackoverflow.com/questions/tagged/fmt
2019-11-26 19:33:16 +03:00
2023-08-04 23:50:17 +03:00
.. image :: https://api.securityscorecards.dev/projects/github.com/fmtlib/fmt/badge
:target: https://securityscorecards.dev/viewer/?uri=github.com/fmtlib/fmt
2020-10-01 03:38:28 +03:00
**{fmt}** is an open-source formatting library providing a fast and safe
alternative to C stdio and C++ iostreams.
2012-12-08 02:18:37 +04:00
2022-03-02 00:53:02 +03:00
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/.
2020-09-26 20:13:04 +03:00
2020-07-08 17:11:13 +03:00
`Documentation <https://fmt.dev> `__
2015-05-22 16:50:46 +03:00
2022-05-15 16:29:15 +03:00
`Cheat Sheets <https://hackingcpp.com/cpp/libs/fmt.html> `__
2020-07-04 18:20:10 +03:00
Q&A: ask questions on `StackOverflow with the tag fmt
<https://stackoverflow.com/questions/tagged/fmt> `_.
2019-05-10 19:56:40 +03:00
2020-07-28 18:18:10 +03:00
Try {fmt} in `Compiler Explorer <https://godbolt.org/z/Eq5763> `_ .
2020-07-26 22:12:31 +03:00
2012-12-08 02:18:37 +04:00
Features
--------
2020-07-13 16:15:47 +03:00
* Simple `format API <https://fmt.dev/latest/api.html> `_ with positional arguments
2020-07-04 18:20:10 +03:00
for localization
* Implementation of `C++20 std::format
2023-10-22 18:30:04 +03:00
<https://en.cppreference.com/w/cpp/utility/format>`__ and ` C++23 std::print
<https://en.cppreference.com/w/cpp/io/print>`__
2020-07-13 16:15:47 +03:00
* `Format string syntax <https://fmt.dev/latest/syntax.html> `_ similar to Python's
2020-07-04 18:20:10 +03:00
`format <https://docs.python.org/3/library/stdtypes.html#str.format> `_
2020-09-14 21:13:51 +03:00
* Fast IEEE 754 floating-point formatter with correct rounding, shortness and
2022-12-30 23:07:55 +03:00
round-trip guarantees using the `Dragonbox <https://github.com/jk-jeon/dragonbox> `_
algorithm
2023-05-13 02:24:47 +03:00
* Portable Unicode support
2015-02-26 20:05:20 +03:00
* Safe `printf implementation
2020-07-08 17:11:13 +03:00
<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>`_
2019-03-10 22:13:14 +03:00
* High performance: faster than common standard library implementations of
2020-07-08 17:11:13 +03:00
`` (s)printf `` , iostreams, `` to_string `` and `` to_chars `` , see `Speed tests`_
and `Converting a hundred million integers to strings per second
2020-07-04 18:27:57 +03:00
<http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_
2020-07-08 17:11:13 +03:00
* 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`_
2020-08-08 02:03:15 +03:00
* Reliability: the library has an extensive set of `tests
<https://github.com/fmtlib/fmt/tree/master/test>`_ and is ` continuously fuzzed
2020-08-09 04:01:56 +03:00
<https://bugs.chromium.org/p/oss-fuzz/issues/list?colspec=ID%20Type%20
2020-10-16 16:46:39 +03:00
Component%20Status%20Proj%20Reported%20Owner%20Summary&q=proj%3Dfmt&can=1>`_
2023-05-22 20:35:24 +03:00
* Safety: the library is fully type-safe, errors in format strings can be
2017-11-10 18:24:16 +03:00
reported at compile time, automatic memory management prevents buffer overflow
2020-07-04 18:20:10 +03:00
errors
2012-12-12 04:30:27 +04:00
* Ease of use: small self-contained code base, no external dependencies,
2019-09-06 23:13:30 +03:00
permissive MIT `license
2016-04-27 18:23:03 +03:00
<https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_
2019-05-18 01:42:00 +03:00
* `Portability <https://fmt.dev/latest/index.html#portability> `_ with
2020-07-04 18:20:10 +03:00
consistent output across platforms and support for older compilers
2020-07-08 17:11:13 +03:00
* Clean warning-free codebase even on high warning levels such as
`` -Wall -Wextra -pedantic ``
2023-05-22 20:35:24 +03:00
* Locale independence by default
2020-07-04 18:20:10 +03:00
* Optional header-only configuration enabled with the `` FMT_HEADER_ONLY `` macro
2012-12-08 02:18:37 +04:00
2020-07-08 17:11:13 +03:00
See the `documentation <https://fmt.dev> `_ for more details.
2013-01-21 22:11:59 +04:00
2012-12-08 02:32:48 +04:00
Examples
--------
2020-07-28 18:21:04 +03:00
**Print to stdout** (`run <https://godbolt.org/z/Tevcjh> `_ )
2014-11-07 18:04:03 +03:00
.. code :: c++
2012-12-08 02:18:37 +04:00
2020-06-20 15:37:58 +03:00
#include <fmt/core.h>
2023-09-16 16:55:22 +03:00
2020-06-20 15:37:58 +03:00
int main() {
fmt::print("Hello, world!\n");
}
2012-12-08 01:20:50 +04:00
2020-08-01 22:00:01 +03:00
**Format a string** (`run <https://godbolt.org/z/oK8h33> `_ )
2020-07-05 16:41:51 +03:00
.. code :: c++
std::string s = fmt::format("The answer is {}.", 42);
// s == "The answer is 42."
2020-08-04 07:51:48 +03:00
**Format a string using positional arguments** (`run <https://godbolt.org/z/Yn7Txe> `_ )
2019-03-16 17:36:27 +03:00
.. code :: c++
std::string s = fmt::format("I'd rather be {1} than {0}.", "right", "happy");
2019-03-16 17:59:58 +03:00
// s == "I'd rather be happy than right."
2019-03-16 17:36:27 +03:00
2020-07-28 18:35:28 +03:00
**Print chrono durations** (`run <https://godbolt.org/z/K8s4Mc> `_ )
2020-07-05 16:41:51 +03:00
.. code :: c++
#include <fmt/chrono.h>
int main() {
2020-07-08 17:11:13 +03:00
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);
2020-07-05 16:41:51 +03:00
}
2020-07-26 20:57:59 +03:00
Output::
2020-07-08 17:11:13 +03:00
Default format: 42s 100ms
strftime-like format: 03:15:30
2020-07-05 16:41:51 +03:00
2022-02-26 00:47:23 +03:00
**Print a container** (`run <https://godbolt.org/z/MxM1YqjE7> `_ )
2020-07-09 04:17:26 +03:00
.. code :: c++
2020-07-09 16:21:02 +03:00
#include <vector>
2020-07-09 04:17:26 +03:00
#include <fmt/ranges.h>
int main() {
std::vector<int> v = {1, 2, 3};
fmt::print("{}\n", v);
}
2020-07-26 20:57:59 +03:00
Output::
2020-07-09 04:17:26 +03:00
2021-05-09 19:35:44 +03:00
[1, 2, 3]
2020-07-09 04:17:26 +03:00
2020-07-26 20:57:59 +03:00
**Check a format string at compile time**
2017-11-10 18:38:51 +03:00
.. code :: c++
2021-07-04 17:03:20 +03:00
std::string s = fmt::format("{:d}", "I am not a number");
2020-07-08 17:44:36 +03:00
2021-07-04 17:03:20 +03:00
This gives a compile-time error in C++20 because `` d `` is an invalid format
specifier for a string.
2013-09-07 02:12:46 +04:00
2020-07-26 20:57:59 +03:00
**Write a file from a single thread**
2020-07-12 19:55:24 +03:00
.. code :: c++
#include <fmt/os.h>
int main() {
auto out = fmt::output_file("guide.txt");
out.print("Don't {}", "Panic");
}
2020-08-05 20:53:49 +03:00
This can be `5 to 9 times faster than fprintf
<http://www.zverovich.net/2020/08/04/optimal-file-buffer-size.html> `_.
2020-07-12 19:55:24 +03:00
2020-08-08 06:58:29 +03:00
**Print with colors and text styles**
2020-07-26 18:14:18 +03:00
.. 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) |
2023-10-22 19:13:14 +03:00
fmt::emphasis::underline, "Olá, {}!\n", "Mundo");
2020-07-26 18:14:18 +03:00
fmt::print(fg(fmt::color::steel_blue) | fmt::emphasis::italic,
2023-10-22 18:30:04 +03:00
"你好{}! \n", "世界");
2020-07-26 18:14:18 +03:00
}
2023-10-22 18:30:04 +03:00
Output on a modern terminal with Unicode support:
2020-07-26 18:14:18 +03:00
2023-10-22 18:30:04 +03:00
.. image :: https://github.com/fmtlib/fmt/assets/
2023-10-22 19:13:14 +03:00
576385/2a93c904-d6fa-4aa6-b453-2618e1c327d7
2020-07-26 18:14:18 +03:00
2019-03-16 17:27:53 +03:00
Benchmarks
----------
Speed tests
~~~~~~~~~~~
================= ============= ===========
Library Method Run Time, s
================= ============= ===========
2022-11-25 20:52:02 +03:00
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
2019-03-16 17:27:53 +03:00
================= ============= ===========
2022-11-25 20:52:02 +03:00
{fmt} is the fastest of the benchmarked methods, ~20% faster than `` printf `` .
2019-03-16 17:27:53 +03:00
The above results were generated by building `` tinyformat_test.cpp `` on macOS
2022-11-25 20:52:02 +03:00
12.6.1 with `` clang++ -O3 -DNDEBUG -DSPEED_TEST -DHAVE_FORMAT `` , and taking the
2020-07-04 18:20:10 +03:00
best of three runs. In the test, the format string `` "%0.10f:%04d:%+g:%s:%p:%c:%%\n" ``
2019-03-16 17:27:53 +03:00
or equivalent is filled 2,000,000 times with output sent to `` /dev/null `` ; for
further details refer to the `source
2021-11-19 19:43:48 +03:00
<https://github.com/fmtlib/format-benchmark/blob/master/src/tinyformat-test.cc> `_.
2019-03-16 17:27:53 +03:00
2020-10-11 19:57:21 +03:00
{fmt} is up to 20-30x faster than `` std::ostringstream `` and `` sprintf `` on
2022-12-06 22:52:37 +03:00
IEEE754 `` float `` and `` double `` formatting (`dtoa-benchmark <https://github.com/fmtlib/dtoa-benchmark> `_ )
2020-10-11 19:57:21 +03:00
and faster than `double-conversion <https://github.com/google/double-conversion> `_ and
`ryu <https://github.com/ulfjack/ryu> `_ :
2019-03-24 21:37:07 +03:00
2020-07-08 23:34:47 +03:00
.. image :: https://user-images.githubusercontent.com/576385/
2020-10-11 19:57:21 +03:00
95684665-11719600-0ba8-11eb-8e5b-972ff4e49428.png
:target: https://fmt.dev/unknown_mac64_clang12.0.html
2019-03-24 21:37:07 +03:00
2019-03-16 17:27:53 +03:00
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
2023-05-22 20:35:24 +03:00
five times in each to simulate a medium-sized project. The resulting
2019-03-16 17:27:53 +03:00
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.
2023-05-22 20:35:24 +03:00
`` printf+string `` is the same as `` printf `` but with an extra `` <string> ``
2019-03-16 17:27:53 +03:00
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
============= =============== ==================== ==================
2023-05-22 20:35:24 +03:00
`` libc `` , `` lib(std)c++ `` , and `` libfmt `` are all linked as shared libraries to
2019-11-20 20:33:59 +03:00
compare formatting function overhead only. Boost Format is a
header-only library so it doesn't provide any linkage options.
2019-03-16 17:27:53 +03:00
Running the tests
~~~~~~~~~~~~~~~~~
2023-05-22 20:35:24 +03:00
Please refer to `Building the library`__ for instructions on how to build
2019-03-16 17:27:53 +03:00
the library and run the unit tests.
2019-05-18 01:42:00 +03:00
__ https://fmt.dev/latest/usage.html#building-the-library
2019-03-16 17:27:53 +03:00
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
2023-09-16 16:55:22 +03:00
2021-04-10 18:31:47 +03:00
Migrating code
--------------
2023-07-01 01:49:36 +03:00
`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 `` .)
2019-03-16 17:27:53 +03:00
2014-01-30 23:16:27 +04:00
Projects using this library
---------------------------
2020-10-19 18:54:55 +03:00
* `0 A.D. <https://play0ad.com/> `_ : a free, open-source, cross-platform
2020-04-22 16:07:12 +03:00
real-time strategy game
2015-02-07 00:46:19 +03:00
2014-10-13 01:18:17 +04:00
* `AMPL/MP <https://github.com/ampl/mp> `_ :
2020-10-19 18:54:55 +03:00
an open-source library for mathematical programming
2020-06-12 03:25:20 +03:00
* `Aseprite <https://github.com/aseprite/aseprite> `_ :
2023-09-16 16:55:22 +03:00
animated sprite editor & pixel art tool
2020-06-12 03:25:20 +03:00
2020-10-19 18:54:55 +03:00
* `AvioBook <https://www.aviobook.aero/en> `_ : a comprehensive aircraft
2018-11-29 04:28:27 +03:00
operations suite
2023-09-16 16:55:22 +03:00
2020-10-19 18:54:55 +03:00
* `Blizzard Battle.net <https://battle.net/> `_ : an online gaming platform
2023-09-16 16:55:22 +03:00
2020-10-19 18:54:55 +03:00
* `Celestia <https://celestia.space/> `_ : real-time 3D visualization of space
2014-01-30 23:16:27 +04:00
2020-10-19 18:54:55 +03:00
* `Ceph <https://ceph.com/> `_ : a scalable distributed storage system
2018-11-29 04:28:27 +03:00
2020-10-19 18:54:55 +03:00
* `ccache <https://ccache.dev/> `_ : a compiler cache
2019-09-06 16:26:09 +03:00
2022-11-08 22:21:16 +03:00
* `ClickHouse <https://github.com/ClickHouse/ClickHouse> `_ : an analytical database
2020-07-08 17:36:07 +03:00
management system
2023-09-16 16:55:22 +03:00
2022-11-08 22:21:16 +03:00
* `Contour <https://github.com/contour-terminal/contour/> `_ : a modern terminal emulator
2020-07-05 15:57:04 +03:00
2020-12-05 17:41:38 +03:00
* `CUAUV <https://cuauv.org/> `_ : Cornell University's autonomous underwater
2018-11-29 04:28:27 +03:00
vehicle
2016-08-10 18:29:44 +03:00
2020-10-19 18:54:55 +03:00
* `Drake <https://drake.mit.edu/> `_ : a planning, control, and analysis toolbox
2020-04-22 16:07:12 +03:00
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
2021-05-06 18:39:36 +03:00
* `fmtlog <https://github.com/MengRao/fmtlog> `_ : a performant fmtlib-style
logging library with latency in nanoseconds
2020-04-22 16:16:07 +03:00
* `Folly <https://github.com/facebook/folly> `_ : Facebook open-source library
2022-05-29 21:44:09 +03:00
* `GemRB <https://gemrb.org/> `_ : a portable open-source implementation of
Bioware’ s Infinity Engine
2021-06-05 16:32:22 +03:00
* `Grand Mountain Adventure
<https://store.steampowered.com/app/1247360/Grand_Mountain_Adventure/>`_:
2022-05-29 21:44:09 +03:00
a beautiful open-world ski & snowboarding game
2021-06-05 16:32:22 +03:00
2015-12-03 19:09:53 +03:00
* `HarpyWar/pvpgn <https://github.com/pvpgn/pvpgn-server> `_ :
2014-06-29 06:17:13 +04:00
Player vs Player Gaming Network with tweaks
2020-10-19 18:54:55 +03:00
* `KBEngine <https://github.com/kbengine/kbengine> `_ : an open-source MMOG server
2020-07-08 18:01:36 +03:00
engine
2014-09-13 19:44:49 +04:00
2020-10-19 18:54:55 +03:00
* `Keypirinha <https://keypirinha.com/> `_ : a semantic launcher for Windows
2016-03-10 21:51:52 +03:00
2020-10-19 18:54:55 +03:00
* `Kodi <https://kodi.tv/> `_ (formerly xbmc): home theater software
2018-01-28 04:47:41 +03:00
2020-10-19 18:54:55 +03:00
* `Knuth <https://kth.cash/> `_ : high-performance Bitcoin full-node
2020-05-20 04:08:32 +03:00
2022-11-08 22:21:16 +03:00
* `libunicode <https://github.com/contour-terminal/libunicode/> `_ : a modern C++17 Unicode library
2022-10-17 23:33:05 +03:00
* `MariaDB <https://mariadb.org/> `_ : relational database management system
2020-06-12 03:25:20 +03:00
* `Microsoft Verona <https://github.com/microsoft/verona> `_ :
2020-10-19 18:54:55 +03:00
research programming language for concurrent ownership
2014-10-13 01:18:17 +04:00
2020-10-19 18:54:55 +03:00
* `MongoDB <https://mongodb.com/> `_ : distributed document database
2019-04-12 19:47:21 +03:00
2020-10-19 18:54:55 +03:00
* `MongoDB Smasher <https://github.com/duckie/mongo_smasher> `_ : a small tool to
2018-02-02 03:44:27 +03:00
generate randomized datasets
2016-03-02 01:28:52 +03:00
2020-10-19 18:54:55 +03:00
* `OpenSpace <https://openspaceproject.com/> `_ : an open-source
2020-04-22 16:07:12 +03:00
astrovisualization framework
2018-02-03 06:10:25 +03:00
2019-12-17 17:48:27 +03:00
* `PenUltima Online (POL) <https://www.polserver.com/> `_ :
2020-10-19 18:54:55 +03:00
an MMO server, compatible with most Ultima Online clients
2015-02-07 19:31:17 +03:00
2020-10-19 18:54:55 +03:00
* `PyTorch <https://github.com/pytorch/pytorch> `_ : an open-source machine
2020-05-01 20:39:28 +03:00
learning library
2020-10-19 18:54:55 +03:00
* `quasardb <https://www.quasardb.net/> `_ : a distributed, high-performance,
2018-02-03 06:10:25 +03:00
associative database
2023-09-16 16:55:22 +03:00
2020-10-19 18:54:55 +03:00
* `Quill <https://github.com/odygrd/quill> `_ : asynchronous low-latency logging library
2015-04-27 17:02:15 +03:00
2020-10-19 18:54:55 +03:00
* `QKW <https://github.com/ravijanjam/qkw> `_ : generalizing aliasing to simplify
2020-09-21 19:40:49 +03:00
navigation, and executing complex multi-line terminal command sequences
2020-09-21 19:39:07 +03:00
2020-10-19 18:54:55 +03:00
* `redis-cerberus <https://github.com/HunanTV/redis-cerberus> `_ : a Redis cluster
2018-11-29 04:28:27 +03:00
proxy
2015-09-17 07:33:51 +03:00
2020-10-19 18:54:55 +03:00
* `redpanda <https://vectorized.io/redpanda> `_ : a 10x faster Kafka® replacement
2023-05-22 20:35:24 +03:00
for mission-critical systems written in C++
2020-04-22 04:44:14 +03:00
2020-10-19 18:54:55 +03:00
* `rpclib <http://rpclib.net/> `_ : a modern C++ msgpack-RPC server and client
2018-12-05 17:42:33 +03:00
library
2020-04-22 16:07:12 +03:00
* `Salesforce Analytics Cloud
<https://www.salesforce.com/analytics-cloud/overview/>`_:
2020-10-19 18:54:55 +03:00
business intelligence software
2014-12-02 23:54:12 +03:00
2020-10-19 18:54:55 +03:00
* `Scylla <https://www.scylladb.com/> `_ : a Cassandra-compatible NoSQL data store
2018-11-29 04:28:27 +03:00
that can handle 1 million transactions per second on a single server
2016-08-10 18:29:44 +03:00
2020-10-19 18:54:55 +03:00
* `Seastar <http://www.seastar-project.org/> `_ : an advanced, open-source C++
2018-11-29 04:28:27 +03:00
framework for high-performance server applications on modern hardware
2016-08-10 18:29:44 +03:00
2020-10-19 18:54:55 +03:00
* `spdlog <https://github.com/gabime/spdlog> `_ : super fast C++ logging library
2014-12-08 17:15:31 +03:00
2020-10-19 18:54:55 +03:00
* `Stellar <https://www.stellar.org/> `_ : financial platform
2015-09-17 07:45:27 +03:00
2020-10-19 18:54:55 +03:00
* `Touch Surgery <https://www.touchsurgery.com/> `_ : surgery simulator
2015-08-09 04:58:25 +03:00
2020-10-19 18:54:55 +03:00
* `TrinityCore <https://github.com/TrinityCore/TrinityCore> `_ : open-source
2018-11-29 04:28:27 +03:00
MMORPG framework
2015-03-18 05:43:47 +03:00
2023-02-26 14:07:06 +03:00
* `🐙 userver framework <https://userver.tech/> `_ : open-source asynchronous
framework with a rich set of abstractions and database drivers
2020-10-19 18:54:55 +03:00
* `Windows Terminal <https://github.com/microsoft/terminal> `_ : the new Windows
terminal
2020-04-22 01:47:04 +03:00
2019-09-06 23:03:14 +03:00
`More... <https://github.com/search?q=fmtlib&type=Code> `_
2015-02-07 01:03:44 +03:00
2014-06-29 22:51:27 +04:00
If you are aware of other projects using this library, please let me know
2014-10-13 01:18:17 +04:00
by `email <mailto:victor.zverovich@gmail.com> `_ or by submitting an
2016-04-27 18:23:03 +03:00
`issue <https://github.com/fmtlib/fmt/issues> `_ .
2014-01-30 23:16:27 +04:00
2012-12-08 03:33:27 +04:00
Motivation
----------
So why yet another formatting library?
There are plenty of methods for doing this task, from standard ones like
2019-03-16 16:30:50 +03:00
the printf family of function and iostreams to Boost Format and FastFormat
2019-03-12 16:08:18 +03:00
libraries. The reason for creating a new library is that every existing
2012-12-08 03:33:27 +04:00
solution that I found either had serious issues or didn't provide
all the features I needed.
2019-03-16 16:46:19 +03:00
printf
2012-12-08 03:33:27 +04:00
~~~~~~
2019-03-16 16:46:19 +03:00
The good thing about `` printf `` is that it is pretty fast and readily available
2014-05-15 06:17:20 +04:00
being a part of the C standard library. The main drawback is that it
2019-03-16 16:47:18 +03:00
doesn't support user-defined types. `` printf `` also has safety issues although
2019-03-16 16:46:19 +03:00
they are somewhat mitigated with `__attribute__ ((format (printf, ...))
2019-12-17 17:48:27 +03:00
<https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html> `_ in GCC.
2012-12-09 22:09:15 +04:00
There is a POSIX extension that adds positional arguments required for
2015-12-03 19:09:53 +03:00
`i18n <https://en.wikipedia.org/wiki/Internationalization_and_localization> `_
2019-03-16 16:46:19 +03:00
to `` printf `` but it is not a part of C99 and may not be available on some
2012-12-09 22:09:15 +04:00
platforms.
2012-12-08 03:33:27 +04:00
2019-03-16 16:30:50 +03:00
iostreams
2012-12-08 03:33:27 +04:00
~~~~~~~~~
2019-03-16 16:30:50 +03:00
The main issue with iostreams is best illustrated with an example:
2012-12-13 20:12:09 +04:00
2014-11-07 18:04:03 +03:00
.. code :: c++
2012-12-08 03:33:27 +04:00
std::cout << std::setprecision(2) << std::fixed << 1.23456 << "\n";
2012-12-13 20:12:09 +04:00
which is a lot of typing compared to printf:
2014-11-07 18:04:03 +03:00
.. code :: c++
2012-12-08 03:33:27 +04:00
printf("%.2f\n", 1.23456);
2019-03-16 16:30:50 +03:00
Matthew Wilson, the author of FastFormat, called this "chevron hell". iostreams
don't support positional arguments by design.
2012-12-08 03:33:27 +04:00
2019-03-16 16:30:50 +03:00
The good part is that iostreams support user-defined types and are safe although
2019-03-16 16:46:19 +03:00
error handling is awkward.
2012-12-08 03:33:27 +04:00
2019-03-16 16:46:19 +03:00
Boost Format
~~~~~~~~~~~~
2012-12-08 03:33:27 +04:00
2023-05-22 20:35:24 +03:00
This is a very powerful library that supports both `` printf `` -like format
2019-03-16 16:46:19 +03:00
strings and positional arguments. Its main drawback is performance. According to
2021-09-28 19:53:37 +03:00
various benchmarks, it is much slower than other methods considered here. Boost
2019-03-16 16:46:19 +03:00
Format also has excessive build times and severe code bloat issues (see
`Benchmarks`_ ).
2012-12-08 03:33:27 +04:00
FastFormat
~~~~~~~~~~
2023-05-22 20:35:24 +03:00
This is an interesting library that is fast, safe, and has positional arguments.
2020-07-04 18:20:10 +03:00
However, it has significant limitations, citing its author:
2012-12-08 03:33:27 +04:00
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
2020-07-04 18:20:10 +03:00
It is also quite big and has a heavy dependency, STLSoft, which might be too
restrictive for using it in some projects.
2012-12-08 03:33:27 +04:00
2012-12-25 09:31:05 +04:00
Boost Spirit.Karma
~~~~~~~~~~~~~~~~~~
2023-05-22 20:35:24 +03:00
This is not a formatting library but I decided to include it here for
2019-03-16 16:46:19 +03:00
completeness. As iostreams, it suffers from the problem of mixing verbatim text
with arguments. The library is pretty fast, but slower on integer formatting
2020-07-04 18:20:10 +03:00
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> `_.
2018-08-15 16:34:34 +03:00
2012-12-12 19:44:41 +04:00
License
-------
2019-09-06 23:13:30 +03:00
{fmt} is distributed under the MIT `license
2023-09-23 01:54:40 +03:00
<https://github.com/fmtlib/fmt/blob/master/LICENSE> `_.
2013-01-14 18:43:31 +04:00
2020-07-04 18:20:10 +03:00
Documentation License
---------------------
The `Format String Syntax <https://fmt.dev/latest/syntax.html> `_
2013-01-14 18:43:31 +04:00
section in the documentation is based on the one from Python `string module
2020-07-04 18:20:10 +03:00
documentation <https://docs.python.org/3/library/string.html#module-string>`_.
2023-05-22 20:35:24 +03:00
For this reason, the documentation is distributed under the Python Software
2020-07-04 18:20:10 +03:00
Foundation license available in `doc/python-license.txt
2016-04-27 18:28:24 +03:00
<https://raw.github.com/fmtlib/fmt/master/doc/python-license.txt> `_.
2020-07-04 18:20:10 +03:00
It only applies if you distribute the documentation of {fmt}.
2013-01-14 18:43:31 +04:00
2020-07-04 18:20:10 +03:00
Maintainers
-----------
2012-12-08 01:20:50 +04:00
2019-03-16 17:27:53 +03:00
The {fmt} library is maintained by Victor Zverovich (`vitaut
2023-04-23 23:35:05 +03:00
<https://github.com/vitaut> `_) with contributions from many other people.
2018-01-21 04:12:43 +03:00
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.
2023-09-29 02:50:14 +03:00
Security Policy
---------------
2023-09-30 17:16:04 +03:00
To report a security issue, please disclose it at `security advisory <https://github.com/fmtlib/fmt/security/advisories/new> `_ .
2023-09-29 02:50:14 +03:00
This project is maintained by a team of volunteers on a reasonable-effort basis. As such, please give us at least 90 days to work on a fix before public exposure.