amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-02-27 05:46:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Implement support for string_view (attempt no. 3) (#3423)

Browse Source 
* Add key_compare member to ordered_map

* Replace == with key_compare in ordered_map

* Expose the actual comparison function used by object_t

nlohmann::ordered_map uses a different comparison function than the one
provided via template parameter.
* Introduce a type trait to detect if object_t has a key_compare member.
* Rename object_comparator_t to default_object_comparator_t.
* Add object_comparator_t to be conditionally defined as
  object_t::key_compare, if available, or default_object_comparator_t
  otherwise.
* Update the documentation accordingly.

Co-authored-by: Niels Lohmann <niels.lohmann@gmail.com>

* Add type traits to check if a type is usable as object key

Add type trait to check:
* if a type is a specialization of a template.
* if a type is a json_pointer.
* if a type is a basic_json::{const_,}iterator.
* if two types are comparable using a given comparison functor.
* if a type is comparable to basic_json::object_t::key_type.
* if a type has a member type is_transparent.
* if a type is usable as object key.
* if a type has an erase() function accepting a given KeyType.

Co-authored-by: Niels Lohmann <niels.lohmann@gmail.com>

* Rework basic_json element access to accept more key types

Rework basic_json element access member functions and operators to
accept any type that meets the requirements defined by type trait
detail::is_usable_as_key_type.

Member functions and operators:
* at()
* operator[]
* value()
* erase()
* find()
* count()
* contains()

Update documentation to reflect these changes.

Add unit tests to excercise the new functions using std::string_view.

Co-authored-by: Niels Lohmann <niels.lohmann@gmail.com>

Co-authored-by: Niels Lohmann <niels.lohmann@gmail.com>
This commit is contained in:
Florian Albrechtskirchinger
2022-04-29 21:40:02 +02:00
committed by GitHub
parent ee51661481
commit 5352856f04
26 changed files with 1517 additions and 305 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
doc/mkdocs/docs/api/basic_json/at.md
View File

@@ -10,13 +10,28 @@ reference at(const typename object_t::key_type& key);
const_reference at(const typename object_t::key_type& key) const;
// (3)
template<typename KeyType>
reference at(KeyType&& key);
template<typename KeyType>
const_reference at(KeyType&& key) const;
// (4)
reference at(const json_pointer& ptr);
const_reference at(const json_pointer& ptr) const;
```
1. Returns a reference to the array element at specified location `idx`, with bounds checking.
2. Returns a reference to the object element at with specified key `key`, with bounds checking.
3. Returns a reference to the element at with specified JSON pointer `ptr`, with bounds checking.
2. Returns a reference to the object element with specified key `key`, with bounds checking.
3. See 2. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
`#!cpp typename object_comparator_t::is_transparent` denotes a type.
4. Returns a reference to the element at specified JSON pointer `ptr`, with bounds checking.
## Template parameters
`KeyType`
: A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with
[`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md).
This can also be a string view (C++17).
## Parameters
@@ -25,15 +40,16 @@ const_reference at(const json_pointer& ptr) const;
`key` (in)
: object key of the elements to access
`ptr` (in)
: JSON pointer to the desired element
## Return value
1. reference to the element at index `idx`
2. reference to the element at key `key`
3. reference to the element pointed to by `ptr`
3. reference to the element at key `key`
4. reference to the element pointed to by `ptr`
## Exception safety
@@ -51,7 +67,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
in this case, calling `at` with a key makes no sense. See example below.
- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is not
stored in the object; that is, `find(key) == end()`. See example below.
3. The function can throw the following exceptions:
3. See 2.
4. The function can throw the following exceptions:
- Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
JSON pointer `ptr` begins with '0'. See example below.
- Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed
@@ -68,9 +85,10 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Complexity
1. Constant
1. Constant.
2. Logarithmic in the size of the container.
3. Constant
3. Logarithmic in the size of the container.
4. Logarithmic in the size of the container.
## Examples
@@ -134,7 +152,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at__object_t_key_type_const.output"
```
??? example "Example (3) access specified element via JSON Pointer"
??? example "Example (4) access specified element via JSON Pointer"
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
@@ -149,7 +167,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/at_json_pointer.output"
```
??? example "Example (3) access specified element via JSON Pointer"
??? example "Example (4) access specified element via JSON Pointer"
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
@@ -173,4 +191,5 @@ Strong exception safety: if an exception occurs, the original value stays intact
1. Added in version 1.0.0.
2. Added in version 1.0.0.
3. Added in version 2.0.0.
3. Added in version 3.11.0.
4. Added in version 2.0.0.

10
doc/mkdocs/docs/api/basic_json/basic_json.md
View File

@@ -201,16 +201,16 @@ basic_json(basic_json&& other) noexcept;
## Exceptions
1. /
1. (none)
2. The function does not throw exceptions.
3. /
4. /
3. (none)
4. (none)
5. The function can throw the following exceptions:
- Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301) if `type_deduction` is
`#!cpp false`, `manual_type` is `value_t::object`, but `init` contains an element which is not a pair whose first
element is a string. In this case, the constructor could not create an object. If `type_deduction` would have been
`#!cpp true`, an array would have been created. See `object(initializer_list_t)` for an example.
6. /
6. (none)
7. The function can throw the following exceptions:
- Throws [`invalid_iterator.201`](../../home/exceptions.md#jsonexceptioninvalid_iterator201) if iterators `first`
and `last` are not compatible (i.e., do not belong to the same JSON value). In this case, the range
@@ -220,7 +220,7 @@ basic_json(basic_json&& other) noexcept;
element anymore. In this case, the range `[first, last)` is undefined. See example code below.
- Throws [`invalid_iterator.206`](../../home/exceptions.md#jsonexceptioninvalid_iterator206) if iterators `first`
and `last` belong to a `#!json null` value. In this case, the range `[first, last)` is undefined.
8. /
8. (none)
9. The function does not throw exceptions.
## Complexity

32
doc/mkdocs/docs/api/basic_json/contains.md
View File

@@ -2,21 +2,28 @@
```cpp
// (1)
template<typename KeyT>
bool contains(KeyT && key) const;
bool contains(const typename object_t::key_type& key) const;
// (2)
template<typename KeyType>
bool contains(KeyType&& key) const;
// (3)
bool contains(const json_pointer& ptr) const;
```
1. Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the
1. Check whether an element exists in a JSON object with a key equivalent to `key`. If the element is not found or the
JSON value is not an object, `#!cpp false` is returned.
2. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value.
2. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
`#!cpp typename object_comparator_t::is_transparent` denotes a type.
3. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value.
## Template parameters
`KeyT`
: A type for an object key other than `basic_json::json_pointer`.
`KeyType`
: A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with
[`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md).
This can also be a string view (C++17).
## Parameters
@@ -30,7 +37,8 @@ bool contains(const json_pointer& ptr) const;
1. `#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value
is not an object, `#!cpp false` is returned.
2. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise.
2. See 1.
3. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise.
## Exception safety
@@ -39,7 +47,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Exceptions
1. The function does not throw exceptions.
2. The function can throw the following exceptions:
2. The function does not throw exceptions.
3. The function can throw the following exceptions:
- Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index begins with
`0`.
- Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index was not a
@@ -74,7 +83,7 @@ Logarithmic in the size of the JSON object.
--8<-- "examples/contains.output"
```
??? example "Example (1) check with JSON pointer"
??? example "Example (3) check with JSON pointer"
The example shows how `contains()` is used.
@@ -90,5 +99,6 @@ Logarithmic in the size of the JSON object.
## Version history
1. Added in version 3.6.0.
2. Added in version 3.7.0.
1. Added in version 3.11.0.
2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0.
3. Added in version 3.7.0.

23
doc/mkdocs/docs/api/basic_json/count.md
View File

@@ -1,17 +1,25 @@
# <small>nlohmann::basic_json::</small>count
```cpp
template<typename KeyT>
size_type count(KeyT&& key) const;
// (1)
size_type count(const typename object_t::key_type& key) const;
// (2)
template<typename KeyType>
size_type count(KeyType&& key) const;
```
Returns the number of elements with key `key`. If `ObjectType` is the default `std::map` type, the return value will
always be `0` (`key` was not found) or `1` (`key` was found).
1. Returns the number of elements with key `key`. If `ObjectType` is the default `std::map` type, the return value will
always be `0` (`key` was not found) or `1` (`key` was found).
2. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
`#!cpp typename object_comparator_t::is_transparent` denotes a type.
## Template parameters
`KeyT`
: A type for an object key.
`KeyType`
: A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with
[`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md).
This can also be a string view (C++17).
## Parameters
@@ -52,4 +60,5 @@ This method always returns `0` when executed on a JSON type that is not an objec
## Version history
- Added in version 1.0.0.
1. Added in version 3.11.0.
2. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0.

19
doc/mkdocs/docs/api/basic_json/default_object_comparator_t.md Normal file
View File

@@ -0,0 +1,19 @@
# <small>nlohmann::basic_json::</small>default_object_comparator_t
```cpp
using default_object_comparator_t = std::less<StringType>; // until C++14
using default_object_comparator_t = std::less<>; // since C++14
```
The default comparator used by [`object_t`](object_t.md).
Since C++14 a transparent comparator is used which prevents unnecessary string construction
when looking up a key in an object.
The actual comparator used depends on [`object_t`](object_t.md) and can be obtained via
[`object_comparator_t`](object_comparator_t.md).
## Version history
- Added in version 3.11.0.

39
doc/mkdocs/docs/api/basic_json/erase.md
View File

@@ -13,6 +13,10 @@ const_iterator erase(const_iterator first, const_iterator last);
size_type erase(const typename object_t::key_type& key);
// (4)
template<typename KeyType>
size_type erase(KeyType&& key);
// (5)
void erase(const size_type idx);
```
@@ -29,7 +33,17 @@ void erase(const size_type idx);
3. Removes an element from a JSON object by key.
4. Removes an element from a JSON array by index.
4. See 3. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
`#!cpp typename object_comparator_t::is_transparent` denotes a type.
5. Removes an element from a JSON array by index.
## Template parameters
`KeyType`
: A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with
[`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md).
This can also be a string view (C++17).
## Parameters
@@ -56,7 +70,8 @@ void erase(const size_type idx);
is returned.
3. Number of elements removed. If `ObjectType` is the default `std::map` type, the return value will always be `0`
(`key` was not found) or `1` (`key` was found).
4. /
4. See 3.
5. (none)
## Exception safety
@@ -83,7 +98,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
3. The function can throw the following exceptions:
- Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
JSON object; example: `"cannot use erase() with null"`
4. The function can throw the following exceptions:
4. See 3.
5. The function can throw the following exceptions:
- Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) when called on a type other than
JSON object; example: `"cannot use erase() with null"`
- Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example:
@@ -103,14 +119,16 @@ Strong exception safety: if an exception occurs, the original value stays intact
- strings and binary: linear in the length of the member
- other types: constant
3. `log(size()) + count(key)`
4. Linear in distance between `idx` and the end of the container.
4. `log(size()) + count(key)`
5. Linear in distance between `idx` and the end of the container.
## Notes
1. Invalidates iterators and references at or after the point of the `erase`, including the `end()` iterator.
2. /
2. (none)
3. References and iterators to the erased elements are invalidated. Other references and iterators are not affected.
4. /
4. See 3.
5. (none)
## Examples
@@ -156,7 +174,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/erase__key_type.output"
```
??? example "Example: (4) remove element from a JSON array given an index"
??? example "Example: (5) remove element from a JSON array given an index"
The example shows the effect of `erase()` using an array index.
@@ -172,5 +190,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Version history
- Added in version 1.0.0.
- Added support for binary types in version 3.8.0.
1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
2. Added in version 1.0.0. Added support for binary types in version 3.8.0.
3. Added in version 1.0.0.
4. Added in version 3.11.0.
5. Added in version 1.0.0.

31
doc/mkdocs/docs/api/basic_json/find.md
View File

@@ -1,20 +1,28 @@
# <small>nlohmann::basic_json::</small>find
```cpp
template<typename KeyT>
iterator find(KeyT&& key);
// (1)
iterator find(const typename object_t::key_type& key);
const_iterator find(const typename object_t::key_type& key) const;
template<typename KeyT>
const_iterator find(KeyT&& key) const;
// (2)
template<typename KeyType>
iterator find(KeyType&& key);
template<typename KeyType>
const_iterator find(KeyType&& key) const;
```
Finds an element in a JSON object with key equivalent to `key`. If the element is not found or the JSON value is not an
object, `end()` is returned.
1. Finds an element in a JSON object with a key equivalent to `key`. If the element is not found or the
JSON value is not an object, `end()` is returned.
2. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
`#!cpp typename object_comparator_t::is_transparent` denotes a type.
## Template parameters
`KeyT`
: A type for an object key.
`KeyType`
: A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with
[`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md).
This can also be a string view (C++17).
## Parameters
@@ -23,8 +31,8 @@ object, `end()` is returned.
## Return value
Iterator to an element with key equivalent to `key`. If no such element is found or the JSON value is not an object,
past-the-end (see `end()`) iterator is returned.
Iterator to an element with a key equivalent to `key`. If no such element is found or the JSON value is not an object,
a past-the-end iterator (see `end()`) is returned.
## Exception safety
@@ -60,4 +68,5 @@ This method always returns `end()` when executed on a JSON type that is not an o
## Version history
- Added in version 1.0.0.
1. Added in version 3.11.0.
2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0.

1
doc/mkdocs/docs/api/basic_json/index.md
View File

@@ -128,6 +128,7 @@ The class satisfies the following concept requirements:
- [**array_t**](array_t.md) - type for arrays
- [**binary_t**](binary_t.md) - type for binary arrays
- [**boolean_t**](boolean_t.md) - type for booleans
- [**default_object_comparator_t**](default_object_comparator_t.md) - default comparator for objects
- [**number_float_t**](number_float_t.md) - type for numbers (floating-point)
- [**number_integer_t**](number_integer_t.md) - type for numbers (integer)
- [**number_unsigned_t**](number_unsigned_t.md) - type for numbers (unsigned)

2
doc/mkdocs/docs/api/basic_json/insert.md
View File

@@ -50,7 +50,7 @@ void insert(const_iterator first, const_iterator last);
2. iterator pointing to the first element inserted, or `pos` if `#!cpp cnt==0`
3. iterator pointing to the first element inserted, or `pos` if `#!cpp first==last`
4. iterator pointing to the first element inserted, or `pos` if `ilist` is empty
5. /
5. (none)
## Exception safety

16
doc/mkdocs/docs/api/basic_json/object_comparator_t.md
View File

@@ -1,16 +1,16 @@
# <small>nlohmann::basic_json::</small>object_comparator_t
```cpp
using object_comparator_t = std::less<StringType>; // until C++14
using object_comparator_t = std::less<>; // since C++14
```cpp
using object_comparator_t = typename object_t::key_compare;
// or
using object_comparator_t = default_object_comparator_t;
```
The comparator used in [`object_t`](object_t.md).
When C++14 is detected, a transparent comparator is used which, when combined with perfect forwarding on find() and
count() calls, prevents unnecessary string construction.
The comparator used by [`object_t`](object_t.md). Defined as `#!cpp typename object_t::key_compare` if available,
and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.
## Version history
- Unknown.
- Added in version 3.0.0.
- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in version 3.11.0.

4
doc/mkdocs/docs/api/basic_json/object_t.md
View File

@@ -3,7 +3,7 @@
```cpp
using object_t = ObjectType<StringType,
basic_json,
object_comparator_t,
default_object_comparator_t,
AllocatorType<std::pair<const StringType, basic_json>>>;
```
@@ -52,7 +52,7 @@ std::map<
>
```
See [`object_comparator_t`](object_comparator_t.md) for more information.
See [`default_object_comparator_t`](default_object_comparator_t.md) for more information.
#### Behavior

52
doc/mkdocs/docs/api/basic_json/operator[].md
View File

@@ -6,26 +6,32 @@ reference operator[](size_type idx);
const_reference operator[](size_type idx) const;
// (2)
reference operator[](const typename object_t::key_type& key);
reference operator[](typename object_t::key_type key);
const_reference operator[](const typename object_t::key_type& key) const;
template<typename T>
reference operator[](T* key);
template<typename T>
const_reference operator[](T* key) const;
// (3)
template<typename KeyType>
reference operator[](KeyType&& key);
template<typename KeyType>
const_reference operator[](KeyType&& key) const;
// (4)
reference operator[](const json_pointer& ptr);
const_reference operator[](const json_pointer& ptr) const;
```
1. Returns a reference to the array element at specified location `idx`.
2. Returns a reference to the object element at with specified key `key`.
3. Returns a reference to the element at with specified JSON pointer `ptr`.
2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by value.
3. See 2. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
`#!cpp typename object_comparator_t::is_transparent` denotes a type.
4. Returns a reference to the element with specified JSON pointer `ptr`.
## Template parameters
`T`
: string literal convertible to `object_t::key_type`
`KeyType`
: A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with
[`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md).
This can also be a string view (C++17).
## Parameters
@@ -40,9 +46,10 @@ const_reference operator[](const json_pointer& ptr) const;
## Return value
1. reference to the element at index `idx`
2. reference to the element at key `key`
3. reference to the element pointed to by `ptr`
1. (const) reference to the element at index `idx`
2. (const) reference to the element at key `key`
3. (const) reference to the element at key `key`
4. (const) reference to the element pointed to by `ptr`
## Exception safety
@@ -56,7 +63,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
2. The function can throw the following exceptions:
- Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an object
or null; in that case, using the `[]` operator with a key makes no sense.
3. The function can throw the following exceptions:
3. See 2.
4. The function can throw the following exceptions:
- Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
JSON pointer `ptr` begins with '0'.
- Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed
@@ -70,7 +78,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
2. Logarithmic in the size of the container.
3. Constant
3. Logarithmic in the size of the container.
4. Logarithmic in the size of the container.
## Notes
@@ -87,7 +96,9 @@ Strong exception safety: if an exception occurs, the original value stays intact
2. If `key` is not found in the object, then it is silently added to the object and filled with a `#!json null` value to
make `key` a valid reference. In case the value was `#!json null` before, it is converted to an object.
3. `null` values are created in arrays and objects if necessary.
3. See 2.
4. `null` values are created in arrays and objects if necessary.
In particular:
@@ -143,7 +154,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorarray__key_type.output"
```
??? example "Example (2): access specified object element"
??? example "Example (2): access specified object element (const)"
The example below shows how object elements can be read using the `[]` operator.
@@ -157,7 +168,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorarray__key_type_const.output"
```
??? example "Example (3): access specified element via JSON Pointer"
??? example "Example (4): access specified element via JSON Pointer"
The example below shows how values can be read and written using JSON Pointers.
@@ -171,7 +182,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
--8<-- "examples/operatorjson_pointer.output"
```
??? example "Example (3): access specified element via JSON Pointer"
??? example "Example (4): access specified element via JSON Pointer (const)"
The example below shows how values can be read using JSON Pointers.
@@ -193,5 +204,6 @@ Strong exception safety: if an exception occurs, the original value stays intact
## Version history
1. Added in version 1.0.0.
2. Added in version 1.0.0. Overloads for `T* key` added in version 1.1.0.
3. Added in version 2.0.0.
2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) in version 3.11.0.
3. Added in version 3.11.0.
4. Added in version 2.0.0.

2
doc/mkdocs/docs/api/basic_json/to_bson.md
View File

@@ -28,7 +28,7 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
## Return value
1. BSON serialization as byte vector
2. /
2. (none)
## Exception safety

2
doc/mkdocs/docs/api/basic_json/to_cbor.md
View File

@@ -29,7 +29,7 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
## Return value
1. CBOR serialization as byte vector
2. /
2. (none)
## Exception safety

2
doc/mkdocs/docs/api/basic_json/to_msgpack.md
View File

@@ -28,7 +28,7 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
## Return value
1. MessagePack serialization as byte vector
2. /
2. (none)
## Exception safety

2
doc/mkdocs/docs/api/basic_json/to_ubjson.md
View File

@@ -39,7 +39,7 @@ The exact mapping and its limitations is described on a [dedicated page](../../f
## Return value
1. UBJSON serialization as byte vector
2. /
2. (none)
## Exception safety

32
doc/mkdocs/docs/api/basic_json/value.md
View File

@@ -4,9 +4,14 @@
// (1)
template<class ValueType>
ValueType value(const typename object_t::key_type& key,
const ValueType& default_value) const;
ValueType&& default_value) const;
// (2)
template<class KeyType, class ValueType>
ValueType value(KeyType&& key,
ValueType&& default_value) const;
// (3)
template<class ValueType>
ValueType value(const json_pointer& ptr,
const ValueType& default_value) const;
@@ -24,7 +29,10 @@ ValueType value(const json_pointer& ptr,
}
```
2. Returns either a copy of an object's element at the specified JSON pointer `ptr` or a given default value if no value
2. See 1. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
`#!cpp typename object_comparator_t::is_transparent` denotes a type.
3. Returns either a copy of an object's element at the specified JSON pointer `ptr` or a given default value if no value
at `ptr` exists.
The function is basically equivalent to executing
@@ -44,6 +52,10 @@ ValueType value(const json_pointer& ptr,
## Template parameters
`KeyType`
: A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with
[`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md).
This can also be a string view (C++17).
`ValueType`
: type compatible to JSON values, for instance `#!cpp int` for JSON integer numbers, `#!cpp bool` for JSON booleans,
or `#!cpp std::vector` types for JSON arrays. Note the type of the expected value at `key`/`ptr` and the default
@@ -55,7 +67,7 @@ ValueType value(const json_pointer& ptr,
: key of the element to access
`default_value` (in)
: the value to return if key/ptr found no value
: the value to return if `key`/`ptr` found no value
`ptr` (in)
: a JSON pointer to the element to access
@@ -63,7 +75,8 @@ ValueType value(const json_pointer& ptr,
## Return value
1. copy of the element at key `key` or `default_value` if `key` is not found
1. copy of the element at JSON Pointer `ptr` or `default_value` if no value for `ptr` is found
2. copy of the element at key `key` or `default_value` if `key` is not found
3. copy of the element at JSON Pointer `ptr` or `default_value` if no value for `ptr` is found
## Exception safety
@@ -77,7 +90,8 @@ changes to any JSON value.
the type of the value at `key`
- Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
in that case, using `value()` with a key makes no sense.
2. The function can throw the following exceptions:
2. See 1.
3. The function can throw the following exceptions:
- Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
the type of the value at `ptr`
- Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
@@ -87,6 +101,7 @@ changes to any JSON value.
1. Logarithmic in the size of the container.
2. Logarithmic in the size of the container.
3. Logarithmic in the size of the container.
## Examples
@@ -104,7 +119,7 @@ changes to any JSON value.
--8<-- "examples/basic_json__value.output"
```
??? example "Example (2): access specified object element via JSON Pointer with default value"
??? example "Example (3): access specified object element via JSON Pointer with default value"
The example below shows how object elements can be queried with a default value.
@@ -125,5 +140,6 @@ changes to any JSON value.
## Version history
1. Added in version 1.0.0.
2. Added in version 2.0.2.
1. Added in version 1.0.0. Changed parameter `default_value` type from `const ValueType&` to `ValueType&&` in version 3.11.0.
2. Added in version 3.11.0.
3. Added in version 2.0.2.