json/docs/mkdocs/docs/api/basic_json_view/get.md

nlohmann::basic_json_view::get

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>())
• #!cpp std::nullptr_t
• #!cpp std::basic_string<char, Traits, Alloc> (including string_t) — a copy of the string
• string_view_t — no copy: the returned view points into the document's source() text, or, for a string that contains escape sequences, into the document's own buffer of decoded strings (see get_string())
• BasicJsonType — equivalent to materialize()
• basic_json_view — returns #!cpp *this
• #!cpp std::vector<U, A> of the types above — 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, basic_json_view, C, A> and #!cpp std::unordered_map<K, basic_json_view, H, E, A>, if K is constructible from a #!cpp (const char*, std::size_t) pair — views of the members of an object; with a repeated key, the view of the last member is kept, as BasicJsonType::parse() keeps its value

A default-constructible T whose from_json() accepts views reads the view directly as well, without building a BasicJsonType value. This covers the library's own conversions of the standard library types — all other #!cpp std::vectors, #!cpp std::map/#!cpp std::unordered_map (also with other key types), #!cpp std::list, #!cpp std::deque, #!cpp std::set, #!cpp std::forward_list, #!cpp std::valarray, #!cpp std::array, C arrays, #!cpp std::pair, #!cpp std::tuple, #!cpp std::optional, enumerations, #!cpp std::filesystem::path, ... -- which give the same values as #!cpp materialize().get<T>() (from an object, a repeated key keeps the last value, as BasicJsonType::parse() does), as well as the types of the NLOHMANN_DEFINE_TYPE_* and NLOHMANN_DEFINE_DERIVED_TYPE_* macros and the enumerations of NLOHMANN_JSON_SERIALIZE_ENUM, and any from_json() constrained to accept views, e.g. with is_json_view. A from_json() that also accepts types that are no JSON values at all, such as the unconstrained #!cpp template<typename BasicJsonType> void from_json(const BasicJsonType&, T&) of arbitrary type conversions, is not called with a view: it may use BasicJsonType functions a view does not have. See Writing generic code.

!!! warning "Duplicate keys"

Such a `from_json()` looks members up in the view, where a repeated key finds the **first** member, while
`#!cpp materialize().get<T>()` sees the **last** one, as [`BasicJsonType::parse()`](../basic_json/parse.md)
keeps it: for `#!cpp {"x":1,"x":2}`, `#!cpp get<point>()` reads `#!cpp x == 1`. See
[Duplicate keys](../../features/json_view.md#duplicate-keys).

Every other T — user types whose from_json() is written for BasicJsonType only, types without a default constructor, #!cpp std::tuples holding references, ... — is converted by #!cpp materialize().get<T>(): the subtree is built into a real BasicJsonType value first (as BasicJsonType::parse() would), and converted from there exactly as BasicJsonType::get<T>() 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 if the value's type does not match T — the same exception, with the same message, that BasicJsonType::get<T>() 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 of views: throws type_error.302 if the value is not an object.
• For a T whose from_json() reads the view: whatever that from_json() throws; for the library's conversions and the macros, the same exceptions with the same messages as BasicJsonType::get<T>() of the same value.
• For every other T: whatever materialize().get<T>() throws — typically type_error.302, or whatever a user-provided from_json() throws.

The exceptions thrown directly by this function or by a from_json() that reads the view (the first four bullets above) carry the context of those of BasicJsonType: with JSON_DIAGNOSTICS the JSON Pointer path of the value within the document, and with JSON_DIAGNOSTIC_POSITIONS its bytes in the source text. An exception thrown while converting through materialize() (the last bullet) is thrown by the materialized BasicJsonType value instead: its path is relative to the root of the view's subtree, because materialize() builds only the subtree (with parent pointers), so it is empty if the failing value is the subtree's root itself.

Complexity

• #!cpp bool, arithmetic types, #!cpp std::nullptr_t, string_view_t, 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().
• #!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.
• a T whose from_json() reads the view: the cost of that from_json(); for the macros, linear in the number of members times the cost of a lookup, plus the cost of converting the members.
• every other T: the cost of materialize() and of destroying the BasicJsonType value afterwards, plus that of BasicJsonType::get<T>().

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
--8<-- "examples/basic_json_view__get.cpp"
```

Output:

```json
--8<-- "examples/basic_json_view__get.output"
```

See also

• get_to - convert and write into a passed value
• get_string - the string, without a copy
• number_token - a number's token text, without a copy
• materialize - build the BasicJsonType value of this subtree
• BasicJsonType::get - the corresponding function of basic_json
• Zero-copy JSON views - which conversions avoid building a basic_json value

Version history

• Added in version 3.13.0.