aboutsummaryrefslogtreecommitdiff
path: root/dep/cppformat/README.rst
diff options
context:
space:
mode:
authorDDuarte <dnpd.dd@gmail.com>2016-12-29 22:38:46 +0000
committerDDuarte <dnpd.dd@gmail.com>2016-12-29 23:45:59 +0000
commite6473ab5d98f0f60556a0ab73e1f03fa288f06c9 (patch)
treecad6deab58966e3d8925375d211e007da44cc18c /dep/cppformat/README.rst
parentec806fa9add886114fb28d12e7653a5b19df120d (diff)
Dep: Update fmt (cppformat) to 3.0.1 https://github.com/fmtlib/fmt/commit/7fa8f8fa48b0903deab5bb42e6760477173ac485
Also renamed cppformat to fmt
Diffstat (limited to 'dep/cppformat/README.rst')
-rw-r--r--dep/cppformat/README.rst411
1 files changed, 0 insertions, 411 deletions
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 <http://cppformat.github.io/latest/>`_
-
-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
- <http://cppformat.github.io/latest/syntax.html>`_
- similar to the one used by `str.format
- <https://docs.python.org/2/library/stdtypes.html#str.format>`_ in Python.
-* Safe `printf implementation
- <http://cppformat.github.io/latest/api.html#printf-formatting-functions>`_
- 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 <http://en.cppreference.com/w/cpp/io/c/fprintf>`_
- and better than performance of 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 (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
- <https://github.com/cppformat/cppformat/tree/master/test>`_.
-* 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
- <https://github.com/cppformat/cppformat/blob/master/LICENSE.rst>`_
-* `Portability <http://cppformat.github.io#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 <http://cppformat.github.io/latest/>`_ 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
-<http://cppformat.github.io/latest/api.html#utilities>`_
-macro to create your own functions similar to `format
-<http://cppformat.github.io/latest/api.html#format>`_ and
-`print <http://cppformat.github.io/latest/api.html#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. <http://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
-
-* `HarpyWar/pvpgn <https://github.com/pvpgn/pvpgn-server>`_:
- Player vs Player Gaming Network with tweaks
-
-* `KBEngine <http://kbengine.org/>`_: An open-source MMOG server engine
-
-* `Keypirinha <http://keypirinha.com/>`_: A semantic launcher for Windows
-
-* `Lifeline <https://github.com/peter-clark/lifeline>`_: A 2D game
-
-* `MongoDB Smasher <https://github.com/duckie/mongo_smasher>`_: A small tool to generate randomized datasets
-
-* `PenUltima Online (POL) <http://www.polserver.com/>`_:
- An MMO server, compatible with most Ultima Online clients
-
-* `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
-
-* `Saddy <https://github.com/mamontov-cpp/saddy-graphics-engine-2d>`_:
- Small crossplatform 2D graphic engine
-
-* `Salesforce Analytics Cloud <http://www.salesforce.com/analytics-cloud/overview/>`_:
- Business intelligence software
-
-* `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
-
-`More... <https://github.com/search?q=cppformat&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/cppformat/cppformat/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 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, ...))
-<http://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, 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++
-<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
-
-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
-<https://github.com/cppformat/format-benchmark/blob/master/tinyformat_test.cpp>`_.
-
-================= ============= ===========
-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 <http://accu.org/index.php/journals/1539>`_.
-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 <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_,
-but slower on floating-point formatting which dominates this benchmark.
-
-Compile time and code bloat
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The script `bloat-test.py
-<https://github.com/cppformat/format-benchmark/blob/master/bloat-test.py>`_
-from `format-benchmark <https://github.com/cppformat/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 <https://github.com/cppformat/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/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
-<https://github.com/cppformat/cppformat/blob/master/LICENSE.rst>`_.
-
-The `Format String Syntax
-<http://cppformat.github.io/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
-<https://raw.github.com/cppformat/cppformat/master/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 <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.