Merge branch 'fmtlib:master' into zig-pkg

kassane · Jan 21, 2024 · fc53e71 · fc53e71
2 parents 3431e10 + 2caf1b3
commit fc53e71
Show file tree

Hide file tree

Showing 34 changed files with 1,446 additions and 1,262 deletions.
diff --git a/README.md b/README.md
@@ -218,24 +218,23 @@ in the following tables.
 | Method        | Compile Time, s | Executable size, KiB | Stripped size, KiB |
 |---------------|-----------------|----------------------|--------------------|
 | printf        |             1.6 |                   54 |                 50 |
-| IOStreams     |            25.6 |                   98 |                 84 |
-| {fmt} 1b7d9db |             4.8 |                   54 |                 50 |
-| tinyformat    |            30.5 |                  161 |                136 |
-| Boost Format  |            56.7 |                  530 |                317 |
+| IOStreams     |            25.9 |                   98 |                 84 |
+| fmt 83652df   |             4.8 |                   54 |                 50 |
+| tinyformat    |            29.1 |                  161 |                136 |
+| Boost Format  |            55.0 |                  530 |                317 |
 
-As you can see, {fmt} has ~70% less overhead in terms of resulting binary code
-size compared to iostreams and comes pretty close to `printf`. Boost Format and
-Folly Format have the largest overheads.
+{fmt} is fast to compile and is comparable to `printf` in terms of per-call
+binary size (within a rounding error on this system).
 
 **Non-optimized build**
 
 | Method        | Compile Time, s | Executable size, KiB | Stripped size, KiB |
 |---------------|-----------------|----------------------|--------------------|
 | printf        |             1.4 |                   54 |                 50 |
-| IOStreams     |            24.2 |                   92 |                 68 |
-| {fmt} 1b7d9db |             4.7 |                  217 |                214 |
-| tinyformat    |            25.7 |                  204 |                161 |
-| Boost Format  |            37.5 |                  831 |                462 |
+| IOStreams     |            23.4 |                   92 |                 68 |
+| {fmt} 83652df |             4.4 |                   89 |                 85 |
+| tinyformat    |            24.5 |                  204 |                161 |
+| Boost Format  |            36.4 |                  831 |                462 |
 
 `libc`, `lib(std)c++`, and `libfmt` are all linked as shared libraries
 to compare formatting function overhead only. Boost Format is a

diff --git a/doc/api.rst b/doc/api.rst
@@ -6,7 +6,7 @@ API Reference
 
 The {fmt} library API consists of the following parts:
 
-* :ref:`fmt/core.h <core-api>`: the core API providing main formatting functions
+* :ref:`fmt/base.h <base-api>`: the base API providing main formatting functions
   for ``char``/UTF-8 with C++20 compile-time checks and minimal dependencies
 * :ref:`fmt/format.h <format-api>`: the full format API providing additional
   formatting functions and locale support
@@ -24,12 +24,12 @@ The {fmt} library API consists of the following parts:
 All functions and types provided by the library reside in namespace ``fmt`` and
 macros have prefix ``FMT_``.
 
-.. _core-api:
+.. _base-api:
 
-Core API
+Base API
 ========
 
-``fmt/core.h`` defines the core API which provides main formatting functions
+``fmt/base.h`` defines the base API which provides main formatting functions
 for ``char``/UTF-8 with C++20 compile-time checks. It has minimal include
 dependencies for better compile times. This header is only beneficial when
 using {fmt} as a library (the default) and not in the header-only mode.
@@ -53,10 +53,18 @@ I/O errors are reported as `std::system_error
 <https://en.cppreference.com/w/cpp/error/system_error>`_ exceptions unless
 specified otherwise.
 
-.. _format:
+.. _print:
 
-.. doxygenfunction:: format(format_string<T...> fmt, T&&... args) -> std::string
-.. doxygenfunction:: vformat(string_view fmt, format_args args) -> std::string
+.. doxygenfunction:: fmt::print(format_string<T...> fmt, T&&... args)
+.. doxygenfunction:: fmt::vprint(string_view fmt, format_args args)
+
+.. doxygenfunction:: print(FILE *f, format_string<T...> fmt, T&&... args)
+.. doxygenfunction:: vprint(FILE *f, string_view fmt, format_args args)
+
+.. doxygenfunction:: println(format_string<T...> fmt, T&&... args)
+.. doxygenfunction:: println(FILE *f, format_string<T...> fmt, T&&... args)
+
+.. _format:
 
 .. doxygenfunction:: format_to(OutputIt out, format_string<T...> fmt, T&&... args) -> OutputIt
 .. doxygenfunction:: format_to_n(OutputIt out, size_t n, format_string<T...> fmt, T&&... args) -> format_to_n_result<OutputIt>
@@ -65,14 +73,6 @@ specified otherwise.
 .. doxygenstruct:: fmt::format_to_n_result
    :members:
 
-.. _print:
-
-.. doxygenfunction:: fmt::print(format_string<T...> fmt, T&&... args)
-.. doxygenfunction:: fmt::vprint(string_view fmt, format_args args)
-
-.. doxygenfunction:: print(std::FILE *f, format_string<T...> fmt, T&&... args)
-.. doxygenfunction:: vprint(std::FILE *f, string_view fmt, format_args args)
-
 Compile-Time Format String Checks
 ---------------------------------
 
@@ -132,21 +132,23 @@ inheritance or composition. This way you can support standard format specifiers
 without implementing them yourself. For example::
 
   // color.h:
