From c56cf3d074fb76296202747df1833fb587251baf Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Sat, 4 Jul 2020 08:20:10 -0700 Subject: [PATCH] Update changelog and readme --- ChangeLog.rst | 97 +++++++++++++++++++++++---------------- README.rst | 123 ++++++++++++++++++-------------------------------- 2 files changed, 102 insertions(+), 118 deletions(-) diff --git a/ChangeLog.rst b/ChangeLog.rst index 00f7ad45..56ab3a1f 100644 --- a/ChangeLog.rst +++ b/ChangeLog.rst @@ -3,17 +3,30 @@ * Reduced the library size. For example, on macOS the stripped binary statically linked with {fmt} shrank from ~368k to less than 100k: - http://www.zverovich.net/2020/05/21/reducing-library-size.html + http://www.zverovich.net/2020/05/21/reducing-library-size.html. + +* Added simpler and more efficient format string compilation API + (https://fmt.dev/dev/api.html#compile-api): + + .. code:: c++ + + #include + + // Converts 42 into std::string using the most efficient method and no + // runtime format string processing. + std::string s = fmt::format(FMT_COMPILE("{}"), 42); + + The old ``fmt::compile`` API is now deprecated. * Optimized integer formatting: ``format_to`` with format string compilation - and a stack-allocated buffer is now faster than both libc++ and libstdc++ - ``to_chars`` + and a stack-allocated buffer is now faster than ``to_chars`` on both + libc++ and libstdc++ (http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html). * Applied extern templates to improve compile times when using the core API - and ``fmt/format.h`` (`#1452`_). - For example, on macOS with clang the compile time dropped from 2.3s to 0.3s - with ``-O2`` and from 0.6s to 0.3s with the default settings (``-O0``). + and ``fmt/format.h`` (`#1452`_). For example, on macOS with clang the compile + time of a test TU dropped from 2.3s to 0.3s with ``-O2`` and from 0.6s to 0.3s + with the default settings (``-O0``). Before (``-O2``):: @@ -71,7 +84,8 @@ mov DWORD PTR [rsp+16], 42 mov QWORD PTR [rsp+32], OFFSET FLAT:.LC0 mov DWORD PTR [rsp+40], 0 - call fmt::v6::vprint(fmt::v6::basic_string_view, fmt::v6::format_args) + call fmt::v6::vprint(fmt::v6::basic_string_view, + fmt::v6::format_args) xor eax, eax add rsp, 56 ret @@ -145,12 +159,6 @@ is now ~40% faster (`#1685`_). -* Added the ``FMT_OS`` CMake option to control inclusion of OS-specific APIs - in the fmt target. This can be useful for embedded platforms - (`#1654`_, `#1656`_). - Thanks `@kwesolowski (Krzysztof Wesolowski) - `_. - * Improved compatibility between ``fmt::printf`` with the standard specs (`#1595`_, `#1683`_, `#1687`_, `#1699`_, `#1717`_). Thanks `@rimathia `_. @@ -159,7 +167,7 @@ * Removed the following deprecated APIs: - * ``fmt`` and ``FMT_STRING_ALIAS`` macros - replaced by ``FMT_STRING`` + * ``FMT_STRING_ALIAS`` and ``fmt`` macros - replaced by ``FMT_STRING`` * ``fmt::basic_string_view::char_type`` - replaced by ``fmt::basic_string_view::value_type`` * ``convert_to_int`` @@ -174,28 +182,36 @@ * Renamed the ``internal`` namespace to ``detail`` (`#1538`_). The former is still provided as an alias if the ``FMT_USE_INTERNAL`` macro is defined. +* Added the ``FMT_OS`` CMake option to control inclusion of OS-specific APIs + in the fmt target. This can be useful for embedded platforms + (`#1654`_, `#1656`_). + Thanks `@kwesolowski (Krzysztof Wesolowski) + `_. + * Replaced ``FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION`` with the ``FMT_FUZZ`` macro to prevent interferring with fuzzing of projects using {fmt} (`#1650`_). Thanks `@asraa (Asra Ali) `_. -* Improved documentation - (`#704`_, `#1643`_, `#1660`_, `#1681`_, `#1691`_, `#1706`_, `#1714`_). +* Improved documentation (`#704`_, `#1643`_, `#1660`_, `#1681`_, `#1691`_, + `#1706`_, `#1714`_, `#1721`_). Thanks `@senior7515 (Alexander Gallego) `_, `@lsr0 (Lindsay Roberts) `_, `@puetzk (Kevin Puetz) `_, `@fpelliccioni (Fernando Pelliccioni) `_, - Alexey Kuzmenko, - `@jelly (jelle van der Waa) `_, - `@claremacrae (Clare Macrae) `_. + Alexey Kuzmenko, `@jelly (jelle van der Waa) `_, + `@claremacrae (Clare Macrae) `_, + `@jiapengwen (文佳鹏) `_. * Implemented various build configuration fixes and improvements - (`#1657`_, `#1702`_). + (`#1657`_, `#1702`_, `#1728`_). Thanks `@jtojnar (Jan Tojnar) `_, - `@orivej (Orivej Desh) `_. + `@orivej (Orivej Desh) `_, + `@flagarde `_. * Fixed various warnings and compilation issues (`#1616`_, `#1622`_, `#1627`_, `#1628`_, `#1629`_, `#1631`_, `#1633`_, `#1649`_, `#1658`_, - `#1661`_, `#1667`_, `#1669`_, `#1692`_, `#1696`_, `#1697`_, `#1712`_). + `#1661`_, `#1667`_, `#1669`_, `#1692`_, `#1696`_, `#1697`_, `#1712`_, + `#1716`_, `#1722`_). Thanks `@gsjaardema (Greg Sjaardema) `_, `@gabime (Gabi Melman) `_, `@johnor (Johan) `_, @@ -204,7 +220,8 @@ `@peterbell10 `_, `@daixtrose (Markus Werle) `_, `@petrutlucian94 (Lucian Petrut) `_, - `@Neargye (Daniil Goncharov) `_. + `@Neargye (Daniil Goncharov) `_, + `@ambitslix (Attila M. Szilagyi) `_. 6.2.1 - 2020-05-09 ------------------ @@ -675,8 +692,8 @@ #include auto f = fmt::compile("{}"); - std::string s = fmt::format(f, 42); // can be called multiple times to format - // different values + std::string s = fmt::format(f, 42); // can be called multiple times to + // format different values // s == "42" It moves the cost of parsing a format string outside of the format function @@ -1486,7 +1503,8 @@ `@LarsGullik `_, `@foonathan (Jonathan Müller) `_, `@eliaskosunen (Elias Kosunen) `_, - `@christianparpart (Christian Parpart) `_, + `@christianparpart (Christian Parpart) + `_, `@DanielaE (Daniela Engert) `_, and `@mwinterb `_. @@ -1790,8 +1808,8 @@ // Prints "The date is 2016-04-29." (with the current date) fmt::print("The date is {:%Y-%m-%d}.", *std::localtime(&t)); -* ``std::ostream`` support including formatting of user-defined types that provide - overloaded ``operator<<`` has been moved to ``fmt/ostream.h``: +* ``std::ostream`` support including formatting of user-defined types that + provide overloaded ``operator<<`` has been moved to ``fmt/ostream.h``: .. code:: c++ @@ -1800,7 +1818,8 @@ class Date { int year_, month_, day_; public: - Date(int year, int month, int day) : year_(year), month_(month), day_(day) {} + Date(int year, int month, int day) + : year_(year), month_(month), day_(day) {} friend std::ostream &operator<<(std::ostream &os, const Date &d) { return os << d.year_ << '-' << d.month_ << '-' << d.day_; @@ -1885,7 +1904,8 @@ Thanks to `@mwinterb `_. * Added ``fprintf`` overload that writes to a ``std::ostream`` (`#251`_). - Thanks to `nickhutchinson (Nicholas Hutchinson) `_. + Thanks to `nickhutchinson (Nicholas Hutchinson) + `_. * Export symbols when building a Windows DLL (`#245`_). Thanks to `macdems (Maciek Dems) `_. @@ -2028,8 +2048,8 @@ General fmt::printf("The date is %s", Date(2012, 12, 9)); * [Breaking] The ``Buffer`` template is now part of the public API and can be - used to implement custom memory buffers (`#140`_). - Thanks to `@polyvertex (Jean-Charles Lefebvre) `_. + used to implement custom memory buffers (`#140`_). Thanks to + `@polyvertex (Jean-Charles Lefebvre) `_. * [Breaking] Improved compatibility between ``BasicStringRef`` and `std::experimental::basic_string_view @@ -2075,8 +2095,8 @@ General Optimization ~~~~~~~~~~~~ -* Made formatting of user-defined types more efficient with a custom stream buffer - (`#92`_, `#230`_). +* Made formatting of user-defined types more efficient with a custom stream + buffer (`#92`_, `#230`_). Thanks to `@NotImplemented `_. * Further improved performance of ``fmt::Writer`` on integer formatting @@ -2110,8 +2130,9 @@ Distribution Thanks to `@jackyf (Eugene V. Lyubimkin) `_. -* `Packages for Fedora and RHEL `_ - are now available. Thanks to Dave Johansen. +* `Packages for Fedora and RHEL + `_ are now + available. Thanks to Dave Johansen. * C++ Format can now be installed via `Homebrew `_ on OS X (`#157`_):: @@ -2181,8 +2202,8 @@ Fixes * Fixed compiler warnings (`#95`_, `#96`_, `#114`_, `#135`_, `#142`_, `#145`_, `#146`_, `#158`_, `#163`_, `#175`_, `#190`_, `#191`_, `#194`_, `#196`_, `#216`_, `#218`_, `#220`_, `#229`_, `#233`_, `#234`_, `#236`_, `#281`_, - `#289`_). - Thanks to `@seanmiddleditch (Sean Middleditch) `_, + `#289`_). Thanks to + `@seanmiddleditch (Sean Middleditch) `_, `@dixlorenz (Dix Lorenz) `_, `@CarterLi (李通洲) `_, `@Naios `_, diff --git a/README.rst b/README.rst index ffb467dc..a0c07a3a 100644 --- a/README.rst +++ b/README.rst @@ -9,7 +9,8 @@ .. image:: https://oss-fuzz-build-logs.storage.googleapis.com/badges/libfmt.svg :alt: fmt is continuously fuzzed att oss-fuzz - :target: https://bugs.chromium.org/p/oss-fuzz/issues/list?colspec=ID%20Type%20Component%20Status%20Proj%20Reported%20Owner%20Summary&q=proj%3Dlibfmt&can=1 + :target: https://bugs.chromium.org/p/oss-fuzz/issues/list?colspec=ID%20Type\ +%20Component%20Status%20Proj%20Reported%20Owner%20Summary&q=proj%3Dlibfmt&can=1 .. image:: https://img.shields.io/badge/stackoverflow-fmt-blue.svg :alt: Ask questions at StackOverflow with the tag fmt @@ -20,25 +21,28 @@ It can be used as a safe and fast alternative to (s)printf and iostreams. `Documentation `__ -Q&A: ask questions on `StackOverflow with the tag fmt `_. +Q&A: ask questions on `StackOverflow with the tag fmt +`_. Features -------- -* Replacement-based `format API `_ with - positional arguments for localization. +* Simple `format API `_ with positional arguments + for localization +* Implementation of `C++20 std::format + `__ * `Format string syntax `_ similar to the one - of `str.format `_ - in Python. + of Python's + `format `_ * Safe `printf implementation `_ including - the POSIX extension for positional arguments. -* Implementation of `C++20 std::format `__. -* Support for user-defined types. + the POSIX extension for positional arguments +* Extensibility: supports user-defined types * High performance: faster than common standard library implementations of `printf `_, - iostreams and `to_string`. See `Speed tests`_ and `Fast integer to string conversion in C++ - `_. + iostreams, ``to_string`` and ``to_chars``. See `Speed tests`_ and + `Converting a hundred million integers to strings per second + `_. * Small code size both in terms of source code (the minimum configuration consists of just three header files, ``core.h``, ``format.h`` and ``format-inl.h``) and compiled code. See `Compile time and code bloat`_. @@ -46,16 +50,17 @@ Features `_ and is continuously fuzzed. * Safety: the library is fully type safe, errors in format strings can be reported at compile time, automatic memory management prevents buffer overflow - errors. + errors * Ease of use: small self-contained code base, no external dependencies, permissive MIT `license `_ * `Portability `_ with - consistent output across platforms and support for older compilers. + consistent output across platforms and support for older compilers * Clean warning-free codebase even on high warning levels - (``-Wall -Wextra -pedantic``). + (``-Wall -Wextra -pedantic``) +* Locale-independence by default * Support for wide strings. -* Optional header-only configuration enabled with the ``FMT_HEADER_ONLY`` macro. +* Optional header-only configuration enabled with the ``FMT_HEADER_ONLY`` macro See the `documentation `_ for more details. @@ -177,14 +182,14 @@ Folly Format folly::format 2.23 {fmt} is the fastest of the benchmarked methods, ~35% faster than ``printf``. The above results were generated by building ``tinyformat_test.cpp`` on macOS -10.14.6 with ``clang++ -O3 -DNDEBUG -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"`` +10.14.6 with ``clang++ -O3 -DNDEBUG -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 2,000,000 times with output sent to ``/dev/null``; for further details refer to the `source `_. -{fmt} is 10x faster than ``std::ostringstream`` and ``sprintf`` on floating-point -formatting (`dtoa-benchmark `_) +{fmt} is up to 10x faster than ``std::ostringstream`` and ``sprintf`` on +floating-point formatting (`dtoa-benchmark `_) and faster than `double-conversion `_: .. image:: https://user-images.githubusercontent.com/576385/69767160-cdaca400-112f-11ea-9fc5-347c9f83caad.png @@ -425,8 +430,8 @@ Format also has excessive build times and severe code bloat issues (see FastFormat ~~~~~~~~~~ -This is an interesting library which is fast, safe and has positional -arguments. However it has significant limitations, citing its author: +This is an interesting library which is fast, safe and has positional arguments. +However, it has significant limitations, citing its author: Three features that have no hope of being accommodated within the current design are: @@ -435,8 +440,8 @@ arguments. However it has significant limitations, citing its author: * Octal/hexadecimal encoding * Runtime width/alignment specification -It is also quite big and has a heavy dependency, STLSoft, which might be -too restrictive for using it in some projects. +It is also quite big and has a heavy dependency, STLSoft, which might be too +restrictive for using it in some projects. Boost Spirit.Karma ~~~~~~~~~~~~~~~~~~ @@ -444,32 +449,9 @@ 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::format_int`` on Karma's own benchmark, -see `Fast integer to string conversion in C++ -`_. - -FAQ ---- - -Q: how can I capture formatting arguments and format them later? - -A: use ``std::tuple``: - -.. code:: c++ - - template - auto capture(const Args&... args) { - return std::make_tuple(args...); - } - - auto print_message = [](const auto&... args) { - fmt::print(args...); - }; - - // Capture and store arguments: - auto args = capture("{} {}", 42, "foo"); - // Do formatting: - std::apply(print_message, args); +than ``fmt::format_to`` with format string compilation on Karma's own benchmark, +see `Converting a hundred million integers to strings per second +`_. License ------- @@ -477,18 +459,19 @@ License {fmt} is distributed under the MIT `license `_. -The `Format String Syntax -`_ -section in the documentation is based on the one from Python `string module -documentation `_ -adapted for the current library. For this reason the documentation is -distributed under the Python Software Foundation license available in -`doc/python-license.txt -`_. -It only applies if you distribute the documentation of fmt. +Documentation License +--------------------- -Acknowledgments ---------------- +The `Format String Syntax `_ +section in the documentation is based on the one from Python `string module +documentation `_. +For this reason the documentation is distributed under the Python Software +Foundation license available in `doc/python-license.txt +`_. +It only applies if you distribute the documentation of {fmt}. + +Maintainers +----------- The {fmt} library is maintained by Victor Zverovich (`vitaut `_) and Jonathan Müller (`foonathan @@ -497,23 +480,3 @@ See `Contributors `_ and `Releases `_ for some of the names. Let us know if your contribution is not listed or mentioned incorrectly and we'll make it right. - -The benchmark section of this readme file and the performance tests are taken -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 `_. -Format string syntax and the documentation are based on Python's `str.format -`_. -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 `_. -Thanks to `CarterLi `_ for contributing various -improvements to the code.