From 859eaed800c4f6d4b1d4d10f55bfe70828ba8fee Mon Sep 17 00:00:00 2001 From: Kargatum Date: Tue, 13 Aug 2019 15:52:03 +0700 Subject: feat(Core/Deps): Added fmt lib (#2190) * About library (https://github.com/fmtlib/fmt) --- deps/fmt/README.rst | 514 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 514 insertions(+) create mode 100644 deps/fmt/README.rst (limited to 'deps/fmt/README.rst') diff --git a/deps/fmt/README.rst b/deps/fmt/README.rst new file mode 100644 index 0000000000..f08b22faef --- /dev/null +++ b/deps/fmt/README.rst @@ -0,0 +1,514 @@ +{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://img.shields.io/badge/stackoverflow-fmt-blue.svg + :alt: Ask questions at StackOverflow with the tag fmt + :target: http://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 `__ + +Q&A: ask questions on `StackOverflow with the tag fmt `_. + +Features +-------- + +* Replacement-based `format API `_ with + positional arguments for localization. +* `Format string syntax `_ similar to the one + of `str.format `_ + in Python. +* Safe `printf implementation + `_ including + the POSIX extension for positional arguments. +* Implementation of `C++20 std::format `__. +* Support for user-defined types. +* High performance: faster than common standard library implementations of + `printf `_ and + iostreams. See `Speed tests`_ and `Fast integer to string conversion in C++ + `_. +* 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 + `_. +* 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 BSD `license + `_ +* `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. + +See the `documentation `_ for more details. + +Examples +-------- + +Print ``Hello, world!`` to ``stdout``: + +.. code:: c++ + + fmt::print("Hello, {}!", "world"); // Python-like format string syntax + fmt::printf("Hello, %s!", "world"); // printf format string syntax + +Format a string and use 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." + +Check a format string at compile time: + +.. code:: c++ + + // test.cc + #define FMT_STRING_ALIAS 1 + #include + std::string s = format(fmt("{2}"), 42); + +.. code:: + + $ c++ -Iinclude -std=c++14 test.cc + ... + test.cc:4:17: note: in instantiation of function template specialization 'fmt::v5::format' 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"); + ^ + +Use {fmt} as a safe portable replacement for ``itoa`` +(`godbolt `_): + +.. 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() + +Format objects of user-defined types via a simple `extension API +`_: + +.. code:: c++ + + #include "fmt/format.h" + + struct date { + int year, month, day; + }; + + template <> + struct fmt::formatter { + template + constexpr auto parse(ParseContext &ctx) { return ctx.begin(); } + + template + auto format(const date &d, FormatContext &ctx) { + return format_to(ctx.out(), "{}-{}-{}", d.year, d.month, d.day); + } + }; + + std::string s = fmt::format("The date is {}", date{2012, 12, 9}); + // s == "The date is 2012-12-9" + +Create your own functions similar to `format +`_ and +`print `_ +which take arbitrary arguments (`godbolt `_): + +.. code:: c++ + + // Prints formatted error message. + void vreport_error(const char *format, fmt::format_args args) { + fmt::print("Error: "); + fmt::vprint(format, args); + } + template + void report_error(const char *format, const Args & ... args) { + vreport_error(format, fmt::make_format_args(args...)); + } + + report_error("file not found: {}", path); + +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. + +Benchmarks +---------- + +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 +Folly Format folly::format 2.23 +================= ============= =========== + +{fmt} is the fastest of the benchmarked methods, ~17% 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"`` +or equivalent is filled 2,000,000 times with output sent to ``/dev/null``; for +further details refer to the `source +`_. + +{fmt} is 10x faster than ``std::ostringstream`` and ``sprintf`` on floating-point +formatting (`dtoa-benchmark `_) +and as fast as `double-conversion `_: + +.. image:: https://user-images.githubusercontent.com/576385/54883977-9fe8c000-4e28-11e9-8bde-272d122e7c52.jpg + :target: https://fmt.dev/unknown_mac64_clang10.0.html + +Compile time and code bloat +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The script `bloat-test.py +`_ +from `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 +tinyformat 44.0 103 97 +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 ```` +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 +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. + +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 `_, +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. `_: A free, open-source, cross-platform real-time + strategy game + +* `AMPL/MP `_: + An open-source library for mathematical programming + +* `AvioBook `_: A comprehensive aircraft + operations suite + +* `Celestia `_: Real-time 3D visualization of space + +* `Ceph `_: A scalable distributed storage system + +* `CUAUV `_: Cornell University's autonomous underwater + vehicle + +* `HarpyWar/pvpgn `_: + Player vs Player Gaming Network with tweaks + +* `KBEngine `_: An open-source MMOG server engine + +* `Keypirinha `_: A semantic launcher for Windows + +* `Kodi `_ (formerly xbmc): Home theater software + +* `Lifeline `_: A 2D game + +* `Drake `_: A planning, control, and analysis toolbox + for nonlinear dynamical systems (MIT) + +* `Envoy `_: C++ L7 proxy and communication bus + (Lyft) + +* `FiveM `_: a modification framework for GTA V + +* `MongoDB `_: Distributed document database + +* `MongoDB Smasher `_: A small tool to + generate randomized datasets + +* `OpenSpace `_: An open-source astrovisualization + framework + +* `PenUltima Online (POL) `_: + An MMO server, compatible with most Ultima Online clients + +* `quasardb `_: A distributed, high-performance, + associative database + +* `readpe `_: Read Portable Executable + +* `redis-cerberus `_: A Redis cluster + proxy + +* `rpclib `_: A modern C++ msgpack-RPC server and client + library + +* `Saddy `_: + Small crossplatform 2D graphic engine + +* `Salesforce Analytics Cloud `_: + Business intelligence software + +* `Scylla `_: A Cassandra-compatible NoSQL data store + that can handle 1 million transactions per second on a single server + +* `Seastar `_: An advanced, open-source C++ + framework for high-performance server applications on modern hardware + +* `spdlog `_: Super fast C++ logging library + +* `Stellar `_: Financial platform + +* `Touch Surgery `_: Surgery simulator + +* `TrinityCore `_: Open-source + MMORPG framework + +`More... `_ + +If you are aware of other projects using this library, please let me know +by `email `_ or by submitting an +`issue `_. + +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, ...)) +`_ in GCC. +There is a POSIX extension that adds positional arguments required for +`i18n `_ +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. + +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. + +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++ +`_. + +FAQ +--- + +Q: how can I capture formatting arguments and format them later? + +A: use ``std::tuple``: + +.. code:: c++ + + template + 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); + +License +------- + +{fmt} is distributed under the BSD `license +`_. + +The `Format String Syntax +`_ +section in the documentation is based on the one from Python `string module +documentation `_ +adapted for the current library. For this reason the documentation is +distributed under the Python Software Foundation license available in +`doc/python-license.txt +`_. +It only applies if you distribute the documentation of fmt. + +Acknowledgments +--------------- + +The {fmt} library is maintained by Victor Zverovich (`vitaut +`_) and Jonathan Müller (`foonathan +`_) with contributions from many other people. +See `Contributors `_ and +`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 `_ 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 +`_ SafeFormat and `Diagnostic API +`_ in +`Clang `_. +Format string syntax and the documentation are based on Python's `str.format +`_. +Thanks `Doug Turnbull `_ for his valuable +comments and contribution to the design of the type-safe API and +`Gregory Czajkowski `_ for implementing binary +formatting. Thanks `Ruslan Baratov `_ for comprehensive +`comparison of integer formatting algorithms `_ +and useful comments regarding performance, `Boris Kaul `_ for +`C++ counting digits benchmark `_. +Thanks to `CarterLi `_ for contributing various +improvements to the code. -- cgit v1.2.3