mirror of https://github.com/nlohmann/json.git synced 2026-08-28 20:07:32 +00:00

Files

T

Niels Lohmann d386e0aa52 Do not require string_t to be convertible from std::string

Three places built a std::string and handed it to something expecting a
string_t: the UBJSON high-precision number reader, which every binary reader
instantiates, and the BSON writer's array element size calculation and write.
That silently required string_t to be implicitly convertible from std::string,
which std::string itself and types with a string_view conversion satisfy, but
many string types do not.

Construct the string_t explicitly from the data and size, which the
requirements already cover. This makes boost::container::string, eastl::string,
std::pmr::string, and std::basic_string with a custom allocator work as
StringType, none of which could previously be used with any binary format.

Add binary format coverage to the alt_string test, which had none, including a
UBJSON high-precision number -- the case that goes through the reader path.
BSON stays uncovered there: it additionally needs string_t::find(value_type),
which alt_string does not provide.

Also record which containers from Boost, Abseil, and EASTL work for each
template parameter, and correct two claims: std::pmr::string is usable after
this change, and tsl::ordered_map is not usable at all, because its iterators
expose the mapped value as const while basic_json modifies it in place.

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

2026-08-28 17:38:56 +00:00

3.6 KiB

Raw Blame History

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.

StringType must have a char-compatible value_type: the library relies on UTF-8/char-based storage and processing internally, so std::wstring, std::u16string, and std::u32string are not valid choices for StringType. 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::string interface (contiguous null-terminated data(), substr(), find(), append(), ...). See Template Parameter Requirements for the full list and for the string types that are known to work.

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.
Removed the requirement that string_t be implicitly convertible from #!cpp std::string, which the BSON writer and the UBJSON reader relied on, in version 3.13.0.

3.6 KiB Raw Blame History