Update changelog and readme

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 <fmt/compile.h>
+
+     // 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<char>, fmt::v6::format_args)
+              call    fmt::v6::vprint(fmt::v6::basic_string_view<char>,
+                                      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)
-  <https://github.com/kwesolowski>`_.
-
 * Improved compatibility between ``fmt::printf`` with the standard specs
   (`#1595`_, `#1683`_, `#1687`_, `#1699`_, `#1717`_).
   Thanks `@rimathia <https://github.com/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)
+  <https://github.com/kwesolowski>`_.
+
 * 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) <https://github.com/asraa>`_.
 
-* Improved documentation
-  (`#704`_, `#1643`_, `#1660`_, `#1681`_, `#1691`_, `#1706`_, `#1714`_).
+* Improved documentation (`#704`_, `#1643`_, `#1660`_, `#1681`_, `#1691`_,
+  `#1706`_, `#1714`_, `#1721`_).
   Thanks `@senior7515 (Alexander Gallego) <https://github.com/senior7515>`_,
   `@lsr0 (Lindsay Roberts) <https://github.com/lsr0>`_,
   `@puetzk (Kevin Puetz) <https://github.com/puetzk>`_,
   `@fpelliccioni (Fernando Pelliccioni) <https://github.com/fpelliccioni>`_,
-  Alexey Kuzmenko,
-  `@jelly (jelle van der Waa) <https://github.com/jelly>`_,
-  `@claremacrae (Clare Macrae) <https://github.com/claremacrae>`_.
+  Alexey Kuzmenko, `@jelly (jelle van der Waa) <https://github.com/jelly>`_,
+  `@claremacrae (Clare Macrae) <https://github.com/claremacrae>`_,
+  `@jiapengwen (文佳鹏) <https://github.com/jiapengwen>`_.
 
 * Implemented various build configuration fixes and improvements
-  (`#1657`_, `#1702`_).
+  (`#1657`_, `#1702`_, `#1728`_).
   Thanks `@jtojnar (Jan Tojnar) <https://github.com/jtojnar>`_,
-  `@orivej (Orivej Desh) <https://github.com/orivej>`_.
+  `@orivej (Orivej Desh) <https://github.com/orivej>`_,
+  `@flagarde <https://github.com/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) <https://github.com/gsjaardema>`_,
   `@gabime (Gabi Melman) <https://github.com/gabime>`_,
   `@johnor (Johan) <https://github.com/johnor>`_,
@@ -204,7 +220,8 @@
   `@peterbell10 <https://github.com/peterbell10>`_,
   `@daixtrose (Markus Werle) <https://github.com/daixtrose>`_,
   `@petrutlucian94 (Lucian Petrut) <https://github.com/petrutlucian94>`_,
-  `@Neargye (Daniil Goncharov) <https://github.com/Neargye>`_.
+  `@Neargye (Daniil Goncharov) <https://github.com/Neargye>`_,
+  `@ambitslix (Attila M. Szilagyi) <https://github.com/ambitslix>`_.
 
 6.2.1 - 2020-05-09
 ------------------
@@ -675,8 +692,8 @@
      #include <fmt/compile.h>
 
      auto f = fmt::compile<int>("{}");
-     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 <https://github.com/LarsGullik>`_,
   `@foonathan (Jonathan Müller) <https://github.com/foonathan>`_,
   `@eliaskosunen (Elias Kosunen) <https://github.com/eliaskosunen>`_,
-  `@christianparpart (Christian Parpart) <https://github.com/christianparpart>`_,
+  `@christianparpart (Christian Parpart)
+  <https://github.com/christianparpart>`_,
   `@DanielaE (Daniela Engert) <https://github.com/DanielaE>`_,
   and `@mwinterb <https://github.com/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 <https://github.com/mwinterb>`_.
 
 * Added ``fprintf`` overload that writes to a ``std::ostream`` (`#251`_).
-  Thanks to `nickhutchinson (Nicholas Hutchinson) <https://github.com/nickhutchinson>`_.
+  Thanks to `nickhutchinson (Nicholas Hutchinson)
+  <https://github.com/nickhutchinson>`_.
 
 * Export symbols when building a Windows DLL (`#245`_).
   Thanks to `macdems (Maciek Dems) <https://github.com/macdems>`_.
@@ -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) <https://github.com/polyvertex>`_.
+  used to implement custom memory buffers (`#140`_). Thanks to
+  `@polyvertex (Jean-Charles Lefebvre) <https://github.com/polyvertex>`_.
 
 * [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 <https://github.com/NotImplemented>`_.
 
 * Further improved performance of ``fmt::Writer`` on integer formatting
@@ -2110,8 +2130,9 @@ Distribution
 
   Thanks to `@jackyf (Eugene V. Lyubimkin) <https://github.com/jackyf>`_.
 
-* `Packages for Fedora and RHEL <https://admin.fedoraproject.org/pkgdb/package/cppformat/>`_
-  are now available. Thanks to Dave Johansen.
+* `Packages for Fedora and RHEL
+  <https://admin.fedoraproject.org/pkgdb/package/cppformat/>`_ are now
+  available. Thanks to Dave Johansen.
   
 * C++ Format can now be installed via `Homebrew <http://brew.sh/>`_ 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) <https://github.com/seanmiddleditch>`_,
