Niels Lohmann
e9c3985f0a
* 📝 Fix documentation gaps found in a full GitHub Discussions review Reviewed all 1008 GitHub Discussions (2020-2026) for recurring questions that better or more visible documentation would have avoided. Adds/expands documentation for ~26 distinct gaps, including: - New "Debugging" page collecting natvis, GDB pretty printer, LLDB status, and JSON_DIAGNOSTICS pointers (previously scattered/undiscoverable) - Thread-safety and schema-validation FAQ entries - StringType's char-based requirement (no wstring/u16string/u32string) - Brace-initialization-yields-arrays warning directly on the constructor reference page (previously only in the FAQ, missed by users reading the constructor docs) - std::any exclusion from get<T>(), with a manual-dispatch example - Non-string-keyed std::map serializing as an array of pairs - ordered_json compatibility with NLOHMANN_DEFINE_TYPE_* macros (already worked, was undocumented) - std::array truncation on size-mismatched conversion (no exception) - static_cast vs. get<std::optional<T>>() divergence - Recipe for omitting a std::optional field instead of emitting null - No built-in nesting-depth limit during parsing + a callback-based workaround recipe - Recipe for streaming a large homogeneous array via parser callbacks - operator>> stream-position semantics for concatenated JSON values - JSON Pointer array-vs-object creation rule for non-existing paths - CMake target name (nlohmann_json_modules) needed to link C++20 modules - ESP-IDF/PlatformIO: no official package, link to a community fork - get(key, default) as the Python dict.get() equivalent - reserve() recipe for pre-allocating array capacity - JSONC as an alias for the existing ignore_comments/ignore_trailing_commas combination (distinct from the unsupported JSON5) - items() dereferenced-element type: decltype() idiom + detail-namespace stability caveat - Various macro/type-conversion limitations (MSGPACK_DEFINE_ARRAY equivalent, char-array round-tripping, ADL serializer macro gap) Signed-off-by: Niels Lohmann <mail@nlohmann.me> * 🎨 fix format Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
117 lines
3.3 KiB
Markdown
117 lines
3.3 KiB
Markdown
# <small>nlohmann::basic_json::</small>items
|
|
|
|
```cpp
|
|
iteration_proxy<iterator> items() noexcept;
|
|
iteration_proxy<const_iterator> items() const noexcept;
|
|
```
|
|
|
|
This function allows accessing `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a
|
|
reference to the JSON values is returned, so there is no access to the underlying iterator.
|
|
|
|
For loop without `items()` function:
|
|
|
|
```cpp
|
|
for (auto it = j_object.begin(); it != j_object.end(); ++it)
|
|
{
|
|
std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
|
|
}
|
|
```
|
|
|
|
Range-based for loop without `items()` function:
|
|
|
|
```cpp
|
|
for (auto it : j_object)
|
|
{
|
|
// "it" is of type json::reference and has no key() member
|
|
std::cout << "value: " << it << '\n';
|
|
}
|
|
```
|
|
|
|
Range-based for loop with `items()` function:
|
|
|
|
```cpp
|
|
for (auto& el : j_object.items())
|
|
{
|
|
std::cout << "key: " << el.key() << ", value:" << el.value() << '\n';
|
|
}
|
|
```
|
|
|
|
The `items()` function also allows using
|
|
[structured bindings](https://en.cppreference.com/w/cpp/language/structured_binding) (C++17):
|
|
|
|
```cpp
|
|
for (auto& [key, val] : j_object.items())
|
|
{
|
|
std::cout << "key: " << key << ", value:" << val << '\n';
|
|
}
|
|
```
|
|
|
|
If you need to name the type of the dereferenced element explicitly (e.g., to write a standalone function that
|
|
takes it as a parameter, or to use `items()` with `std::for_each`), use `decltype`:
|
|
|
|
```cpp
|
|
using element_type = decltype(*j_object.items().begin());
|
|
```
|
|
|
|
The per-element type (`iteration_proxy_value`) lives in the library's internal `detail` namespace and is
|
|
intentionally unspecified as a stable, named type -- `decltype` is the supported way to obtain it, but its exact
|
|
name/definition may change between versions.
|
|
|
|
## Return value
|
|
|
|
iteration proxy object wrapping the current value with an interface to use in range-based for loops
|
|
|
|
## Exception safety
|
|
|
|
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
|
|
|
|
## Complexity
|
|
|
|
Constant.
|
|
|
|
## Notes
|
|
|
|
When iterating over an array, `key()` will return the index of the element as string (see example). For primitive types
|
|
(e.g., numbers), `key()` returns an empty string.
|
|
|
|
!!! danger "Lifetime issues"
|
|
|
|
Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See
|
|
[#2040](https://github.com/nlohmann/json/issues/2040) for more information.
|
|
|
|
## Examples
|
|
|
|
??? example
|
|
|
|
The following code shows an example for `items()`.
|
|
|
|
```cpp
|
|
--8<-- "examples/items.cpp"
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
--8<-- "examples/items.output"
|
|
```
|
|
|
|
## See also
|
|
|
|
- [begin](begin.md) returns an iterator to the first element
|
|
- [end](end.md) returns an iterator to one past the last element
|
|
|
|
## Version history
|
|
|
|
- Added `iterator_wrapper` in version 3.0.0.
|
|
- Added `items` and deprecated `iterator_wrapper` in version 3.1.0.
|
|
- Added structured binding support in version 3.5.0.
|
|
|
|
!!! warning "Deprecation"
|
|
|
|
This function replaces the static function `iterator_wrapper` which was introduced in version 1.0.0, but has been
|
|
deprecated in version 3.1.0. Function `iterator_wrapper` will be removed in version 4.0.0. Please replace all
|
|
occurrences of `#!cpp iterator_wrapper(j)` with `#!cpp j.items()`.
|
|
|
|
You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
|
|
function.
|