amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-08-29 04:17:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: remove a duplicated StringType compatibility section

Browse Source 
The StringType section carried two 'Compatible types' tables and two copies of
the reference-implementation tip. The second table was a stale copy from before
the binary format string fixes and still listed std::pmr::string and
std::basic_string with a custom allocator as unusable, contradicting the
corrected table a few lines above it, and it dragged along the old explanation
that blamed int_to_string.

Drop the stale copy and put the surviving table before the notes, so the
'see below' in the std::pmr::string row points forwards.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann
2026-08-28 17:38:57 +00:00
parent ca47dd539d
commit 690c3be01d
1 changed files with 15 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mkdocs/docs/features/types/template_parameters.md
+15 -40
View File
@@ -289,6 +289,21 @@ using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
| [`std::hash<basic_json>`](../../api/basic_json/std_hash.md) | a specialization of `#!cpp std::hash<StringType>` |
| exception messages | `data()` and `size()`, or `begin()` and `end()` |
### Compatible types
| Type | Support |
|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `#!cpp std::string` (default) | full |
| `#!cpp std::basic_string` with a custom **stateless** allocator | full |
| `#!cpp std::pmr::string` | compiles and behaves correctly, but always allocates from the default memory resource -- see below |
| `boost::container::string` | full, once a `#!cpp std::hash` specialization is supplied (Boost provides `boost::hash` instead) |
| `folly::fbstring` | full; requires C++20, see the note below |
| `eastl::string` | full, except that [`parse`](../../api/basic_json/parse.md) does not accept it directly; pass a character range or a `#!cpp std::string` |
| a custom string class in a user-defined namespace | full, if the requirements above are met |
| `#!cpp std::wstring`, `#!cpp std::u16string`, `#!cpp std::u32string` | not usable; the character type is not one byte wide |
| `absl::Cord` | not usable; no `value_type`, and the storage is not contiguous |
| `QString` | not usable; UTF-16, so the character type is not one byte wide |
!!! warning "A `std::pmr::string` does not allocate from a memory resource you choose"
`basic_json` cannot be given an allocator or a memory resource. `AllocatorType` is default-constructed at every
@@ -311,46 +326,6 @@ using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
The unit test `tests/src/unit-alt-string.cpp` contains `alt_string`, a minimal string type that satisfies the
requirements needed for the tested subset of the API. It is a good starting point for a custom `StringType`.
### Compatible types
| Type | Support |
|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `#!cpp std::string` (default) | full |
| `#!cpp std::basic_string` with a custom **stateless** allocator | full |
| `#!cpp std::pmr::string` | compiles and behaves correctly, but always allocates from the default memory resource -- see below |
| `boost::container::string` | full, once a `#!cpp std::hash` specialization is supplied (Boost provides `boost::hash` instead) |
| `folly::fbstring` | full; requires C++20, see the note below |
| `eastl::string` | full, except that [`parse`](../../api/basic_json/parse.md) does not accept it directly; pass a character range or a `#!cpp std::string` |
| a custom string class in a user-defined namespace | full, if the requirements above are met |
| `#!cpp std::wstring`, `#!cpp std::u16string`, `#!cpp std::u32string` | not usable; the character type is not one byte wide |
| `absl::Cord` | not usable; no `value_type`, and the storage is not contiguous |
| `QString` | not usable; UTF-16, so the character type is not one byte wide |
!!! tip "Reference implementation"
The unit test `tests/src/unit-alt-string.cpp` contains `alt_string`, a minimal string type that satisfies the
requirements needed for the tested subset of the API. It is a good starting point for a custom `StringType`.
### Compatible types
| Type | Support |
|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `#!cpp std::string` (default) | full |
| a custom string class in a user-defined namespace | full, if the requirements above are met |
| `#!cpp std::pmr::string`, `#!cpp std::basic_string` with a custom allocator | not usable beyond the DOM, `dump`, and `parse` -- see below |
| `#!cpp std::wstring`, `#!cpp std::u16string`, `#!cpp std::u32string` | not usable; the character type is not one byte wide |
| `absl::Cord` | not usable; no `value_type`, and the storage is not contiguous |
!!! warning "`std::basic_string` with a non-default allocator"
In several places the library builds a `#!cpp std::string` and assigns it to a `string_t`: `int_to_string()` (used
by [`flatten`](../../api/basic_json/flatten.md) and [`diff`](../../api/basic_json/diff.md)) and the UBJSON
high-precision number reader, which every binary reader instantiates. A `#!cpp std::basic_string` with a different
allocator is not assignable from `#!cpp std::string`, and because such a type lives in namespace `std`, the ADL
customization point `int_to_string()` cannot be provided for it either. Only the DOM,
[`dump`](../../api/basic_json/dump.md), and [`parse`](../../api/basic_json/parse.md) compile with such a type.
Wrap it in a class of your own namespace if you need a custom allocator.
## `BooleanType`
`boolean_t` is stored **directly** inside `basic_json`, as a member of an anonymous union.