diff --git a/docs/mkdocs/docs/api/basic_json/index.md b/docs/mkdocs/docs/api/basic_json/index.md index fc934ca93..fdb57105c 100644 --- a/docs/mkdocs/docs/api/basic_json/index.md +++ b/docs/mkdocs/docs/api/basic_json/index.md @@ -109,6 +109,9 @@ The class satisfies the following concept requirements: - **initializer_list_t** - type for initializer lists of `basic_json` values - [**input_format_t**](input_format_t.md) - type to choose the format to parse - [**json_sax_t**](../json_sax/index.md) - type for SAX events +- [**with_object_t, with_array_t, with_string_t, with_boolean_t, with_integers_t, with_float_t, with_allocator_t, + with_json_serializer_t, with_binary_t, with_base_class_t**](with_t.md) - types to create a `basic_json` type with + one (or two) replaced template parameters ### Exceptions diff --git a/docs/mkdocs/docs/api/basic_json/with_t.md b/docs/mkdocs/docs/api/basic_json/with_t.md new file mode 100644 index 000000000..9de825746 --- /dev/null +++ b/docs/mkdocs/docs/api/basic_json/with_t.md @@ -0,0 +1,124 @@ +# nlohmann::basic_json::with_t + +Member alias templates `with_object_t`, `with_array_t`, `with_string_t`, `with_boolean_t`, `with_integers_t`, +`with_float_t`, `with_allocator_t`, `with_json_serializer_t`, `with_binary_t`, and `with_base_class_t`. + +```cpp +template class ObjectType2> +using with_object_t = basic_json; + +template class ArrayType2> +using with_array_t = basic_json; + +template +using with_string_t = basic_json; + +template +using with_boolean_t = basic_json; + +template +using with_integers_t = basic_json; + +template +using with_float_t = basic_json; + +template class AllocatorType2> +using with_allocator_t = basic_json; + +template class JSONSerializer2> +using with_json_serializer_t = basic_json; + +template +using with_binary_t = basic_json; + +template +using with_base_class_t = basic_json; +``` + +These member alias templates make it easier to create a `basic_json` type that is identical to the current type except +for one (or, in the case of `with_integers_t`, two) of its [template parameters](index.md#template-parameters). +Spelling out all 11 template parameters of `basic_json` just to change a single one is verbose and error-prone; these +aliases only require the replacement type(s). + +with_object_t<ObjectType2> +: replaces `ObjectType` + +with_array_t<ArrayType2> +: replaces `ArrayType` + +with_string_t<StringType2> +: replaces `StringType` + +with_boolean_t<BooleanType2> +: replaces `BooleanType` + +with_integers_t<NumberIntegerType2, NumberUnsignedType2> +: replaces both `NumberIntegerType` and `NumberUnsignedType`; the two are combined into a single alias because they + are usually changed together (for instance, when switching to fixed-width integer types) + +with_float_t<NumberFloatType2> +: replaces `NumberFloatType` + +with_allocator_t<AllocatorType2> +: replaces `AllocatorType` + +with_json_serializer_t<JSONSerializer2> +: replaces `JSONSerializer` + +with_binary_t<BinaryType2> +: replaces `BinaryType` + +with_base_class_t<CustomBaseClass2> +: replaces `CustomBaseClass`; see also [`json_base_class_t`](json_base_class_t.md) + +## Notes + +All other template parameters are kept unchanged, so the resulting type still uses, for instance, the same +`ObjectType` unless `with_object_t` itself is used. + +## Examples + +??? example + + The following code shows how `with_object_t` can be used to create a JSON type that stores object elements in a + `std::map` and therefore keeps them sorted by key, unlike the default type which preserves insertion order + only when `nlohmann::ordered_json` is used. + + ```cpp + --8<-- "examples/with_t.cpp" + ``` + + Output: + + ```json + --8<-- "examples/with_t.output" + ``` + +## See also + +- [basic_json](index.md#template-parameters) - the template parameters that can be replaced +- [json_base_class_t](json_base_class_t.md) - the type used for `CustomBaseClass` + +## Version history + +- Added in version 3.13.0. diff --git a/docs/mkdocs/docs/examples/with_t.cpp b/docs/mkdocs/docs/examples/with_t.cpp new file mode 100644 index 000000000..665efde3e --- /dev/null +++ b/docs/mkdocs/docs/examples/with_t.cpp @@ -0,0 +1,18 @@ +#include +#include +#include + +// a JSON type that stores objects in a std::map (which keeps keys sorted) +// instead of the default ordered associative container +using sorted_json = nlohmann::json::with_object_t; + +int main() +{ + sorted_json j; + j["c"] = 1; + j["a"] = 2; + j["b"] = 3; + + // keys are sorted, because std::map is used to store the object + std::cout << j.dump() << std::endl; +} diff --git a/docs/mkdocs/docs/examples/with_t.output b/docs/mkdocs/docs/examples/with_t.output new file mode 100644 index 000000000..0886cda01 --- /dev/null +++ b/docs/mkdocs/docs/examples/with_t.output @@ -0,0 +1 @@ +{"a":2,"b":3,"c":1} diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml index e2e234929..53ea4d19e 100644 --- a/docs/mkdocs/mkdocs.yml +++ b/docs/mkdocs/mkdocs.yml @@ -232,6 +232,7 @@ nav: - 'update': api/basic_json/update.md - 'value': api/basic_json/value.md - 'value_t': api/basic_json/value_t.md +- 'with_t': api/basic_json/with_t.md - byte_container_with_subtype: - 'Overview': api/byte_container_with_subtype/index.md - '(constructor)': api/byte_container_with_subtype/byte_container_with_subtype.md