-  #include <fmt/core.h>
+  #include <fmt/base.h>
 
   enum class color {red, green, blue};
 
   template <> struct fmt::formatter<color>: formatter<string_view> {
     // parse is inherited from formatter<string_view>.
 
-    auto format(color c, format_context& ctx) const;
+    auto format(color c, format_context& ctx) const
+      -> format_parse_context::iterator;
   };
 
   // color.cc:
   #include "color.h"
   #include <fmt/format.h>
 
-  auto fmt::formatter<color>::format(color c, format_context& ctx) const {
+  auto fmt::formatter<color>::format(color c, format_context& ctx) const
+      -> format_parse_context::iterator {
     string_view name = "unknown";
     switch (c) {
     case color::red:   name = "red"; break;
@@ -182,7 +184,8 @@ For example::
   struct fmt::formatter<point> : nested_formatter<double> {
     auto format(point p, format_context& ctx) const {
       return write_padded(ctx, [=](auto out) {
-        return format_to(out, "({}, {})", nested(p.x), nested(p.y));
+        return format_to(out, "({}, {})", this->nested(p.x),
+                         this->nested(p.y));
       });
     }
   };
@@ -276,7 +279,7 @@ binary footprint, for example (https://godbolt.org/z/vajfWEG4b):
 
 .. code:: c++
 
-    #include <fmt/core.h>
+    #include <fmt/base.h>
 
     void vlog(const char* file, int line, fmt::string_view format,
               fmt::format_args args) {
@@ -296,10 +299,7 @@ binary footprint, for example (https://godbolt.org/z/vajfWEG4b):
 Note that ``vlog`` is not parameterized on argument types which improves compile
 times and reduces binary code size compared to a fully parameterized version.
 
-.. doxygenfunction:: fmt::make_format_args(const Args&...)
-
-.. doxygenclass:: fmt::format_arg_store
-   :members:
+.. doxygenfunction:: make_format_args(T&... args)
 
 .. doxygenclass:: fmt::basic_format_args
    :members:
@@ -312,7 +312,7 @@ times and reduces binary code size compared to a fully parameterized version.
 .. doxygenclass:: fmt::basic_format_parse_context
    :members:
 
-.. doxygenclass:: fmt::basic_format_context
+.. doxygenclass:: fmt::context
    :members:
 
 .. doxygentypedef:: fmt::format_context
@@ -344,6 +344,9 @@ Format API
 ``fmt/format.h`` defines the full format API providing additional formatting
 functions and locale support.
 
+.. doxygenfunction:: format(format_string<T...> fmt, T&&... args) -> std::string
+.. doxygenfunction:: vformat(string_view fmt, format_args args) -> std::string
+
 Literal-Based API
 -----------------
 
@@ -473,7 +476,7 @@ Using ``fmt::join``, you can separate tuple elements with a custom separator::
   // Prints "1, a"
   fmt::print("{}", fmt::join(t, ", "));
 
-.. doxygenfunction:: fmt::join(Range &&range, string_view sep) -> join_view<detail::iterator_t<Range>, detail::sentinel_t<Range>>
+.. doxygenfunction:: fmt::join(Range &&range, string_view sep) -> join_view<decltype(std::begin(range)), decltype(std::end(range))>
 .. doxygenfunction:: fmt::join(It begin, Sentinel end, string_view sep) -> join_view<It, Sentinel>
 
 .. _chrono-api:
@@ -583,7 +586,7 @@ Terminal Color and Text Style
 
 ``fmt/color.h`` provides support for terminal color and text style output.
 
-.. doxygenfunction:: print(const text_style &ts, const S &format_str, const Args&... args)
+.. doxygenfunction:: print(const text_style &ts, format_string<T...> fmt, T&&... args)
 
 .. doxygenfunction:: fg(detail::color_type)
 

diff --git a/doc/build.py b/doc/build.py
@@ -54,9 +54,9 @@ def build_docs(version='dev', **kwargs):
       GENERATE_MAN      = NO
       GENERATE_RTF      = NO
       CASE_SENSE_NAMES  = NO
-      INPUT             = {0}/args.h {0}/core.h {0}/chrono.h {0}/color.h \
-                          {0}/compile.h {0}/format.h {0}/os.h {0}/ostream.h \
-                          {0}/printf.h {0}/ranges.h {0}/xchar.h
+      INPUT             = {0}/args.h {0}/base.h {0}/chrono.h {0}/color.h \
+                          {0}/core.h {0}/compile.h {0}/format.h {0}/os.h \
+                          {0}/ostream.h {0}/printf.h {0}/ranges.h {0}/xchar.h
       QUIET             = YES
       JAVADOC_AUTOBRIEF = YES
       AUTOLINK_SUPPORT  = NO

diff --git a/doc/syntax.rst b/doc/syntax.rst
@@ -354,7 +354,7 @@ The available presentation types (*chrono_type*) are:
 |         | The modified command ``%Ec`` produces the locale's alternate date  |
 |         | and time representation.                                           |
 +---------+--------------------------------------------------------------------+
-| ``'C'`` | The year divided by 100 using floored division, e.g. "55". If the  |
+| ``'C'`` | The year divided by 100 using floored division, e.g. "19". If the  |
 |         | result is a single decimal digit, it is prefixed with 0.           |
 |         | The modified command ``%EC`` produces the locale's alternative     |
 |         | representation of the century.                                     |