+  `#289`_). Thanks to
+  `@seanmiddleditch (Sean Middleditch) <https://github.com/seanmiddleditch>`_,
   `@dixlorenz (Dix Lorenz) <https://github.com/dixlorenz>`_,
   `@CarterLi (李通洲) <https://github.com/CarterLi>`_,
   `@Naios <https://github.com/Naios>`_,

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 <https://fmt.dev/latest/>`__
 
-Q&A: ask questions on `StackOverflow with the tag fmt <https://stackoverflow.com/questions/tagged/fmt>`_.
+Q&A: ask questions on `StackOverflow with the tag fmt
+<https://stackoverflow.com/questions/tagged/fmt>`_.
 
 Features
 --------
 
-* Replacement-based `format API <https://fmt.dev/dev/api.html>`_ with
-  positional arguments for localization.
+* Simple `format API <https://fmt.dev/dev/api.html>`_ with positional arguments
+  for localization
+* Implementation of `C++20 std::format
+  <https://en.cppreference.com/w/cpp/utility/format>`__
 * `Format string syntax <https://fmt.dev/dev/syntax.html>`_ similar to the one
-  of `str.format <https://docs.python.org/3/library/stdtypes.html#str.format>`_
-  in Python.
+  of Python's
+  `format <https://docs.python.org/3/library/stdtypes.html#str.format>`_
 * Safe `printf implementation
   <https://fmt.dev/latest/api.html#printf-formatting>`_ including
-  the POSIX extension for positional arguments.
-* Implementation of `C++20 std::format <https://en.cppreference.com/w/cpp/utility/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 <https://en.cppreference.com/w/cpp/io/c/fprintf>`_,
-  iostreams and `to_string`. See `Speed tests`_ and `Fast integer to string conversion in C++
-  <http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
+  iostreams, ``to_string`` and ``to_chars``. See `Speed tests`_ and
+  `Converting a hundred million integers to strings per second
+  <http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_.
 * 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
   <https://github.com/fmtlib/fmt/tree/master/test>`_ 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
   <https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_
 * `Portability <https://fmt.dev/latest/index.html#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 <https://fmt.dev/latest/>`_ 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
 <https://github.com/fmtlib/format-benchmark/blob/master/tinyformat_test.cpp>`_.
 
-{fmt} is 10x faster than ``std::ostringstream`` and ``sprintf`` on floating-point
-formatting (`dtoa-benchmark <https://github.com/fmtlib/dtoa-benchmark>`_)
+{fmt} is up to 10x faster than ``std::ostringstream`` and ``sprintf`` on
+floating-point formatting (`dtoa-benchmark <https://github.com/fmtlib/dtoa-benchmark>`_)
 and faster than `double-conversion <https://github.com/google/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++
-<http://zverovich.net/2013/09/07/integer-to-string-conversion-in-cplusplus.html>`_.
-
-FAQ
----
-
-Q: how can I capture formatting arguments and format them later?
-
-A: use ``std::tuple``:
-
-.. code:: c++
-
-   template <typename... Args>
-   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
+<http://www.zverovich.net/2020/06/13/fast-int-to-string-revisited.html>`_.
 
 License
 -------
@@ -477,18 +459,19 @@ License
 {fmt} is distributed under the MIT `license
 <https://github.com/fmtlib/fmt/blob/master/LICENSE.rst>`_.
 
-The `Format String Syntax
-<https://fmt.dev/latest/syntax.html>`_
+Documentation License
+---------------------
+
+The `Format String Syntax <https://fmt.dev/latest/syntax.html>`_
 section in the documentation is based on the one from Python `string module
-documentation <https://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/python-license.txt
+documentation <https://docs.python.org/3/library/string.html#module-string>`_.
+For this reason the documentation is distributed under the Python Software
+Foundation license available in `doc/python-license.txt
 <https://raw.github.com/fmtlib/fmt/master/doc/python-license.txt>`_.
-It only applies if you distribute the documentation of fmt.
+It only applies if you distribute the documentation of {fmt}.
 
-Acknowledgments
----------------
+Maintainers
+-----------
 
 The {fmt} library is maintained by Victor Zverovich (`vitaut
 <https://github.com/vitaut>`_) and Jonathan Müller (`foonathan
@@ -497,23 +480,3 @@ See `Contributors <https://github.com/fmtlib/fmt/graphs/contributors>`_ and
 `Releases <https://github.com/fmtlib/fmt/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 <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
-<https://clang.llvm.org/doxygen/classclang_1_1Diagnostic.html>`_ in
-`Clang <https://clang.llvm.org/>`_.
-Format string syntax and the documentation are based on Python's `str.format
-<https://docs.python.org/3/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>`_.
-Thanks to `CarterLi <https://github.com/CarterLi>`_ for contributing various
-improvements to the code.