mirror of
https://github.com/nlohmann/json.git
synced 2026-07-21 19:23:03 +04:00
Niels Lohmann
521a084827
* 📝 Fix documentation gaps for 3.13.0 release (todos 138-142) - Todo 138: Add "Known issues" section to modules.md with compiler-specific troubleshooting (GCC redefinition, MSVC symbol export). Add pointer note to quality_assurance.md. - Todo 139: Document CBOR/MessagePack half-precision float encoding for NaN/Infinity (0xF9/0xCA with exact byte sequences). Explain pre-3.13.0 double-precision bug mechanism without issue citations. - Todo 140: Document CBOR negative-integer-overflow rejection (parse_error.112) for magnitudes exceeding int64_t range (already implemented in rev 1). - Todo 141: Update version history in value.md and operator[].md with behavior-change details, removing issue citations per citation policy (prose is self-contained). - Todo 142: Global sed replace of 3.12.x → 3.13.0 placeholder across all 20 documentation files. Revision 2 incorporates feedback to reduce changelog-like issue citations. Only citations that add unique troubleshooting value are retained (#5103 for GCC workaround, #3970 for MSVC symbol export). "Known issues" section follows PR #5252's visual pattern (info admonition with bold-bullet format). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * 📝 Document integer type selection, type_name() invalid value, and std::optional get() fix - number_handling.md: clarify that positive/negative integers select unsigned/signed storage based on the leading minus sign (todo 143). - type_name.md: document the new "invalid" return value for corrupted JSON values (todo 145). - get.md: note that get<std::optional<T>>() was unreachable in every configuration prior to 3.13.0 due to an internal macro-guard bug, unrelated to JSON_USE_IMPLICIT_CONVERSIONS's actual effect (todo 144). Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.0 KiB
3.0 KiB
format_as(basic_json)
template <typename BasicJsonType>
std::string format_as(const BasicJsonType& j);
This function implements the format_as
customization point used by the {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
Return value
string containing the serialization of the JSON value (same as dump())
Exception safety
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
Exceptions
Throws type_error.316 if a string stored inside the JSON value
is not UTF-8 encoded
Complexity
Linear.
Possible implementation
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 pretty-print spec support that
[`std::formatter<basic_json>`](std_formatter.md) has (`#!cpp "{:#}"`, a width to set the indent such
as `#!cpp "{:2}"`/`#!cpp "{:#2}"`, and fill-and-align to pick the indent character such as
`#!cpp "{:.>#}"`), define your own `fmt::formatter` specialization mirroring the same logic:
```cpp
--8<-- "../../../tests/fmt_formatter/project/main.cpp:formatter_recipe"
```
This recipe isn't shipped by the library itself, since doing so would make `fmt` a build dependency
(see the FAQ entry on
[using JSON values with `std::format` or `fmt`](../../home/faq.md#using-json-values-with-stdformat-or-fmt)
for more background) — but it *is* compiled and exercised against a real, current `fmt` release as
part of the library's own test suite (`tests/fmt_formatter`, via CMake `FetchContent`), so it's kept in
sync with `std::formatter<basic_json>` and verified to actually work, not just illustrative.
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
- std::formatter<basic_json> - the
std::format(C++20) equivalent - Serialization - the serialization article
Version history
- Added in version 3.13.0.