summaryrefslogtreecommitdiff
path: root/deps/fmt/README.rst
diff options
context:
space:
mode:
authorKargatum <dowlandtop@yandex.com>2021-05-20 22:24:08 +0700
committerGitHub <noreply@github.com>2021-05-20 17:24:08 +0200
commitd86a7b96c3cdb4b20012d01cde31941959436533 (patch)
treecb586eda6ef174253d39d5a689a5523a9b02c2b1 /deps/fmt/README.rst
parent7f3734375e173d5e7e5c38113878be8bfb9f678d (diff)
feat(Deps/FmtLib): update fmtlib to 7.1.3 (#5950)
Diffstat (limited to 'deps/fmt/README.rst')
-rw-r--r--deps/fmt/README.rst462
1 files changed, 236 insertions, 226 deletions
diff --git a/deps/fmt/README.rst b/deps/fmt/README.rst
index f08b22faef..7cf794e4ac 100644
--- a/deps/fmt/README.rst
+++ b/deps/fmt/README.rst
@@ -1,157 +1,186 @@
{fmt}
=====
-.. image:: https://travis-ci.org/fmtlib/fmt.png?branch=master
- :target: https://travis-ci.org/fmtlib/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://ci.appveyor.com/api/projects/status/ehjkiefde6gucy1v
:target: https://ci.appveyor.com/project/vitaut/fmt
+.. 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: http://stackoverflow.com/questions/tagged/fmt
+ :target: https://stackoverflow.com/questions/tagged/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 BY_Help,
+an initiative to help victims of political repressions in Belarus:
+https://www.facebook.com/donate/199475051809330/.
-**{fmt}** is an open-source formatting library for C++.
-It can be used as a safe and fast alternative to (s)printf and iostreams.
+`Documentation <https://fmt.dev>`__
-`Documentation <https://fmt.dev/latest/>`__
+Q&A: ask questions on `StackOverflow with the tag fmt
+<https://stackoverflow.com/questions/tagged/fmt>`_.
-Q&A: ask questions on `StackOverflow with the tag fmt <http://stackoverflow.com/questions/tagged/fmt>`_.
+Try {fmt} in `Compiler Explorer <https://godbolt.org/z/Eq5763>`_.
Features
--------
-* Replacement-based `format API <https://fmt.dev/dev/api.html>`_ with
- positional arguments for localization.
-* `Format string syntax <https://fmt.dev/dev/syntax.html>`_ similar to the one
- of `str.format <https://docs.python.org/2/library/stdtypes.html#str.format>`_
- in Python.
+* 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
* Safe `printf implementation
- <https://fmt.dev/latest/api.html#printf-formatting>`_ including
- the POSIX extension for positional arguments.
-* Implementation of `C++20 std::format <https://fmt.dev/Text%20Formatting.html>`__.
-* Support for user-defined types.
+ <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
- `printf <http://en.cppreference.com/w/cpp/io/c/fprintf>`_ and
- iostreams. See `Speed tests`_ and `Fast integer to string conversion in C++
- <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
-* Small code size both in terms of source code (the minimum configuration
- consists of just three header 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 `unit tests
- <https://github.com/fmtlib/fmt/tree/master/test>`_.
+ ``(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.
+ errors
* Ease of use: small self-contained code base, no external dependencies,
- permissive BSD `license
+ 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
- (``-Wall -Wextra -pedantic``).
-* Support for wide strings.
-* Optional header-only configuration enabled with the ``FMT_HEADER_ONLY`` macro.
+ 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/latest/>`_ for more details.
+See the `documentation <https://fmt.dev>`_ for more details.
Examples
--------
-Print ``Hello, world!`` to ``stdout``:
+**Print to stdout** (`run <https://godbolt.org/z/Tevcjh>`_)
.. code:: c++
- fmt::print("Hello, {}!", "world"); // Python-like format string syntax
- fmt::printf("Hello, %s!", "world"); // printf format string syntax
+ #include <fmt/core.h>
+
+ int main() {
+ fmt::print("Hello, world!\n");
+ }
-Format a string and use positional arguments:
+**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."
-Check a format string at compile time:
+**Print chrono durations** (`run <https://godbolt.org/z/K8s4Mc>`_)
.. code:: c++
- // test.cc
- #define FMT_STRING_ALIAS 1
- #include <fmt/format.h>
- std::string s = format(fmt("{2}"), 42);
+ #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);
+ }
-.. code::
+Output::
- $ c++ -Iinclude -std=c++14 test.cc
- ...
- test.cc:4:17: note: in instantiation of function template specialization 'fmt::v5::format<S, int>' requested here
- std::string s = format(fmt("{2}"), 42);
- ^
- include/fmt/core.h:778:19: note: non-constexpr function 'on_error' cannot be used in a constant expression
- ErrorHandler::on_error(message);
- ^
- include/fmt/format.h:2226:16: note: in call to '&checker.context_->on_error(&"argument index out of range"[0])'
- context_.on_error("argument index out of range");
- ^
+ Default format: 42s 100ms
+ strftime-like format: 03:15:30
-Use {fmt} as a safe portable replacement for ``itoa``
-(`godbolt <https://godbolt.org/g/NXmpU4>`_):
+**Print a container** (`run <https://godbolt.org/z/MjsY7c>`_)
.. code:: c++
- fmt::memory_buffer buf;
- format_to(buf, "{}", 42); // replaces itoa(42, buffer, 10)
- format_to(buf, "{:x}", 42); // replaces itoa(42, buffer, 16)
- // access the string with to_string(buf) or buf.data()
+ #include <vector>
+ #include <fmt/ranges.h>
-Format objects of user-defined types via a simple `extension API
-<https://fmt.dev/latest/api.html#formatting-user-defined-types>`_:
+ int main() {
+ std::vector<int> v = {1, 2, 3};
+ fmt::print("{}\n", v);
+ }
-.. code:: c++
+Output::
- #include "fmt/format.h"
+ [1, 2, 3]
- struct date {
- int year, month, day;
- };
+**Check a format string at compile time**
- template <>
- struct fmt::formatter<date> {
- template <typename ParseContext>
- constexpr auto parse(ParseContext &ctx) { return ctx.begin(); }
+.. code:: c++
- template <typename FormatContext>
- auto format(const date &d, FormatContext &ctx) {
- return format_to(ctx.out(), "{}-{}-{}", d.year, d.month, d.day);
- }
- };
+ std::string s = fmt::format(FMT_STRING("{:d}"), "I am not a number");
- std::string s = fmt::format("The date is {}", date{2012, 12, 9});
- // s == "The date is 2012-12-9"
+This gives a compile-time error because ``d`` is an invalid format specifier for
+a string.
-Create your own functions similar to `format
-<https://fmt.dev/latest/api.html#format>`_ and
-`print <https://fmt.dev/latest/api.html#print>`_
-which take arbitrary arguments (`godbolt <https://godbolt.org/g/MHjHVf>`_):
+**Write a file from a single thread**
.. code:: c++
- // Prints formatted error message.
- void vreport_error(const char *format, fmt::format_args args) {
- fmt::print("Error: ");
- fmt::vprint(format, args);
+ #include <fmt/os.h>
+
+ int main() {
+ auto out = fmt::output_file("guide.txt");
+ out.print("Don't {}", "Panic");
}
- template <typename... Args>
- void report_error(const char *format, const Args & ... args) {
- vreport_error(format, fmt::make_format_args(args...));
+
+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", "世界");
}
- report_error("file not found: {}", path);
+Output on a modern terminal:
-Note that ``vreport_error`` is not parameterized on argument types which can
-improve compile times and reduce code size compared to a fully parameterized
-version.
+.. image:: https://user-images.githubusercontent.com/
+ 576385/88485597-d312f600-cf2b-11ea-9cbe-61f535a86e28.png
Benchmarks
----------
@@ -162,29 +191,30 @@ Speed tests
================= ============= ===========
Library Method Run Time, s
================= ============= ===========
-libc printf 1.01
-libc++ std::ostream 3.04
-{fmt} 1632f72 fmt::print 0.86
-tinyformat 2.0.1 tfm::printf 3.23
-Boost Format 1.67 boost::format 7.98
+libc printf 1.04
+libc++ std::ostream 3.05
+{fmt} 6.1.1 fmt::print 0.75
+Boost Format 1.67 boost::format 7.24
Folly Format folly::format 2.23
================= ============= ===========
-{fmt} is the fastest of the benchmarked methods, ~17% faster than ``printf``.
+{fmt} is the fastest of the benchmarked methods, ~35% faster than ``printf``.
The above results were generated by building ``tinyformat_test.cpp`` on macOS
-10.14.3 with ``clang++ -O3 -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"``
+10.14.6 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/tinyformat_test.cpp>`_.
-{fmt} is 10x faster than ``std::ostringstream`` and ``sprintf`` on floating-point
-formatting (`dtoa-benchmark <https://github.com/fmtlib/dtoa-benchmark>`_)
-and as fast as `double-conversion <https://github.com/google/double-conversion>`_:
+{fmt} is up to 20-30x faster than ``std::ostringstream`` and ``sprintf`` on
+floating-point 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/54883977-9fe8c000-4e28-11e9-8bde-272d122e7c52.jpg
- :target: https://fmt.dev/unknown_mac64_clang10.0.html
+.. 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -207,7 +237,6 @@ printf 2.6 29 26
printf+string 16.4 29 26
iostreams 31.1 59 55
{fmt} 19.0 37 34
-tinyformat 44.0 103 97
Boost Format 91.9 226 203
Folly Format 115.7 101 88
============= =============== ==================== ==================
@@ -228,14 +257,13 @@ printf 2.2 33 30
printf+string 16.0 33 30
iostreams 28.3 56 52
{fmt} 18.2 59 50
-tinyformat 32.6 88 82
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 and tinyformat are
-header-only libraries so they don't provide any linkage options.
+compare formatting function overhead only. Boost Format is a
+header-only library so it doesn't provide any linkage options.
Running the tests
~~~~~~~~~~~~~~~~~
@@ -261,38 +289,46 @@ Then you can run the speed test::
or the bloat test::
$ make bloat-test
+
+Migrating code
+--------------
+
+`clang-tidy-fmt <https://github.com/mikecrowe/clang-tidy-fmt>`_ provides clang
+tidy checks for converting occurrences of ``printf`` and ``fprintf`` to
+``fmt::print``.
Projects using this library
---------------------------
-* `0 A.D. <http://play0ad.com/>`_: A free, open-source, cross-platform real-time
- strategy game
+* `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
-
-* `AvioBook <https://www.aviobook.aero/en>`_: A comprehensive aircraft
- operations suite
-
-* `Celestia <https://celestia.space/>`_: Real-time 3D visualization of space
+* `2GIS <https://2gis.ru/>`_: free business listings with a city map
-* `Ceph <https://ceph.com/>`_: A scalable distributed storage system
+* `AMPL/MP <https://github.com/ampl/mp>`_:
+ an open-source library for mathematical programming
-* `CUAUV <http://cuauv.org/>`_: Cornell University's autonomous underwater
- vehicle
+* `Aseprite <https://github.com/aseprite/aseprite>`_:
+ animated sprite editor & pixel art tool
-* `HarpyWar/pvpgn <https://github.com/pvpgn/pvpgn-server>`_:
- Player vs Player Gaming Network with tweaks
+* `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
-* `KBEngine <http://kbengine.org/>`_: An open-source MMOG server engine
+* `Ceph <https://ceph.com/>`_: a scalable distributed storage system
-* `Keypirinha <http://keypirinha.com/>`_: A semantic launcher for Windows
+* `ccache <https://ccache.dev/>`_: a compiler cache
-* `Kodi <https://kodi.tv/>`_ (formerly xbmc): Home theater software
+* `ClickHouse <https://github.com/ClickHouse/ClickHouse>`_: analytical database
+ management system
-* `Lifeline <https://github.com/peter-clark/lifeline>`_: A 2D game
+* `CUAUV <https://cuauv.org/>`_: Cornell University's autonomous underwater
+ vehicle
-* `Drake <http://drake.mit.edu/>`_: A planning, control, and analysis toolbox
+* `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
@@ -300,50 +336,80 @@ Projects using this library
* `FiveM <https://fivem.net/>`_: a modification framework for GTA V
-* `MongoDB <https://mongodb.com/>`_: Distributed document database
+* `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
+
+* `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
-* `MongoDB Smasher <https://github.com/duckie/mongo_smasher>`_: A small tool to
+* `Kodi <https://kodi.tv/>`_ (formerly xbmc): home theater software
+
+* `Knuth <https://kth.cash/>`_: high-performance Bitcoin full-node
+
+* `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 <http://openspaceproject.com/>`_: An open-source astrovisualization
- framework
+* `OpenSpace <https://openspaceproject.com/>`_: an open-source
+ astrovisualization framework
-* `PenUltima Online (POL) <http://www.polserver.com/>`_:
- An MMO server, compatible with most Ultima Online clients
+* `PenUltima Online (POL) <https://www.polserver.com/>`_:
+ an MMO server, compatible with most Ultima Online clients
-* `quasardb <https://www.quasardb.net/>`_: A distributed, high-performance,
+* `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
-* `readpe <https://bitbucket.org/sys_dev/readpe>`_: Read Portable Executable
+* `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
+* `redis-cerberus <https://github.com/HunanTV/redis-cerberus>`_: a Redis cluster
proxy
-* `rpclib <http://rpclib.net/>`_: A modern C++ msgpack-RPC server and client
- library
+* `redpanda <https://vectorized.io/redpanda>`_: a 10x faster Kafka® replacement
+ for mission critical systems written in C++
-* `Saddy <https://github.com/mamontov-cpp/saddy-graphics-engine-2d>`_:
- Small crossplatform 2D graphic engine
+* `rpclib <http://rpclib.net/>`_: a modern C++ msgpack-RPC server and client
+ library
-* `Salesforce Analytics Cloud <http://www.salesforce.com/analytics-cloud/overview/>`_:
- Business intelligence software
+* `Salesforce Analytics Cloud
+ <https://www.salesforce.com/analytics-cloud/overview/>`_:
+ business intelligence software
-* `Scylla <http://www.scylladb.com/>`_: A Cassandra-compatible NoSQL data store
+* `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++
+* `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
+* `spdlog <https://github.com/gabime/spdlog>`_: super fast C++ logging library
-* `Stellar <https://www.stellar.org/>`_: Financial platform
+* `Stellar <https://www.stellar.org/>`_: financial platform
-* `Touch Surgery <https://www.touchsurgery.com/>`_: Surgery simulator
+* `Touch Surgery <https://www.touchsurgery.com/>`_: surgery simulator
-* `TrinityCore <https://github.com/TrinityCore/TrinityCore>`_: Open-source
+* `TrinityCore <https://github.com/TrinityCore/TrinityCore>`_: open-source
MMORPG framework
-`More... <https://github.com/search?q=cppformat&type=Code>`_
+* `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
@@ -367,7 +433,7 @@ 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, ...))
-<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ in GCC.
+<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
@@ -399,15 +465,15 @@ Boost Format
This is a very powerful library which 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
+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 which is fast, safe and has positional
-arguments. However it has significant limitations, citing its author:
+This is an interesting library which 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:
@@ -416,22 +482,8 @@ arguments. However it has significant limitations, citing its author:
* 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.
-
-Loki SafeFormat
-~~~~~~~~~~~~~~~
-
-SafeFormat is a formatting library which uses ``printf``-like format strings and
-is type safe. It doesn't support user-defined types or positional arguments and
-makes unconventional use of ``operator()`` for passing format arguments.
-
-Tinyformat
-~~~~~~~~~~
-
-This library supports ``printf``-like format strings and is very small .
-It doesn't support positional arguments and wrapping it in C++98 is somewhat
-difficult. Tinyformat relies on iostreams which limits its performance.
+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
~~~~~~~~~~~~~~~~~~
@@ -439,51 +491,29 @@ Boost Spirit.Karma
This is not really 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_int`` on Karma's own benchmark,
-see `Fast integer to string conversion in C++
-<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
-
-FAQ
----
-
-Q: how can I capture formatting arguments and format them later?
-
-A: use ``std::tuple``:
-
-.. code:: c++
-
- template <typename... Args>
- auto capture(const Args&... args) {
- return std::make_tuple(args...);
- }
-
- auto print_message = [](const auto&... args) {
- fmt::print(args...);
- };
-
- // Capture and store arguments:
- auto args = capture("{} {}", 42, "foo");
- // Do formatting:
- std::apply(print_message, args);
+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 BSD `license
+{fmt} is distributed under the MIT `license
<https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_.
-The `Format String Syntax
-<https://fmt.dev/latest/syntax.html>`_
+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>`_
-adapted for the current library. For this reason the documentation is
-distributed under the Python Software Foundation license available in
-`doc/python-license.txt
+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.
+It only applies if you distribute the documentation of {fmt}.
-Acknowledgments
----------------
+Maintainers
+-----------
The {fmt} library is maintained by Victor Zverovich (`vitaut
<https://github.com/vitaut>`_) and Jonathan Müller (`foonathan
@@ -492,23 +522,3 @@ 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.
-
-The benchmark section of this readme file and the performance tests are taken
-from the excellent `tinyformat <https://github.com/c42f/tinyformat>`_ library
-written by Chris Foster. Boost Format library is acknowledged transitively
-since it had some influence on tinyformat.
-Some ideas used in the implementation are borrowed from `Loki
-<http://loki-lib.sourceforge.net/>`_ SafeFormat and `Diagnostic API
-<http://clang.llvm.org/doxygen/classclang_1_1Diagnostic.html>`_ in
-`Clang <http://clang.llvm.org/>`_.
-Format string syntax and the documentation are based on Python's `str.format
-<http://docs.python.org/2/library/stdtypes.html#str.format>`_.
-Thanks `Doug Turnbull <https://github.com/softwaredoug>`_ for his valuable
-comments and contribution to the design of the type-safe API and
-`Gregory Czajkowski <https://github.com/gcflymoto>`_ for implementing binary
-formatting. Thanks `Ruslan Baratov <https://github.com/ruslo>`_ for comprehensive
-`comparison of integer formatting algorithms <https://github.com/ruslo/int-dec-format-tests>`_
-and useful comments regarding performance, `Boris Kaul <https://github.com/localvoid>`_ for
-`C++ counting digits benchmark <https://github.com/localvoid/cxx-benchmark-count-digits>`_.
-Thanks to `CarterLi <https://github.com/CarterLi>`_ for contributing various
-improvements to the code.