From a7f68dcc01c527e39671e37d934b58b4e7b1d719 Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Sat, 16 Mar 2019 06:46:19 -0700 Subject: [PATCH] Update readme --- README.rst | 54 ++++++++++++++++++++++++++---------------------------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/README.rst b/README.rst index 39ebf7e7..0092e644 100644 --- a/README.rst +++ b/README.rst @@ -248,17 +248,17 @@ libraries. 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 +printf ~~~~~~ -The good thing about printf is that it is pretty fast and readily available +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, ...)) +doesn't support user-defined types. ``print`` also has safety issues although +they are somewhat mitigated with `__attribute__ ((format (printf, ...)) `_ in GCC. There is a POSIX extension that adds positional arguments required for `i18n `_ -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. iostreams @@ -280,16 +280,16 @@ Matthew Wilson, the author of FastFormat, called this "chevron hell". iostreams don't support positional arguments by design. The good part is that iostreams support user-defined types and are safe although -error reporting is awkward. +error handling is awkward. -Boost Format library -~~~~~~~~~~~~~~~~~~~~ +Boost Format +~~~~~~~~~~~~ -This is a very powerful library which supports both printf-like format -strings and positional arguments. Its main 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`_). +This is a very powerful library which supports both ``printf``-like format +strings and positional arguments. Its main 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 ~~~~~~~~~~ @@ -310,26 +310,24 @@ 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. +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 and +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. +This library supports ``printf``-like format strings and is very small . +It doesn't support positional arguments and wrapping it in C++98 is somewhat +difficult. Tinyformat relies on iostreams which limits its performance. 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, +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::format_int`` on Karma's own benchmark, see `Fast integer to string conversion in C++ `_. @@ -350,13 +348,13 @@ Boost Format 1.67 boost::format 7.98 Folly Format folly::format 2.23 ================= ============= =========== -{fmt} is the fastest of the benchmarked methods, ~17% faster than `printf`. +{fmt} is the fastest of the benchmarked methods, ~17% faster than ``printf``. The above results were generated by building ``tinyformat_test.cpp`` on macOS 10.14.3 with ``clang++ -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 +or equivalent is filled 2,000,000 times with output sent to ``/dev/null``; for +further details refer to the `source `_. Compile time and code bloat