mirror of
https://github.com/nlohmann/json.git
synced 2026-08-30 13:07:14 +00:00
docs: document the implicit requirements on basic_json's template parameters
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>
This commit is contained in:
co-authored by
Claude Opus 5
parent
35705d79d8
commit
599bb1b68c
@@ -18,7 +18,11 @@ To store objects in C++, a type is defined by the template parameters described
|
||||
## Template parameters
|
||||
|
||||
`ObjectType`
|
||||
: the container to store objects (e.g., `std::map` or `std::unordered_map`)
|
||||
: the container to store objects. Its template parameters must have the same order and meaning as those of
|
||||
`std::map`; in particular, the third parameter is a comparator and the container must provide a `key_compare`
|
||||
member type. `#!cpp std::unordered_map` satisfies neither and cannot be used without a wrapper -- see
|
||||
[Template Parameter Requirements](../../features/types/template_parameters.md#objecttype) for the full list of
|
||||
requirements and a wrapper example.
|
||||
|
||||
`StringType`
|
||||
: the type of the keys or names (e.g., `std::string`). The comparison function `std::less<StringType>` is used to
|
||||
|
||||
Reference in New Issue
Block a user