std::formatter<nlohmann::basic_json>¶

namespace std {
    template <>
    struct formatter<nlohmann::basic_json, char>;
}

Specialization to make JSON values formattable with std::format (and the other members of C++20's <format> header, such as std::format_to).

A subset of the standard format spec grammar is supported, repurposed for JSON pretty-printing; any other spec component (sign, the 0 flag, precision, L, a dynamic width such as "{:{}}", or a trailing type character) throws std::format_error:

• "{}" serializes the value the same way as dump() (compact, no whitespace).
• "{:#}" ("alternate form") serializes the value the same way as dump(4) (pretty-printed with an indent of 4).
• A width, with or without "#" (e.g. "{:2}" or "{:#2}"), serializes the value the same way as dump(width) — a width on its own implies pretty-printing, since an indent size has no meaning for compact output.
• fill-and-align (e.g. "{:.>#}" or "{:.>3}") picks a custom indent character, the same way as dump(indent, indent_char). The alignment direction itself ('<', '>', '^') has no separate meaning for JSON values — only the fill character before it is used, and any of the three directions is accepted.

This specialization is only available for char-based JSON values and only if the standard library provides <format>, controlled by the JSON_HAS_STD_FORMAT macro.

Examples¶

#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) << "\n\n";

    // a width sets the indent, like dump(2)
    std::cout << std::format("{:2}", j) << "\n\n";

    // fill-and-align sets the indent character, like dump(4, '.')
    std::cout << std::format("{:.>#}", j) << std::endl;
}

{"one":1,"two":2}

{
    "one": 1,
    "two": 2
}

{
  "one": 1,
  "two": 2
}

{
...."one": 1,
...."two": 2
}

See also¶

• dump - serialization
• operator<<(std::ostream&) - serialize to stream
• format_as - customization point used by fmt::format (fmtlib)

Version history¶

• Added in version 3.12.x.