deploy: 4155e2938f
This commit is contained in:
nlohmann committed
1 parent
be4d0a6f4b
commit
90f0c9d411
714 files changed
+22067
-622
No files matched your search
@@ -0,0 +1,191 @@
|
||||
# <small>nlohmann::basic_json_view::</small>get
|
||||
|
||||
```cpp
|
||||
template<typename T>
|
||||
T get() const;
|
||||
```
|
||||
|
||||
Converts the value to `T`.
|
||||
|
||||
For the types below, the conversion works directly on the flat index -- no `BasicJsonType` value is built for it:
|
||||
|
||||
- `#!cpp bool`
|
||||
- arithmetic types other than `#!cpp bool` (for a boolean, `#!cpp 0`/`#!cpp 1`, exactly as for
|
||||
[`BasicJsonType::get<T>()`](../basic_json/get.md))
|
||||
- `#!cpp std::nullptr_t`
|
||||
- `#!cpp std::basic_string<char, Traits, Alloc>` (including `string_t`) -- a copy of the string
|
||||
- [`string_view_t`](index.md#member-types) -- **no copy**: the returned view points into the document's
|
||||
[`source()`](../basic_json_document/source.md) text, or, for a string that contains escape sequences, into the
|
||||
document's own buffer of decoded strings (see [`get_string()`](get_string.md))
|
||||
- `BasicJsonType` -- equivalent to [`materialize()`](materialize.md)
|
||||
- `basic_json_view` -- returns `#!cpp *this`
|
||||
- `#!cpp std::vector<U, A>` -- from an array, element by element, each converted with `#!cpp get<U>()`; `#!cpp
|
||||
std::vector<basic_json_view>` keeps a view of every element instead of a value
|
||||
- `#!cpp std::map<K, V, C, A>` and `#!cpp std::unordered_map<K, V, H, E, A>`, if `K` is constructible from a `#!cpp
|
||||
(const char*, std::size_t)` pair -- from an object, member by member, each value converted with `#!cpp get<V>()`; with a repeated
|
||||
key, the *last* value is kept, as [`BasicJsonType::parse()`](../basic_json/parse.md) (and
|
||||
[`materialize()`](materialize.md)) does; `#!cpp std::map<std::string, basic_json_view>` keeps views of the members
|
||||
instead of values
|
||||
|
||||
Every other `T` -- `#!cpp std::list`, `#!cpp std::pair`, `#!cpp std::array`, enumerations, user types with a
|
||||
`from_json()`, ... -- is converted by `#!cpp materialize().get<T>()`: the subtree is built into a real `BasicJsonType`
|
||||
value first (as [`BasicJsonType::parse()`](../basic_json/parse.md) would), and converted from there exactly as
|
||||
[`BasicJsonType::get<T>()`](../basic_json/get.md) would convert it.
|
||||
|
||||
## Template parameters
|
||||
|
||||
`T`
|
||||
: the type to convert the value to
|
||||
|
||||
## Return value
|
||||
|
||||
the value, converted to `T`
|
||||
|
||||
## Exception safety
|
||||
|
||||
Strong guarantee: there are no changes to the view or the document it refers to.
|
||||
|
||||
## Exceptions
|
||||
|
||||
- For the directly-converted types listed above (other than `BasicJsonType` and `basic_json_view`, which never
|
||||
throw): throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if the value's type does not
|
||||
match `T` -- the same exception, with the same message, that [`BasicJsonType::get<T>()`](../basic_json/get.md)
|
||||
throws for the same JSON type and `T`.
|
||||
- For `#!cpp std::vector<U, A>`: throws `type_error.302` if the value is not an array; otherwise, whatever converting
|
||||
an element to `U` throws.
|
||||
- For `#!cpp std::map`/`#!cpp std::unordered_map`: throws `type_error.302` if the value is not an object; otherwise,
|
||||
whatever converting a member to the mapped type throws.
|
||||
- For every other `T`: whatever [`materialize().get<T>()`](../basic_json/get.md) throws -- typically `type_error.302`,
|
||||
or whatever a user-provided `from_json()` throws.
|
||||
|
||||
None of the exceptions thrown directly by this function (the first three bullets above) carry a
|
||||
[`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no `BasicJsonType` value to point at. An
|
||||
exception thrown while converting through `materialize()` (the last bullet) is different: it is thrown by a real
|
||||
`BasicJsonType` value, so it **does** carry a `JSON_DIAGNOSTICS` path if `BasicJsonType` was built with it enabled.
|
||||
That path is relative to the root of the view's subtree, because `materialize()` builds only the subtree (with parent
|
||||
pointers): it is empty if the failing value is the subtree's root itself, and it never is the path within the whole
|
||||
document.
|
||||
|
||||
## Complexity
|
||||
|
||||
- `#!cpp bool`, arithmetic types, `#!cpp std::nullptr_t`, [`string_view_t`](index.md#member-types), `basic_json_view`:
|
||||
constant.
|
||||
- `#!cpp std::basic_string<char, Traits, Alloc>`: constant, plus one allocation and a copy of the string's bytes.
|
||||
- `BasicJsonType`: linear in the size of the subtree, see [`materialize()`](materialize.md).
|
||||
- `#!cpp std::vector<U, A>`: linear in the number of elements, times the complexity of converting one element to `U`.
|
||||
- `#!cpp std::map`/`#!cpp std::unordered_map`: linear in the number of members for walking them, plus the container's
|
||||
own insertion cost per member (logarithmic for `#!cpp std::map`, amortized constant for `#!cpp
|
||||
std::unordered_map`), times the complexity of converting one member to the mapped type.
|
||||
- every other `T`: the cost of [`materialize()`](materialize.md) and of destroying the `BasicJsonType` value
|
||||
afterwards, plus that of [`BasicJsonType::get<T>()`](../basic_json/get.md).
|
||||
|
||||
## Notes
|
||||
|
||||
!!! info "Floating-point values"
|
||||
|
||||
A floating-point `T` is converted from the same digits the lexer would see during `#!cpp BasicJsonType::parse()`,
|
||||
using the same conversion, so the result is bit-for-bit identical to `#!cpp BasicJsonType::parse(text).get<T>()`
|
||||
for the same source text.
|
||||
|
||||
!!! info "Duplicate keys"
|
||||
|
||||
`#!cpp std::map`/`#!cpp std::unordered_map` conversions keep the *last* value of a repeated key, like
|
||||
[`materialize()`](materialize.md) and [`BasicJsonType::parse()`](../basic_json/parse.md) do. This is the opposite
|
||||
of [`operator[]`](operator[].md)/[`at`](at.md)/[`find`](find.md)/[`contains`](contains.md), which resolve to the
|
||||
*first* occurrence (see the [Notes on duplicate keys](operator[].md#notes)).
|
||||
|
||||
!!! info "No pointers, references, or implicit conversion"
|
||||
|
||||
Unlike `BasicJsonType`, `basic_json_view` has no stored value anywhere to hand out a pointer or a reference to, so
|
||||
it provides neither `#!cpp get_ptr()`, `#!cpp get_ref()`, nor `#!cpp operator ValueType()`.
|
||||
[`get_string()`](get_string.md) (equivalently, `#!cpp get<string_view_t>()`) is the zero-copy alternative for
|
||||
strings.
|
||||
|
||||
## Examples
|
||||
|
||||
??? example
|
||||
|
||||
The example below reads typed fields straight into C++ variables, collects a view of every array element with
|
||||
`#!cpp get<std::vector<basic_json_view>>()` instead of a value, and converts a nested object into a user type
|
||||
through its `from_json()` -- which runs on a `BasicJsonType` value `materialize()` builds for just that one
|
||||
member.
|
||||
|
||||
```cpp
|
||||
#include <iostream>
|
||||
#include <nlohmann/json_view.hpp>
|
||||
#include <string>
|
||||
#include <vector>
|
||||
|
||||
using json_document = nlohmann::json_document;
|
||||
using json_view = nlohmann::json_view;
|
||||
|
||||
// address has no direct conversion in get<T>(), so get<address>() falls back
|
||||
// to materialize().get<address>() -- a real nlohmann::json value is built
|
||||
// for just this one member, and its own from_json() runs on that
|
||||
struct address
|
||||
{
|
||||
std::string city;
|
||||
int zip = 0;
|
||||
};
|
||||
|
||||
void from_json(const nlohmann::json& j, address& a)
|
||||
{
|
||||
j.at("city").get_to(a.city);
|
||||
j.at("zip").get_to(a.zip);
|
||||
}
|
||||
|
||||
int main()
|
||||
{
|
||||
json_document doc = json_document::parse(R"(
|
||||
{
|
||||
"name": "Alice",
|
||||
"active": true,
|
||||
"orders": [1, 2, 3],
|
||||
"address": {"city": "Berlin", "zip": 10115}
|
||||
}
|
||||
)");
|
||||
const json_view customer = doc.root();
|
||||
|
||||
// read typed fields straight into C++ variables -- none of these build
|
||||
// a nlohmann::json value
|
||||
const std::string name = customer["name"].get<std::string>();
|
||||
const bool active = customer["active"].get<bool>();
|
||||
std::cout << name << (active ? " (active)" : " (inactive)") << '\n';
|
||||
|
||||
// std::vector<json_view> keeps views of the array elements instead of
|
||||
// copies of their values
|
||||
bool first = true;
|
||||
for (const json_view order : customer["orders"].get<std::vector<json_view>>())
|
||||
{
|
||||
std::cout << (first ? "" : " ") << order.get<int>();
|
||||
first = false;
|
||||
}
|
||||
std::cout << '\n';
|
||||
|
||||
// everything else goes through materialize()
|
||||
const address a = customer["address"].get<address>();
|
||||
std::cout << a.city << ' ' << a.zip << '\n';
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
Alice (active)
|
||||
1 2 3
|
||||
Berlin 10115
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [get_to](get_to.md) - convert and write into a passed value
|
||||
- [get_string](get_string.md) - the string, without a copy
|
||||
- [number_token](number_token.md) - a number's token text, without a copy
|
||||
- [materialize](materialize.md) - build the `BasicJsonType` value of this subtree
|
||||
- [`BasicJsonType::get`](../basic_json/get.md) - the corresponding function of `basic_json`
|
||||
|
||||
## Version history
|
||||
|
||||
- Added in version 3.13.0.
|
||||
Reference in new issue
Block a user