Niels Lohmann
0660e6d482
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>
2.3 KiB
nlohmann::basic_json_view::begin
iterator begin() const noexcept;
Returns an iterator to the first element of an array, or the first member value of an object, in document order
-- the order the values appear in the source text, not sorted by key. A primitive value iterates as a range of one
element (itself), and a #!json null value or a discarded view iterates as an empty range.
Return value
Iterator to the first element.
Exception safety
No-throw guarantee: this function never throws exceptions.
Complexity
Constant.
Notes
For an object, iteration visits every member, including all occurrences of a duplicate key -- unlike
operator[], at, find, and contains,
which all resolve to the first member with a given key. See the
Notes on duplicate keys of operator[].
Because objects are iterated in document order rather than sorted by key, the order seen here can differ from what
iterating the materialize()d BasicJsonType value would produce: a #!cpp basic_json object
(std::map-backed by default) sorts its keys, while a view does not.
An ordered_json value also keeps document order, but it keeps only one entry per key: as parse() does, it keeps the
last value, at the position of the key's first occurrence. The view, in contrast, visits every member, including
the duplicates.
Examples
??? example
The example below iterates a log record's members with `begin()`/[`end()`](end.md) and prints them in the order
they were written. Materializing the record into a `BasicJsonType` object and iterating that would instead print
the members sorted by key.
```cpp
--8<-- "examples/basic_json_view__begin.cpp"
```
Output:
```json
--8<-- "examples/basic_json_view__begin.output"
```
See also
- end - returns an iterator to one past the last element
- cbegin - returns a const iterator to the first element
- items - access iterator member functions in range-based for
BasicJsonType::begin- the corresponding function ofbasic_json
Version history
- Added in version 3.13.0.