Niels LohmannandClaude Opus 5
599bb1b68c
The requirements that basic_json places on its eleven template parameters were only implied by how the library uses the resulting object_t, array_t, string_t, etc. Consumers had to discover them by trial and error. Add "Template Parameter Requirements" collecting them, split into what is always required and what is only required when a particular part of the API is instantiated. Notable findings that were previously undocumented: - ObjectType must provide a key_compare member type (actual_object_comparator names object_t::key_compare in both arms of a std::conditional), and its third template parameter is used as a comparator, so std::unordered_map cannot be used without a wrapper. - ArrayType must provide capacity() -- push_back(), emplace_back(), operator+=(), and operator[](size_type) call it unconditionally -- and needs random-access iterators, so std::deque and std::list do not work. - StringType needs contiguous, null-terminated data(), a one-byte value_type, and either assignability from std::to_string or an ADL int_to_string(). - NumberFloatType must be float, double, or long double for parsing and serialization; the integer types must satisfy std::is_integral. - AllocatorType must be stateless, support incomplete types, and use plain pointers. - BooleanType and the number types are union members and must be trivial. Link the new page from the basic_json overview, the types feature page, and the individual type alias pages, and correct the container examples given for ObjectType (std::unordered_map) and ArrayType (std::list), which do not work. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018hxZxz8svM54c6ATEvXp5E Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.4 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.Beyond the character type, the library expects a substantial part of the
#!cpp std::stringinterface (contiguous null-terminateddata(),substr(),find(),append(), ...). See Template Parameter Requirements for the full list.
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.