Simplify markup
This commit is contained in:
Victor Zverovich
parent
10698cc44d
commit
9cbb25e43f
68
README.rst
68
README.rst
@ -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>`_.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user