diff options
Diffstat (limited to 'dep/fmt/README.rst')
| -rw-r--r-- | dep/fmt/README.rst | 242 |
1 files changed, 127 insertions, 115 deletions
diff --git a/dep/fmt/README.rst b/dep/fmt/README.rst index 722a65eb10f..acddc70ef18 100644 --- a/dep/fmt/README.rst +++ b/dep/fmt/README.rst @@ -7,48 +7,57 @@ .. 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 att oss-fuzz +.. 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%3Dlibfmt&can=1 + Summary&q=proj%3Dfmt&can=1 .. image:: https://img.shields.io/badge/stackoverflow-fmt-blue.svg :alt: Ask questions at StackOverflow with the tag fmt :target: https://stackoverflow.com/questions/tagged/fmt -**{fmt}** is an open-source formatting library for C++. -It can be used as a safe and fast alternative to (s)printf and iostreams. +**{fmt}** is an open-source formatting library providing a fast and safe +alternative to C stdio and C++ iostreams. -`Documentation <https://fmt.dev/latest/>`__ +If you like this project, please consider donating to BYSOL, +an initiative to help victims of political repressions in Belarus: +https://www.facebook.com/donate/759400044849707/108388587646909/. + +`Documentation <https://fmt.dev>`__ Q&A: ask questions on `StackOverflow with the tag fmt <https://stackoverflow.com/questions/tagged/fmt>`_. +Try {fmt} in `Compiler Explorer <https://godbolt.org/z/Eq5763>`_. + Features -------- -* Simple `format API <https://fmt.dev/dev/api.html>`_ with positional arguments +* 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/dev/syntax.html>`_ similar to the one - of Python's +* `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 -* Extensibility: 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 <https://en.cppreference.com/w/cpp/io/c/fprintf>`_, - iostreams, ``to_string`` and ``to_chars``, see `Speed tests`_ and - `Converting a hundred million integers to strings per second + ``(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 (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>`_ and is continuously fuzzed +* 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 @@ -57,18 +66,17 @@ Features <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``) +* Clean warning-free codebase even on high warning levels such as + ``-Wall -Wextra -pedantic`` * Locale-independence by default -* Support for wide strings * 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++ @@ -78,100 +86,95 @@ Print ``Hello, world!`` to ``stdout``: fmt::print("Hello, world!\n"); } -Format a string: +**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: +**Format a string using positional arguments** (`run <https://godbolt.org/z/Yn7Txe>`_) .. code:: c++ std::string s = fmt::format("I'd rather be {1} than {0}.", "right", "happy"); // s == "I'd rather be happy than right." -Print a chrono duration: +**Print chrono durations** (`run <https://godbolt.org/z/K8s4Mc>`_) .. code:: c++ #include <fmt/chrono.h> int main() { - using namespace std::chrono_literals; - fmt::print("Elapsed time: {}", 42ms); + 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); } -prints "Elapsed time: 42ms". +Output:: -Check a format string at compile time: + Default format: 42s 100ms + strftime-like format: 03:15:30 -.. code:: c++ +**Print a container** (`run <https://godbolt.org/z/MjsY7c>`_) - // test.cc - #include <fmt/format.h> - std::string s = format(FMT_STRING("{:d}"), "hello"); +.. code:: c++ -gives a compile-time error because ``d`` is an invalid format specifier for a -string. + #include <vector> + #include <fmt/ranges.h> -Use {fmt} as a safe portable replacement for ``itoa`` -(`godbolt <https://godbolt.org/g/NXmpU4>`_): + int main() { + std::vector<int> v = {1, 2, 3}; + fmt::print("{}\n", v); + } -.. code:: c++ +Output:: - 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() + {1, 2, 3} -Format objects of user-defined types via a simple `extension API -<https://fmt.dev/latest/api.html#formatting-user-defined-types>`_: +**Check a format string at compile time** .. code:: c++ - #include <fmt/format.h> + std::string s = fmt::format(FMT_STRING("{:d}"), "don't panic"); - struct date { - int year, month, day; - }; +This gives a compile-time error because ``d`` is an invalid format specifier for +a string. - template <> - struct fmt::formatter<date> { - constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); } +**Write a file from a single thread** - template <typename FormatContext> - auto format(const date& d, FormatContext& ctx) { - return format_to(ctx.out(), "{}-{}-{}", d.year, d.month, d.day); - } - }; +.. code:: c++ - std::string s = fmt::format("The date is {}", date{2012, 12, 9}); - // s == "The date is 2012-12-9" + #include <fmt/os.h> -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>`_): + int main() { + auto out = fmt::output_file("guide.txt"); + out.print("Don't {}", "Panic"); + } + +This can be `5 to 9 times faster than fprintf +<http://www.zverovich.net/2020/08/04/optimal-file-buffer-size.html>`_. + +**Print with colors and text styles** .. code:: c++ - // Prints formatted error message. - void vreport_error(const char* format, fmt::format_args args) { - fmt::print("Error: "); - fmt::vprint(format, args); - } - template <typename... Args> - void report_error(const char* format, const Args & ... args) { - vreport_error(format, fmt::make_format_args(args...)); + #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 ---------- @@ -198,12 +201,14 @@ 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 +{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 faster than `double-conversion <https://github.com/google/double-conversion>`_ and +`ryu <https://github.com/ulfjack/ryu>`_: -.. image:: https://user-images.githubusercontent.com/576385/69767160-cdaca400-112f-11ea-9fc5-347c9f83caad.png - :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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -282,30 +287,33 @@ or the bloat test:: Projects using this library --------------------------- -* `0 A.D. <https://play0ad.com/>`_: A free, open-source, cross-platform +* `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 + an open-source library for mathematical programming * `Aseprite <https://github.com/aseprite/aseprite>`_: - Animated sprite editor & pixel art tool + animated sprite editor & pixel art tool -* `AvioBook <https://www.aviobook.aero/en>`_: A comprehensive aircraft +* `AvioBook <https://www.aviobook.aero/en>`_: a comprehensive aircraft operations suite -* `Celestia <https://celestia.space/>`_: Real-time 3D visualization of space +* `Blizzard Battle.net <https://battle.net/>`_: an online gaming platform + +* `Celestia <https://celestia.space/>`_: real-time 3D visualization of space -* `Ceph <https://ceph.com/>`_: A scalable distributed storage system +* `Ceph <https://ceph.com/>`_: a scalable distributed storage system -* `ccache <https://ccache.dev/>`_: A compiler cache +* `ccache <https://ccache.dev/>`_: a compiler cache -* `ClickHouse <https://github.com/ClickHouse/ClickHouse>`_: analytical database management system +* `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 +* `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 @@ -318,66 +326,70 @@ Projects using this library * `HarpyWar/pvpgn <https://github.com/pvpgn/pvpgn-server>`_: Player vs Player Gaming Network with tweaks -* `KBEngine <https://kbengine.org/>`_: An open-source MMOG server engine +* `KBEngine <https://github.com/kbengine/kbengine>`_: an open-source MMOG server + engine -* `Keypirinha <https://keypirinha.com/>`_: A semantic launcher for Windows +* `Keypirinha <https://keypirinha.com/>`_: a semantic launcher for Windows -* `Kodi <https://kodi.tv/>`_ (formerly xbmc): Home theater software +* `Kodi <https://kodi.tv/>`_ (formerly xbmc): home theater software -* `Knuth <https://kth.cash/>`_: High-performance Bitcoin full-node +* `Knuth <https://kth.cash/>`_: high-performance Bitcoin full-node * `Microsoft Verona <https://github.com/microsoft/verona>`_: - Research programming language for concurrent ownership + research programming language for concurrent ownership -* `MongoDB <https://mongodb.com/>`_: Distributed document database +* `MongoDB <https://mongodb.com/>`_: distributed document database -* `MongoDB Smasher <https://github.com/duckie/mongo_smasher>`_: A small tool to +* `MongoDB Smasher <https://github.com/duckie/mongo_smasher>`_: a small tool to generate randomized datasets -* `OpenSpace <https://openspaceproject.com/>`_: An open-source +* `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 + an MMO server, compatible with most Ultima Online clients -* `PyTorch <https://github.com/pytorch/pytorch>`_: An open-source machine +* `PyTorch <https://github.com/pytorch/pytorch>`_: an open-source machine learning library -* `quasardb <https://www.quasardb.net/>`_: A distributed, high-performance, +* `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 -* `redpanda <https://vectorized.io/redpanda>`_: A 10x faster Kafka® replacement +* `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 +* `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 + business intelligence software -* `Scylla <https://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 -* `Windows Terminal <https://github.com/microsoft/terminal>`_: The new Windows - Terminal +* `Windows Terminal <https://github.com/microsoft/terminal>`_: the new Windows + terminal `More... <https://github.com/search?q=fmtlib&type=Code>`_ @@ -435,7 +447,7 @@ 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`_). |