From e6473ab5d98f0f60556a0ab73e1f03fa288f06c9 Mon Sep 17 00:00:00 2001 From: DDuarte Date: Thu, 29 Dec 2016 22:38:46 +0000 Subject: Dep: Update fmt (cppformat) to 3.0.1 https://github.com/fmtlib/fmt/commit/7fa8f8fa48b0903deab5bb42e6760477173ac485 Also renamed cppformat to fmt --- dep/cppformat/README.rst | 411 ----------------------------------------------- 1 file changed, 411 deletions(-) delete mode 100644 dep/cppformat/README.rst (limited to 'dep/cppformat/README.rst') diff --git a/dep/cppformat/README.rst b/dep/cppformat/README.rst deleted file mode 100644 index e859f909466..00000000000 --- a/dep/cppformat/README.rst +++ /dev/null @@ -1,411 +0,0 @@ -C++ Format -========== - -.. image:: https://travis-ci.org/cppformat/cppformat.png?branch=master - :target: https://travis-ci.org/cppformat/cppformat - -.. image:: https://ci.appveyor.com/api/projects/status/qk0bhyhqp1ekpat8 - :target: https://ci.appveyor.com/project/vitaut/cppformat - -.. image:: https://badges.gitter.im/Join%20Chat.svg - :alt: Join the chat at https://gitter.im/cppformat/cppformat - :target: https://gitter.im/cppformat/cppformat?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge - -C++ Format is an open-source formatting library for C++. -It can be used as a safe alternative to printf or as a fast -alternative to IOStreams. - -`Documentation `_ - -Features --------- - -* Two APIs: faster concatenation-based write API and slower (but still - very fast) replacement-based format API with positional arguments for - localization. -* Write API similar to the one used by IOStreams but stateless allowing - faster implementation. -* Format API with `format string syntax - `_ - similar to the one used by `str.format - `_ in Python. -* Safe `printf implementation - `_ - including the POSIX extension for positional arguments. -* Support for user-defined types. -* High speed: performance of the format API is close to that of - glibc's `printf `_ - and better than performance of IOStreams. See `Speed tests`_ and - `Fast integer to string conversion in C++ - `_. -* Small code size both in terms of source code (format consists of a single - header file and a single source file) 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 are - reported using exceptions, 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 --------- - -This prints ``Hello, world!`` to stdout: - -.. code:: c++ - - fmt::print("Hello, {}!", "world"); // uses Python-like format string syntax - fmt::printf("Hello, %s!", "world"); // uses printf format string syntax - -Arguments can be accessed by position and arguments' indices can be repeated: - -.. code:: c++ - - std::string s = fmt::format("{0}{1}{0}", "abra", "cad"); - // s == "abracadabra" - -C++ Format can be used as a safe portable replacement for ``itoa``: - -.. code:: c++ - - fmt::MemoryWriter w; - w << 42; // replaces itoa(42, buffer, 10) - w << fmt::hex(42); // replaces itoa(42, buffer, 16) - // access the string using w.str() or w.c_str() - -An object of any user-defined type for which there is an overloaded -:code:`std::ostream` insertion operator (``operator<<``) can be formatted: - -.. code:: c++ - - class Date { - int year_, month_, day_; - public: - Date(int year, int month, int day) : year_(year), month_(month), day_(day) {} - - friend std::ostream &operator<<(std::ostream &os, const Date &d) { - return os << 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" - -You can use the `FMT_VARIADIC -`_ -macro to create your own functions similar to `format -`_ and -`print `_ -which take arbitrary arguments: - -.. code:: c++ - - // Prints formatted error message. - void report_error(const char *format, fmt::ArgList args) { - fmt::print("Error: "); - fmt::print(format, args); - } - FMT_VARIADIC(void, report_error, const char *) - - report_error("file not found: {}", path); - -Note that you only need to define one function that takes ``fmt::ArgList`` -argument. ``FMT_VARIADIC`` automatically defines necessary wrappers that -accept variable number of arguments. - -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 - -* `HarpyWar/pvpgn `_: - Player vs Player Gaming Network with tweaks - -* `KBEngine `_: An open-source MMOG server engine - -* `Keypirinha `_: A semantic launcher for Windows - -* `Lifeline `_: A 2D game - -* `MongoDB Smasher `_: A small tool to generate randomized datasets - -* `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 - -* `Saddy `_: - Small crossplatform 2D graphic engine - -* `Salesforce Analytics Cloud `_: - Business intelligence software - -* `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 library and -FastFormat. 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 mostly solved 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, referred to this situation with -IOStreams as "chevron hell". IOStreams doesn't support positional arguments -by design. - -The good part is that IOStreams supports user-defined types and is safe -although error reporting is awkward. - -Boost Format library -~~~~~~~~~~~~~~~~~~~~ - -This is a very powerful library which supports both printf-like format -strings and positional arguments. The main its 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. It makes unconventional use of ``operator()`` for passing -format arguments. - -Tinyformat -~~~~~~~~~~ - -This library supports printf-like format strings and is very small and -fast. Unfortunately it doesn't support positional arguments and wrapping -it in C++98 is somewhat difficult. Also its performance and code compactness -are limited by IOStreams. - -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::Writer`` on Karma's own benchmark, -see `Fast integer to string conversion in C++ -`_. - -Benchmarks ----------- - -Speed tests -~~~~~~~~~~~ - -The following speed tests results were generated by building -``tinyformat_test.cpp`` on Ubuntu GNU/Linux 14.04.1 with -``g++-4.8.2 -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 2000000 times with output sent to ``/dev/null``; for -further details see the `source -`_. - -================= ============= =========== -Library Method Run Time, s -================= ============= =========== -EGLIBC 2.19 printf 1.30 -libstdc++ 4.8.2 std::ostream 1.85 -C++ Format 1.0 fmt::print 1.42 -tinyformat 2.0.1 tfm::printf 2.25 -Boost Format 1.54 boost::format 9.94 -================= ============= =========== - -As you can see ``boost::format`` is much slower than the alternative methods; this -is confirmed by `other tests `_. -Tinyformat is quite good coming close to IOStreams. Unfortunately tinyformat -cannot be faster than the IOStreams because it uses them internally. -Performance of cppformat is close to that of printf, being `faster than printf on integer -formatting `_, -but slower on floating-point formatting which dominates this benchmark. - -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 (g++-4.8.1, Ubuntu GNU/Linux 13.10, -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 41 30 -IOStreams 19.4 92 70 -C++ Format 46.8 46 34 -tinyformat 64.6 418 386 -Boost Format 222.8 990 923 -============ =============== ==================== ================== - -As you can see, C++ Format has two times less overhead in terms of resulting -code size compared to IOStreams and comes pretty close to ``printf``. -Boost Format has by far the largest overheads. - -**Non-optimized build** - -============ =============== ==================== ================== -Method Compile Time, s Executable size, KiB Stripped size, KiB -============ =============== ==================== ================== -printf 2.1 41 30 -IOStreams 19.7 86 62 -C++ Format 47.9 108 86 -tinyformat 27.7 234 190 -Boost Format 122.6 884 763 -============ =============== ==================== ================== - -``libc``, ``libstdc++`` and ``libformat`` 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. - -__ http://cppformat.github.io/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/cppformat/format-benchmark.git - $ cd format-benchmark - $ cmake . - -Then you can run the speed test:: - - $ make speed-test - -or the bloat test:: - - $ make bloat-test - -License -------- - -C++ Format 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 C++ Format. - -Acknowledgments ---------------- - -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