Document format string compilation

doc/api.rst

@@ -14,6 +14,7 @@ The {fmt} library API consists of the following parts:
 * :ref:`fmt/ranges.h <ranges-api>`: additional formatting support for ranges
   and tuples
 * :ref:`fmt/chrono.h <chrono-api>`: date and time formatting
+* :ref:`fmt/compile.h <compile-api>`: format string compilation
 * :ref:`fmt/ostream.h <ostream-api>`: ``std::ostream`` support
 * :ref:`fmt/printf.h <printf-api>`: ``printf`` formatting
 
@@ -421,6 +422,19 @@ formatting::
 The format string syntax is described in the documentation of
 `strftime <http://en.cppreference.com/w/cpp/chrono/c/strftime>`_.
 
+.. _compile-api:
+
+Format string compilation
+=========================
+
+Format strings can be processed at compile time for built-in and string types
+as well as user-defined types with ``constexpr`` ``parse`` functions in their
+``formatter`` specializations. Format string compilation can generate more
+binary code compared to the normal API and is only recommended in places where
+formatting is a performance bottleneck.
+
+.. doxygendefine:: FMT_COMPILE
+
 .. _ostream-api:
 
 ``std::ostream`` Support

include/fmt/compile.h

@@ -21,6 +21,19 @@ class compiled_string {};
 template <typename S>
 struct is_compiled_string : std::is_base_of<compiled_string, S> {};
 
+/**
+  \rst
+  Constructs a format string that will be translated into an efficient
+  formatting code at compile time from a string literal *s*. Requires C++17
+  ``constexpr if``.
+
+  **Example**::
+
+    // Converts 42 into std::string using the most efficient code and no runtime
+    // format string processing.
+    std::string s = fmt::format(FMT_COMPILE("{}"), 42);
+  \endrst
+ */
 #define FMT_COMPILE(s) FMT_STRING_IMPL(s, fmt::detail::compiled_string)
 
 template <typename T, typename... Tail>

include/fmt/format.h

@@ -2840,7 +2840,7 @@ FMT_CONSTEXPR basic_string_view<Char> compile_string_to_view(
   **Example**::
 
     // A compile-time error because 'd' is an invalid specifier for strings.
-    std::string s = format(FMT_STRING("{:d}"), "foo");
+    std::string s = fmt::format(FMT_STRING("{:d}"), "foo");
   \endrst
  */
 #define FMT_STRING(s) FMT_STRING_IMPL(s, fmt::compile_string)