mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2024-12-24 21:16:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

Simplify markup

Browse Source
This commit is contained in:
Victor Zverovich 2014-11-05 07:36:55 -08:00
parent 10698cc44d
commit 9cbb25e43f
1 changed files with 34 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
README.rst
View File

@ -24,12 +24,12 @@ Features
* Write API similar to the one used by IOStreams but much faster and more * Write API similar to the one used by IOStreams but much faster and more
consistent. consistent.
* Format API with `format string syntax * Format API with `format string syntax
<http://cppformat.readthedocs.org/en/latest/#format-string-syntax>`__ <http://cppformat.readthedocs.org/en/latest/#format-string-syntax>`_
similar to the one used by `str.format similar to the one used by `str.format
<http://docs.python.org/2/library/stdtypes.html#str.format>`__ in Python. <http://docs.python.org/2/library/stdtypes.html#str.format>`_ in Python.
* Support for user-defined types. * Support for user-defined types.
* High speed: performance of the format API is close to that of * High speed: performance of the format API is close to that of
glibc's `printf <http://en.cppreference.com/w/cpp/io/c/fprintf>`__ glibc's `printf <http://en.cppreference.com/w/cpp/io/c/fprintf>`_
and better than performance of IOStreams. See `Speed tests`_ and and better than performance of IOStreams. See `Speed tests`_ and
`Fast integer to string conversion in C++ `Fast integer to string conversion in C++
<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_. <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
@ -37,19 +37,19 @@ Features
header file and a single source file) and compiled code. header file and a single source file) and compiled code.
See `Compile time and code bloat`_. See `Compile time and code bloat`_.
* Reliability: the library has an extensive set of `unit tests * Reliability: the library has an extensive set of `unit tests
<https://github.com/cppformat/cppformat/tree/master/test>`__. <https://github.com/cppformat/cppformat/tree/master/test>`_.
* Safety: the library is fully type safe, errors in format strings are * Safety: the library is fully type safe, errors in format strings are
reported using exceptions, automatic memory management prevents buffer reported using exceptions, automatic memory management prevents buffer
overflow errors. overflow errors.
* Ease of use: small self-contained code base, no external dependencies, * Ease of use: small self-contained code base, no external dependencies,
permissive BSD `license`_. permissive BSD `license`_.
* `Portability <http://cppformat.github.io#portability>`__ with consistent output * `Portability <http://cppformat.github.io#portability>`_ with consistent output
across platforms and support for older compilers. across platforms and support for older compilers.
* Clean warning-free codebase even on high warning levels * Clean warning-free codebase even on high warning levels
(-Wall -Wextra -pedantic). (-Wall -Wextra -pedantic).
* Support for wide strings. * Support for wide strings.
See the `documentation <http://cppformat.readthedocs.org/en/latest/>`__ for more details. See the `documentation <http://cppformat.readthedocs.org/en/latest/>`_ for more details.
Examples Examples
-------- --------
@ -96,10 +96,10 @@ An object of any user-defined type for which there is an overloaded
// s == "The date is 2012-12-9" // s == "The date is 2012-12-9"
You can use the `FMT_VARIADIC You can use the `FMT_VARIADIC
<http://cppformat.readthedocs.org/en/latest/#project0format_8h_1a65215c7dfcc0e942cd0798860877e86b>`__ <http://cppformat.readthedocs.org/en/latest/#project0format_8h_1a65215c7dfcc0e942cd0798860877e86b>`_
macro to create your own functions similar to `format macro to create your own functions similar to `format
<http://cppformat.github.io/doc/latest#fmt::format__StringRef.ArgListCR>`__ and <http://cppformat.github.io/doc/latest#fmt::format__StringRef.ArgListCR>`_ and
`print <http://cppformat.readthedocs.org/en/latest#fmt::print__StringRef.ArgListCR>`__ `print <http://cppformat.readthedocs.org/en/latest#fmt::print__StringRef.ArgListCR>`_
which take arbitrary arguments: which take arbitrary arguments:
.. code-block:: c++ .. code-block:: c++
@ -154,10 +154,10 @@ Printf
The good thing about printf is that it is very fast and readily available The good thing about printf is that it is very fast and readily available
being a part of the C standard library. The main drawback is that it 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 doesn't support user-defined types. Printf also has safety issues although
they are mostly solved with `__attribute__ ((format (printf, ...)) they are mostly solved with `_attribute__ ((format (printf, ...))
<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`__ in GCC. <http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ in GCC.
There is a POSIX extension that adds positional arguments required for There is a POSIX extension that adds positional arguments required for
`i18n <http://en.wikipedia.org/wiki/Internationalization_and_localization>`__ `i18n <http://en.wikipedia.org/wiki/Internationalization_and_localization>`_
to printf but it is not a part of C99 and may not be available on some to printf but it is not a part of C99 and may not be available on some
platforms. platforms.
@ -233,7 +233,7 @@ for completeness. As IOStreams it suffers from the problem of mixing
verbatim text with arguments. The library is pretty fast, but slower verbatim text with arguments. The library is pretty fast, but slower
on integer formatting than ``fmt::Writer`` on Karma's own benchmark, on integer formatting than ``fmt::Writer`` on Karma's own benchmark,
see `Fast integer to string conversion in C++ see `Fast integer to string conversion in C++
<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`__. <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
Benchmarks Benchmarks
---------- ----------
@ -247,7 +247,7 @@ The following speed tests results were generated by building
runs. In the test, the format string ``"%0.10f:%04d:%+g:%s:%p:%c:%%\n"`` or 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 equivalent is filled 2000000 times with output sent to ``/dev/null``; for
further details see the `source further details see the `source
<https://github.com/cppformat/format-benchmark/blob/master/tinyformat_test.cpp>`__. <https://github.com/cppformat/format-benchmark/blob/master/tinyformat_test.cpp>`_.
============== ======== ============== ========
test name run time test name run time
@ -260,7 +260,7 @@ boost::format 10.42s
============== ======== ============== ========
As you can see boost::format is much slower than the alternative methods; this 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>`__. is confirmed by `other tests <http://accu.org/index.php/journals/1539>`_.
Tinyformat is quite good coming close to IOStreams. Unfortunately tinyformat Tinyformat is quite good coming close to IOStreams. Unfortunately tinyformat
cannot be faster than the IOStreams because it uses them internally. cannot be faster than the IOStreams because it uses them internally.
Performance of format is close to that of printf. Performance of format is close to that of printf.
@ -269,8 +269,8 @@ Compile time and code bloat
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
The script `bloat-test.py The script `bloat-test.py
<https://github.com/cppformat/format-benchmark/blob/master/bloat-test.py>`__ <https://github.com/cppformat/format-benchmark/blob/master/bloat-test.py>`_
from `format-benchmark <https://github.com/cppformat/format-benchmark>`__ from `format-benchmark <https://github.com/cppformat/format-benchmark>`_
tests compile time and code bloat for nontrivial projects. tests compile time and code bloat for nontrivial projects.
It generates 100 translation units and uses ``printf()`` or its alternative It generates 100 translation units and uses ``printf()`` or its alternative
five times in each to simulate a medium sized project. The resulting five times in each to simulate a medium sized project. The resulting
@ -318,10 +318,10 @@ To run the unit tests first get the source code by cloning the repository::
$ git clone https://github.com/cppformat/cppformat.git $ git clone https://github.com/cppformat/cppformat.git
or downloading a package from or downloading a package from
`Releases <https://github.com/cppformat/cppformat/releases>`__. `Releases <https://github.com/cppformat/cppformat/releases>`_.
Then go to the cppformat directory, generate Makefiles with Then go to the cppformat directory, generate Makefiles with
`CMake <http://www.cmake.org/>`__ and build the project:: `CMake <http://www.cmake.org/>`_ and build the project::
$ cd cppformat $ cd cppformat
$ cmake . $ cmake .
@ -332,7 +332,7 @@ Now you can run the unit tests::
$ make test $ make test
Benchmarks reside in a separate repository, Benchmarks reside in a separate repository,
`format-benchmarks <https://github.com/cppformat/format-benchmark>`__, `format-benchmarks <https://github.com/cppformat/format-benchmark>`_,
so to run the benchmarks you first need to clone this repository and so to run the benchmarks you first need to clone this repository and
generate Makefiles with CMake:: generate Makefiles with CMake::
@ -379,31 +379,31 @@ Documentation License
--------------------- ---------------------
The `Format String Syntax The `Format String Syntax
<http://cppformat.readthedocs.org/en/latest/#format-string-syntax>`__ <http://cppformat.readthedocs.org/en/latest/#format-string-syntax>`_
section in the documentation is based on the one from Python `string module section in the documentation is based on the one from Python `string module
documentation <http://docs.python.org/3/library/string.html#module-string>`__ documentation <http://docs.python.org/3/library/string.html#module-string>`_
adapted for the current library. For this reason the documentation is adapted for the current library. For this reason the documentation is
distributed under the Python Software Foundation license available in distributed under the Python Software Foundation license available in
`doc/LICENSE.python `doc/LICENSE.python
<https://raw.github.com/cppformat/cppformat/master/doc/LICENSE.python>`__. <https://raw.github.com/cppformat/cppformat/master/doc/LICENSE.python>`_.
Acknowledgments Acknowledgments
--------------- ---------------
The benchmark section of this readme file and the performance tests are taken The benchmark section of this readme file and the performance tests are taken
from the excellent `tinyformat <https://github.com/c42f/tinyformat>`__ library from the excellent `tinyformat <https://github.com/c42f/tinyformat>`_ library
written by Chris Foster. Boost Format library is acknowledged transitively written by Chris Foster. Boost Format library is acknowledged transitively
since it had some influence on tinyformat. since it had some influence on tinyformat.
Some ideas used in the implementation are borrowed from `Loki Some ideas used in the implementation are borrowed from `Loki
<http://loki-lib.sourceforge.net/>`__ SafeFormat and `Diagnostic API <http://loki-lib.sourceforge.net/>`_ SafeFormat and `Diagnostic API
<http://clang.llvm.org/doxygen/classclang_1_1Diagnostic.html>`__ in <http://clang.llvm.org/doxygen/classclang_1_1Diagnostic.html>`_ in
`Clang <http://clang.llvm.org/>`__. `Clang <http://clang.llvm.org/>`_.
Format string syntax and the documentation are based on Python's `str.format Format string syntax and the documentation are based on Python's `str.format
<http://docs.python.org/2/library/stdtypes.html#str.format>`__. <http://docs.python.org/2/library/stdtypes.html#str.format>`_.
Thanks `Doug Turnbull <https://github.com/softwaredoug>`__ for his valuable Thanks `Doug Turnbull <https://github.com/softwaredoug>`_ for his valuable
comments and contribution to the design of the type-safe API and comments and contribution to the design of the type-safe API and
`Gregory Czajkowski <https://github.com/gcflymoto>`__ for implementing binary `Gregory Czajkowski <https://github.com/gcflymoto>`_ for implementing binary
formatting. Thanks `Ruslan Baratov <https://github.com/ruslo>`__ for comprehensive formatting. Thanks `Ruslan Baratov <https://github.com/ruslo>`_ for comprehensive
`comparison of integer formatting algorithms <https://github.com/ruslo/int-dec-format-tests>`__ `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 and useful comments regarding performance, `Boris Kaul <https://github.com/localvoid>`_ for
`C++ counting digits benchmark <https://github.com/localvoid/cxx-benchmark-count-digits>`__. `C++ counting digits benchmark <https://github.com/localvoid/cxx-benchmark-count-digits>`_.