diff options
author | Kargatum <dowlandtop@yandex.com> | 2021-05-20 22:24:08 +0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-05-20 17:24:08 +0200 |
commit | d86a7b96c3cdb4b20012d01cde31941959436533 (patch) | |
tree | cb586eda6ef174253d39d5a689a5523a9b02c2b1 /deps/fmt/README.rst | |
parent | 7f3734375e173d5e7e5c38113878be8bfb9f678d (diff) |
feat(Deps/FmtLib): update fmtlib to 7.1.3 (#5950)
Diffstat (limited to 'deps/fmt/README.rst')
-rw-r--r-- | deps/fmt/README.rst | 462 |
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. |