diff --git a/README.rst b/README.rst index e279fbb6..57a1943c 100644 --- a/README.rst +++ b/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 - `__ + `_ similar to the one used by `str.format - `__ in Python. + `_ in Python. * Support for user-defined types. * High speed: performance of the format API is close to that of - glibc's `printf `__ + glibc's `printf `_ and better than performance of IOStreams. See `Speed tests`_ and `Fast integer to string conversion in C++ `_. @@ -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 - `__. + `_. * 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 +* `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 `__ for more details. +See the `documentation `_ 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 -`__ +`_ macro to create your own functions similar to `format -`__ and -`print `__ +`_ and +`print `_ 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, ...)) -`__ in GCC. +they are mostly solved with `_attribute__ ((format (printf, ...)) +`_ in GCC. There is a POSIX extension that adds positional arguments required for -`i18n `__ +`i18n `_ 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++ -`__. +`_. 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 -`__. +`_. ============== ======== 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 `__. +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 format is close to that of printf. @@ -269,8 +269,8 @@ Compile time and code bloat ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The script `bloat-test.py -`__ -from `format-benchmark `__ +`_ +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 @@ -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 `__. +`Releases `_. Then go to the cppformat directory, generate Makefiles with -`CMake `__ and build the project:: +`CMake `_ 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 `__, +`format-benchmarks `_, 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 -`__ +`_ section in the documentation is based on the one from Python `string module -documentation `__ +documentation `_ adapted for the current library. For this reason the documentation is distributed under the Python Software Foundation license available in `doc/LICENSE.python -`__. +`_. Acknowledgments --------------- The benchmark section of this readme file and the performance tests are taken -from the excellent `tinyformat `__ library +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 `__. +`_ 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 +`_. +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 `__. +`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 `_.