Add element access, iteration, values, and JSON pointers to json_view (#5622)

* Add element access, iteration, values, and JSON pointers to json_view Give basic_json_view the read-only access functions of basic_json: operator[] and at() with keys and indices, front()/back(), find(), contains(), count(), begin()/end() and cbegin()/cend(), items() with structured bindings from C++17 on, and type_name(). Exceptions have the ids and messages of the const functions of basic_json. Where basic_json has undefined behavior the view answers safely: operator[] with a missing key or an out-of-range index returns a discarded view, and front()/back() of an empty container throw invalid_iterator.214. Objects are iterated in document order, and all members are visited; duplicate-key lookups find the first member (as yyjson and simdjson do), while parse(), materialize(), and the map conversions keep the last value, as parse() does. Keys of up to 16 bytes are compared with two overlapping loads. Add value conversions: get<T>()/get_to() for arithmetic types, bool, nullptr_t, strings (std::basic_string copied, string_view_t without a copy), BasicJsonType, views, std::vector, and maps with string keys; get_string() for the string without a copy; number_token() for the number exactly as written in the source; value() with keys and JSON pointers; and operator[]/at()/ contains() with JSON pointers. Everything else, including types with from_json(), goes through materialize() of that subtree. get<T>() of arithmetic types is inlined down to the conversion, so reading an integer needs no call. detail::json_pointer_access exposes a pointer's reference tokens to code outside basic_json. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Make view lookups last-wins and chained access safe * Lookups (operator[], at, find, contains, count, value, JSON pointers) return the last member of a duplicate key, as materialize() and parse() keep it. * operator[] on a discarded view returns a discarded view instead of throwing, so v["a"]["b"] is safe for a missing "a". * operator[] and at() take any integer type (not only int and size_t), fixing ambiguous calls with unsigned, long, std::int64_t, ... * Fix the operator[] documentation, which claimed a discarded view for a type mismatch where type_error.305 is thrown. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Replace the removed operator bool of basic_json_view in the header and its tests A view is tested with is_discarded(); the lookups in at(), value() and contains(json_pointer) and the unit tests no longer rely on the explicit conversion to bool. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Use named documents in the json_view tests that called root() on a temporary root() of an rvalue document is deleted, because the views would dangle. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Test discarded views with is_discarded() in the operator[] docs and examples The explicit conversion to bool of basic_json_view is gone. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Return the first member of duplicate keys from lookups again Looking up the last member of a duplicate key cannot stop at a match, so every lookup scanned the whole object (1.6 to 3.4 times slower for small objects). operator[](key), at, find, value, contains, count, and JSON pointer resolution return the first member again, as yyjson and simdjson do; materialize() and get<map>() keep the last value, as parse(). The documentation says so in the feature page and on each lookup page, and explains how to get the value parse() would give. The integer index templates and the discarded chaining of operator[] stay. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Do not force-inline the view's functions on MSVC __forceinline makes MSVC report C4714 for function templates it cannot inline (get<std::string>), an error under /WX. The forced inlining is only a performance hint, so use plain inline there. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Make json_view.hpp pass include-what-you-use Mark the includes that are needed by design (json.hpp, the macro unscope, <tuple> for the tuple_size specialization), take size_t from <cstring>, and drop the forward declaration of basic_json_document that the friend declaration makes redundant. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Avoid GCC useless-cast warnings in the integer index tests Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Make json_view.hpp pass include-what-you-use ci_single_binaries runs IWYU with --error on every header. For json_view.hpp it suggested adding <array> (std::array is used), the headers that json.hpp already provides (abi_config, abi_macros, input_adapters, json_pointer, cpp_future, string_concat, value_t, json_fwd), and <version> for std::nullptr_t, and removing <cstddef>. - include <array> - keep <cstddef> (nullptr_t, size_t; IWYU attributes them to <version> and <cstring>) - tell IWYU not to suggest the headers that json.hpp provides: the amalgamated json_view.hpp only includes json.hpp, so including them here would duplicate their definitions Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix the clang-tidy 22 findings in json_view and its tests The same changes as on the dump branch, where they were first made, so that this branch passes clang-tidy on its own. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Regenerate the amalgamated headers Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Report one-character non-numeric array indices like basic_json in the view Develop's #5800 made basic_json report a JSON pointer array index such as "/a" as parse_error.109 instead of out_of_range.404, as longer ones were; the view's array_index() follows, with "-" and the empty token still unresolved. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Address the review of json_view element access From gregmarr's review of #5622: - count() counts every member with the key, so count(key) > 1 detects duplicate keys; it was contains() as 0/1 before. - get_to() passes types that get<T>() does not convert directly to from_json with the existing value, as basic_json::get_to() does, so that a from_json which sets only the fields present keeps the others. - array_index() checks the empty token and "-" first; the results are unchanged. - Docs: no "if an exception is thrown" where a view never changes anything; the borrowed source must also stay unmodified; items() on a temporary view is safe; back()/front() notes shortened; the basic_json see-also entries say how the view's results can differ. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Regenerate the amalgamated headers Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Count matching keys as unsigned in the json_view access test The conditional added 1 or 0 as int to a std::size_t, which GCC rejects with -Werror=sign-conversion (ci_test_standards_gcc). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Address the second review round of json_view element access From gregmarr's review of #5622: - begin()/end(): "a null value or a discarded view iterates as an empty range", singular like the primitive case before it. - The class page's list of function groups has no trailing commas. - document_data::key_equals() compares a key node with a string, for the key comparisons that were spelled out in each lookup. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Regenerate the amalgamated headers Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Write the negated enable_if conditions of json_view with negation<> With a ! or && in the condition, astyle spaces the whole template header (template < ... >); detail::negation and a named trait keep it compact, as the library writes such conditions elsewhere. From gregmarr's review of #5630. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Regenerate the amalgamated headers Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Keep detail::negation out of json_view.hpp's enable_ifs include-what-you-use asks json_view.hpp to include detail/meta/type_traits.hpp for it, which the single header must not do (the amalgamation would duplicate json's internals). The two conditions of value() go through a trait in value.hpp, like the others. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Regenerate the amalgamated headers Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-25 12:04:42 +00:00 · 2026-10-21 10:21:27 +02:00
1 parent 122d718330
commit 43e97b629b
@@ -0,0 +1,138 @@
+# <small>nlohmann::basic_json_view::</small>value
+
+```cpp
+// (1)
+template<typename T>
+T value(string_view_t key, const T& default_value) const;
+string_t value(string_view_t key, const char* default_value) const;
+
+// (2)
+template<typename T>
+T value(const json_pointer& ptr, const T& default_value) const;
+string_t value(const json_pointer& ptr, const char* default_value) const;
+```
+
+1. Returns the value of the object member with key `key` -- the first one, should the key occur more than once (see
+   [Notes on duplicate keys](operator[].md#notes)) -- converted to `T`, or `default_value` if there is no such member.
+2. Returns the value a JSON pointer `ptr` refers to, starting at this value, converted to `T`, or `default_value` if
+   `ptr` cannot be resolved.
+
+Both overloads have a dedicated `#!cpp const char*` overload, so `#!cpp v.value(key, "default")` (and the JSON pointer
+equivalent) deduce `string_t`, not `const char*`, for their return type and for the comparison used to pick between
+`key` and `default_value`.
+
+## Template parameters
+
+`T`
+:   the type to convert the found value to; also the type of `default_value`
+
+## Parameters
+
+`key` (in)
+:   object key of the element to access
+
+`ptr` (in)
+:   JSON pointer to the element to access
+
+`default_value` (in)
+:   the value to return if `key`/`ptr` resolves to no value
+
+## Return value
+
+1. the first member with key `key`, converted to `T`, or `default_value`
+2. the value `ptr` resolves to, converted to `T`, or `default_value`
+
+## Exception safety
+
+Strong guarantee: there are no changes to the view or the document it refers to.
+
+## Exceptions
+
+1. Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the value is not an object --
+   the same exception, with the same message, that [`BasicJsonType::value`](../basic_json/value.md) throws for the
+   same call. If a member with key `key` is found, throws whatever converting it to `T` throws (typically
+   [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302), with the same message
+   [`BasicJsonType::value`](../basic_json/value.md) throws for the same mismatch); a missing member never throws.
+2. Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if this value -- not the value `ptr`
+   resolves to -- is neither an object nor an array. Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106)
+   or [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if `ptr` contains a malformed array
+   index. If `ptr` resolves to a value, throws whatever converting it to `T` throws. Every other way `ptr` can fail to
+   resolve -- a missing key, an out-of-range or "`-`" array index, an unresolvable token on a primitive -- yields
+   `default_value` instead of throwing, exactly as [`BasicJsonType::value`](../basic_json/value.md) catches
+   `out_of_range` and returns `default_value`.
+
+None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no
+`BasicJsonType` value to point at, so the exception is created without one, even if `BasicJsonType` was built with
+`JSON_DIAGNOSTICS` enabled.
+
+## Complexity
+
+1. Linear in the number of members: as for [`operator[]`](operator[].md#complexity), members are compared one after
+   another, in document order, stopping at the first match. Plus the complexity of converting
+   the found member to `T` (see [`get`](get.md)).
+2. Linear in the number of reference tokens of `ptr` and, for each token, in the number of members of the object at
+   that level or the index into the array -- as for the [`operator[]`](operator[].md#complexity) and
+   [`at`](at.md#complexity) overloads that take a JSON pointer. Plus the complexity of converting the resolved value
+   to `T`.
+
+## Notes
+
+!!! warning "Duplicate keys: the first member wins"
+
+    If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
+    [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
+    `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
+    the last value.
+
+!!! info "Differences to `at` and `operator[]`"
+
+    Unlike [`at`](at.md), this function does not throw if `key`/`ptr` resolves to no value. Unlike
+    [`operator[]`](operator[].md), it never returns a [discarded](is_discarded.md) view -- it always returns a `T` --
+    and it is available on any view, since it never needs to insert a missing element the way the non-const
+    `BasicJsonType::operator[]` would.
+
+!!! info "Which values can be asked"
+
+    As for [`BasicJsonType::value`](../basic_json/value.md), the key overload (1) requires an object, and the JSON
+    pointer overload (2) an object or an array.
+
+## Examples
+
+??? example "Example: (1) access specified object element with default value"
+
+    The example below reads a couple of optional configuration fields with a default, so that a missing key never
+    needs a `#!cpp try`/`#!cpp catch` of its own.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__value.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__value.output"
+    ```
+
+??? example "Example: (2) access specified element via JSON pointer with default value"
+
+    The example below reads an optional, nested configuration value with a default, given as a JSON pointer.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__value_json_pointer.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__value_json_pointer.output"
+    ```
+
+## See also
+
+- [at](at.md) - access specified element with bounds checking (throws instead of returning a default value)
+- [operator[]](operator[].md) - access specified element (returns a discarded view instead of a default value)
+- [`BasicJsonType::value`](../basic_json/value.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.