Niels LohmannandGitHub
e9c3985f0a
* 📝 Fix documentation gaps found in a full GitHub Discussions review Reviewed all 1008 GitHub Discussions (2020-2026) for recurring questions that better or more visible documentation would have avoided. Adds/expands documentation for ~26 distinct gaps, including: - New "Debugging" page collecting natvis, GDB pretty printer, LLDB status, and JSON_DIAGNOSTICS pointers (previously scattered/undiscoverable) - Thread-safety and schema-validation FAQ entries - StringType's char-based requirement (no wstring/u16string/u32string) - Brace-initialization-yields-arrays warning directly on the constructor reference page (previously only in the FAQ, missed by users reading the constructor docs) - std::any exclusion from get<T>(), with a manual-dispatch example - Non-string-keyed std::map serializing as an array of pairs - ordered_json compatibility with NLOHMANN_DEFINE_TYPE_* macros (already worked, was undocumented) - std::array truncation on size-mismatched conversion (no exception) - static_cast vs. get<std::optional<T>>() divergence - Recipe for omitting a std::optional field instead of emitting null - No built-in nesting-depth limit during parsing + a callback-based workaround recipe - Recipe for streaming a large homogeneous array via parser callbacks - operator>> stream-position semantics for concatenated JSON values - JSON Pointer array-vs-object creation rule for non-existing paths - CMake target name (nlohmann_json_modules) needed to link C++20 modules - ESP-IDF/PlatformIO: no official package, link to a community fork - get(key, default) as the Python dict.get() equivalent - reserve() recipe for pre-allocating array capacity - JSONC as an alias for the existing ignore_comments/ignore_trailing_commas combination (distinct from the unsupported JSON5) - items() dereferenced-element type: decltype() idiom + detail-namespace stability caveat - Various macro/type-conversion limitations (MSGPACK_DEFINE_ARRAY equivalent, char-array round-tripping, ADL serializer macro gap) Signed-off-by: Niels Lohmann <mail@nlohmann.me> * 🎨 fix format Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.1 KiB
nlohmann::basic_json::string_t
using string_t = StringType;
The type used to store JSON strings.
RFC 8259 describes JSON strings as follows:
A string is a sequence of zero or more Unicode characters.
To store strings in C++, a type is defined by the template parameter described below. Unicode values are split by the JSON class into byte-sized characters during deserialization.
Template parameters
StringType- the container to store strings (e.g.,
std::string). Note this container is used for keys/names in objects, see object_t.StringTypemust have achar-compatiblevalue_type: the library relies on UTF-8/char-based storage and processing internally, sostd::wstring,std::u16string, andstd::u32stringare not valid choices forStringType. To work with wide-character data, convert it to/from UTF-8 at the boundary instead -- see the FAQ's wide string handling section for a conversion recipe.
Notes
Default type
With the default values for StringType (std::string), the default value for string_t is #!cpp std::string.
Encoding
Strings are stored in UTF-8 encoding. Therefore, functions like std::string::size() or std::string::length() return
the number of bytes in the string rather than the number of characters or glyphs.
String comparison
RFC 8259 states:
Software implementations are typically required to test names of object members for equality. Implementations that transform the textual representation into sequences of Unicode code units and then perform the comparison numerically, code unit by code unit, are interoperable in the sense that implementations will agree in all cases on equality or inequality of two strings. For example, implementations that compare strings with escaped characters unconverted may incorrectly find that
"a\\b"and"a\u005Cb"are not equal.
This implementation is interoperable as it does compare strings code unit by code unit.
Storage
String values are stored as pointers in a basic_json type. That is, for any access to string values, a pointer of type
string_t* must be dereferenced.
Cross-basic_json conversion requirements
When converting a string value from one basic_json specialization to another via the
converting constructor, the target string_t must be directly
constructible from the source basic_json's string_t type. If this requirement is not met, the
conversion does not fail; instead, the string is silently converted as an array of character codes,
which is incorrect. See issue #3425 for details
and an example.
Examples
??? example
The following code shows that `string_t` is by default, a typedef to `#!cpp std::string`.
```cpp
--8<-- "examples/string_t.cpp"
```
Output:
```json
--8<-- "examples/string_t.output"
```
Version history
- Added in version 1.0.0.