mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2024-12-24 12:14:26 +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
consistent.
* 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
<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.
* 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
`Fast integer to string conversion in C++
<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.
See `Compile time and code bloat`_.
* 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
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 <http://cppformat.github.io#portability>`__ with consistent output
* `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.
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
--------
@ -96,10 +96,10 @@ An object of any user-defined type for which there is an overloaded
// s == "The date is 2012-12-9"
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
<http://cppformat.github.io/doc/latest#fmt::format__StringRef.ArgListCR>`__ and
`print <http://cppformat.readthedocs.org/en/latest#fmt::print__StringRef.ArgListCR>`__
<http://cppformat.github.io/doc/latest#fmt::format__StringRef.ArgListCR>`_ and
`print <http://cppformat.readthedocs.org/en/latest#fmt::print__StringRef.ArgListCR>`_
which take arbitrary arguments:
.. code-block:: c++
@ -154,10 +154,10 @@ Printf
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
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.
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 <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
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
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>`__.
<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
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
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>`__.
<https://github.com/cppformat/format-benchmark/blob/master/tinyformat_test.cpp>`_.
============== ========
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
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
cannot be faster than the IOStreams because it uses them internally.
Performance of format is close to that of printf.
@ -269,8 +269,8 @@ 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>`__
<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
@ -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
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
`CMake <http://www.cmake.org/>`__ and build the project::
`CMake <http://www.cmake.org/>`_ and build the project::
$ cd cppformat
$ cmake .
@ -332,7 +332,7 @@ Now you can run the unit tests::
$ make test
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
generate Makefiles with CMake::
@ -379,31 +379,31 @@ Documentation License
---------------------
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
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
distributed under the Python Software Foundation license available in
`doc/LICENSE.python
<https://raw.github.com/cppformat/cppformat/master/doc/LICENSE.python>`__.
<https://raw.github.com/cppformat/cppformat/master/doc/LICENSE.python>`_.
Acknowledgments
---------------
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
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/>`__.
<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
<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>`__.
`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>`_.