✨ add std::format and fmt support

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/basic_json/format_as.md

@@ -0,0 +1,91 @@
+# format_as(basic_json)
+
+```cpp
+template <typename BasicJsonType>
+std::string format_as(const BasicJsonType& j);
+```
+
+This function implements the [`format_as`](https://fmt.dev/latest/api/#formatting-user-defined-types)
+customization point used by the [{fmt}](https://github.com/fmtlib/fmt) library (fmtlib). It has no
+dependency on any `fmt` header and no effect at all unless a caller's translation unit also includes
+`fmt` and calls `fmt::format`/`fmt::print` on a JSON value.
+
+## Template parameters
+
+`BasicJsonType`
+:   a specialization of [`basic_json`](index.md)
+
+## Return value
+
+string containing the serialization of the JSON value (same as [`dump()`](dump.md))
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+
+## Exceptions
+
+Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
+is not UTF-8 encoded
+
+## Complexity
+
+Linear.
+
+## Possible implementation
+
+```cpp
+template <typename BasicJsonType>
+std::string format_as(const BasicJsonType& j)
+{
+    return j.dump();
+}
+```
+
+## Notes
+
+!!! warning "Version-dependent effect on fmt"
+
+    `fmt` only picks up a `format_as` overload that returns a `std::string` in fmt **10.0.0 through
+    11.0.2**. Starting with fmt **11.1.0**, `fmt` restricts automatic `format_as` pickup to overloads that
+    return an arithmetic type, so this function has no effect there (it is simply unused, not a compile
+    error). If you use fmt \>= 11.1.0 (or want the same `#!cpp "{:#}"` pretty-print support that
+    [`std::formatter<basic_json>`](std_formatter.md) has), define your own `fmt::formatter` specialization,
+    for example:
+
+    ```cpp
+    template <>
+    struct fmt::formatter<nlohmann::json> : fmt::formatter<std::string>
+    {
+        auto format(const nlohmann::json& j, format_context& ctx) const
+        {
+            return fmt::formatter<std::string>::format(j.dump(), ctx);
+        }
+    };
+    ```
+
+## Examples
+
+??? example
+
+    The following code shows how the library's `format_as()` function integrates with `fmt::format`,
+    allowing argument-dependent lookup.
+
+    ```cpp
+    --8<-- "examples/format_as.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/format_as.output"
+    ```
+
+## See also
+
+- [dump](dump.md)
+- [std::formatter<basic_json>](std_formatter.md) - the `std::format` (C++20) equivalent
+
+## Version history
+
+- Added in version 3.12.x.

docs/mkdocs/docs/api/basic_json/index.md

@@ -301,6 +301,7 @@ Access to the JSON value
 - [**operator<<(std::ostream&)**](../operator_ltlt.md) - serialize to stream
 - [**operator>>(std::istream&)**](../operator_gtgt.md) - deserialize from stream
 - [**to_string**](to_string.md) - user-defined `to_string` function for JSON values
+- [**format_as**](format_as.md) - user-defined `format_as` function for JSON values (fmt support)
 
 ## Literals
 
@@ -308,6 +309,7 @@ Access to the JSON value
 
 ## Helper classes
 
+- [**std::formatter&lt;basic_json&gt;**](std_formatter.md) - make JSON values formattable with `std::format`
 - [**std::hash&lt;basic_json&gt;**](std_hash.md) - return a hash value for a JSON object
 - [**std::swap&lt;basic_json&gt;**](std_swap.md) - exchanges the values of two JSON objects
 

docs/mkdocs/docs/api/basic_json/std_formatter.md

@@ -0,0 +1,46 @@
+# <small>std::</small>formatter<nlohmann::basic_json\>
+
+```cpp
+namespace std {
+    template <>
+    struct formatter<nlohmann::basic_json, char>;
+}
+```
+
+Specialization to make JSON values formattable with [`std::format`](https://en.cppreference.com/w/cpp/utility/format/format)
+(and the other members of C++20's `<format>` header, such as `std::format_to`).
+
+Only an empty format spec (`#!cpp "{}"`) or the single flag `#!cpp "{:#}"` are accepted; any other spec
+throws [`std::format_error`](https://en.cppreference.com/w/cpp/utility/format/format_error).
+
+- `#!cpp "{}"` serializes the value the same way as [`dump()`](dump.md) (compact, no whitespace).
+- `#!cpp "{:#}"` serializes the value the same way as `#!cpp dump(4)` (pretty-printed with an indent of 4).
+
+This specialization is only available for `#!cpp char`-based JSON values and only if the standard library
+provides `<format>`, controlled by the [`JSON_HAS_STD_FORMAT`](../macros/json_has_std_format.md) macro.
+
+## Examples
+
+??? example
+
+    The example shows how to format JSON values with `std::format`.
+
+    ```cpp
+    --8<-- "examples/std_formatter.c++20.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/std_formatter.c++20.output"
+    ```
+
+## See also
+
+- [dump](dump.md) - serialization
+- [operator<<(std::ostream&)](../operator_ltlt.md) - serialize to stream
+- [format_as](format_as.md) - customization point used by `fmt::format` (fmtlib)
+
+## Version history
+
+- Added in version 3.12.x.

docs/mkdocs/docs/api/macros/index.md

@@ -19,6 +19,7 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**JSON_HAS_CPP_11**<br>**JSON_HAS_CPP_14**<br>**JSON_HAS_CPP_17**<br>**JSON_HAS_CPP_20**](json_has_cpp_11.md) - set supported C++ standard
 - [**JSON_HAS_FILESYSTEM**<br>**JSON_HAS_EXPERIMENTAL_FILESYSTEM**](json_has_filesystem.md) - control `std::filesystem` support
 - [**JSON_HAS_RANGES**](json_has_ranges.md) - control `std::ranges` support
+- [**JSON_HAS_STD_FORMAT**](json_has_std_format.md) - control `std::format`/`std::formatter` support
 - [**JSON_HAS_THREE_WAY_COMPARISON**](json_has_three_way_comparison.md) - control 3-way comparison support
 - [**JSON_NO_IO**](json_no_io.md) - switch off functions relying on certain C++ I/O headers
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](json_skip_unsupported_compiler_check.md) - do not warn about unsupported compilers

docs/mkdocs/docs/api/macros/json_has_std_format.md

@@ -0,0 +1,41 @@
+# JSON_HAS_STD_FORMAT
+
+```cpp
+#define JSON_HAS_STD_FORMAT /* value */
+```
+
+This macro indicates whether the standard library has support for `std::format`/`std::formatter` (that
+is, the `<format>` header). Possible values are `1` when supported or `0` when unsupported.
+
+## Default definition
+
+The default value is detected based on the preprocessor macros `#!cpp JSON_HAS_CPP_20` and
+`#!cpp __cpp_lib_format`.
+
+When the macro is not defined, the library will define it to its default value.
+
+## Notes
+
+!!! info "Enabled functionality"
+
+    When this macro evaluates to `1`, the library provides a
+    [`std::formatter<basic_json>`](../basic_json/std_formatter.md) specialization so JSON values can be
+    used directly with `std::format`.
+
+## Examples
+
+??? example
+
+    The code below forces the library to disable support for `std::format`, even if the standard library
+    would otherwise support it:
+
+    ```cpp
+    #define JSON_HAS_STD_FORMAT 0
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
+## Version history
+
+- Added in version 3.12.x.

docs/mkdocs/docs/examples/format_as.cpp

@@ -0,0 +1,16 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON value
+    json j = {{"one", 1}, {"two", 2}};
+
+    // format_as() is found via argument-dependent lookup, the same way
+    // fmt::format/fmt::print would find it
+    auto j_str = format_as(j);
+
+    std::cout << j_str << std::endl;
+}

docs/mkdocs/docs/examples/format_as.output

@@ -0,0 +1 @@
+{"one":1,"two":2}

docs/mkdocs/docs/examples/std_formatter.c++20.cpp

@@ -0,0 +1,16 @@
+#include <format>
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    json j = {{"one", 1}, {"two", 2}};
+
+    // compact formatting, like dump()
+    std::cout << std::format("{}", j) << "\n\n";
+
+    // pretty-printed formatting, like dump(4)
+    std::cout << std::format("{:#}", j) << std::endl;
+}

docs/mkdocs/docs/examples/std_formatter.c++20.output

@@ -0,0 +1,6 @@
+{"one":1,"two":2}
+
+{
+    "one": 1,
+    "two": 2
+}

docs/mkdocs/docs/home/faq.md

@@ -171,6 +171,30 @@ The library uses `std::numeric_limits<number_float_t>::digits10` (15 for IEEE `d
 
 See [this section](../features/types/number_handling.md#number-serialization) on the library's number handling for more information.
 
+### Using JSON values with `std::format` or `fmt`
+
+!!! question
+
+    - Can I use `std::format("{}", j)` on a JSON value?
+    - Can I use `fmt::format("{}", j)` or `fmt::print("{}", j)` (the [{fmt}](https://github.com/fmtlib/fmt) library) on a JSON value?
+
+`std::format` works out of the box since version 3.12.x, as long as the standard library provides
+`<format>` (see [`JSON_HAS_STD_FORMAT`](../api/macros/json_has_std_format.md)); see
+[`std::formatter<basic_json>`](../api/basic_json/std_formatter.md) for details, including the `#!cpp "{:#}"`
+pretty-print spec.
+
+For `fmt`, the library ships [`format_as`](../api/basic_json/format_as.md), a small customization point
+`fmt` looks for via argument-dependent lookup. It only has an effect on fmt 10.0.0 through 11.0.2 — from
+fmt 11.1.0 onwards, `fmt` no longer picks up a `format_as` overload that returns a `std::string`. On such
+versions (or any version, if you also want `#!cpp "{:#}"` pretty-print support), define your own
+`fmt::formatter` specialization; see [`format_as`](../api/basic_json/format_as.md) for a two-line recipe.
+
+If you get ambiguous-overload errors when passing a JSON value to `fmt::format`/`fmt::print` without any
+`fmt::formatter<json>` specialization in scope, that's `fmt` picking up `basic_json`'s implicit
+`operator ValueType()` conversion operator (see [#964](https://github.com/nlohmann/json/issues/964) and
+[#958](https://github.com/nlohmann/json/issues/958)); disabling it via
+[`JSON_USE_IMPLICIT_CONVERSIONS 0`](../api/macros/json_use_implicit_conversions.md) avoids the ambiguity.
+
 ## Compilation issues
 
 ### Android SDK

docs/mkdocs/mkdocs.yml

@@ -133,6 +133,7 @@ nav:
           - 'exception': api/basic_json/exception.md
           - 'find': api/basic_json/find.md
           - 'flatten': api/basic_json/flatten.md
+          - 'format_as': api/basic_json/format_as.md
           - 'from_bjdata': api/basic_json/from_bjdata.md
           - 'from_bson': api/basic_json/from_bson.md
           - 'from_cbor': api/basic_json/from_cbor.md
@@ -145,6 +146,7 @@ nav:
           - 'get_ptr': api/basic_json/get_ptr.md
           - 'get_ref': api/basic_json/get_ref.md
           - 'get_to': api/basic_json/get_to.md
+          - 'std::formatter<basic_json>': api/basic_json/std_formatter.md
           - 'std::hash<basic_json>': api/basic_json/std_hash.md
           - 'input_format_t': api/basic_json/input_format_t.md
           - 'insert': api/basic_json/insert.md
@@ -279,6 +281,7 @@ nav:
           - 'JSON_HAS_EXPERIMENTAL_FILESYSTEM, JSON_HAS_FILESYSTEM': api/macros/json_has_filesystem.md
           - 'JSON_HAS_RANGES': api/macros/json_has_ranges.md
           - 'JSON_HAS_STATIC_RTTI': api/macros/json_has_static_rtti.md
+          - 'JSON_HAS_STD_FORMAT': api/macros/json_has_std_format.md
           - 'JSON_HAS_THREE_WAY_COMPARISON': api/macros/json_has_three_way_comparison.md
           - 'JSON_NOEXCEPTION': api/macros/json_noexception.md
           - 'JSON_NO_IO': api/macros/json_no_io.md