diff options
Diffstat (limited to 'third-party/fmt/README.rst')
| -rw-r--r-- | third-party/fmt/README.rst | 469 |
1 files changed, 469 insertions, 0 deletions
diff --git a/third-party/fmt/README.rst b/third-party/fmt/README.rst new file mode 100644 index 0000000000..4b943e4996 --- /dev/null +++ b/third-party/fmt/README.rst @@ -0,0 +1,469 @@ +{fmt} +===== + +.. image:: https://travis-ci.org/fmtlib/fmt.png?branch=master + :target: https://travis-ci.org/fmtlib/fmt + +.. 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/libfmt.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%3Dlibfmt&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 + +**{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>`__ + +Q&A: ask questions on `StackOverflow with the tag fmt +<https://stackoverflow.com/questions/tagged/fmt>`_. + +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>`_ +* 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 `unit tests + <https://github.com/fmtlib/fmt/tree/master/test>`_ and is continuously fuzzed +* 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 ``Hello, world!`` to ``stdout``: + +.. code:: c++ + + #include <fmt/core.h> + + int main() { + fmt::print("Hello, world!\n"); + } + +Format a string: + +.. code:: c++ + + std::string s = fmt::format("The answer is {}.", 42); + // s == "The answer is 42." + +Format a string using positional arguments: + +.. 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: + +.. 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: + +.. 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(FMT_STRING("{:d}"), "don't panic"); + +This gives a compile-time error 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 is up to 6x faster than glibc's ``fprintf``. + +Benchmarks +---------- + +Speed tests +~~~~~~~~~~~ + +================= ============= =========== +Library Method Run Time, s +================= ============= =========== +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, ~35% faster than ``printf``. + +The above results were generated by building ``tinyformat_test.cpp`` on macOS +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 up to 10x 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>`_: + +.. image:: https://user-images.githubusercontent.com/576385/ + 69767160-cdaca400-112f-11ea-9fc5-347c9f83caad.png + :target: https://fmt.dev/unknown_mac64_clang10.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 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 the 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 + +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 + +* `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>`_: analytical database + management system + +* `CUAUV <http://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 + +* `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 + +* `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 <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 + +* `readpe <https://bitbucket.org/sys_dev/readpe>`_: Read Portable Executable + +* `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 + +* `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 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 +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: + + 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 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_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>`_) and Jonathan Müller (`foonathan +<https://github.com/foonathan>`_) 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. |