ceph/src/jaegertracing/opentelemetry-cpp/third_party/nlohmann-json/doc/mkdocs/docs/api/basic_json/items.md

   1 # <small>nlohmann::basic_json::</small>items
   2
   3 ```cpp
   4 iteration_proxy<iterator> items() noexcept;
   5 iteration_proxy<const_iterator> items() const noexcept;
   6 ```
   7
   8 This function allows accessing `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a
   9 reference to the JSON values is returned, so there is no access to the underlying iterator.
  10
  11 For loop without `items()` function:
  12
  13 ```cpp
  14 for (auto it = j_object.begin(); it != j_object.end(); ++it)
  15 {
  16     std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
  17 }
  18 ```
  19
  20 Range-based for loop without `items()` function:
  21
  22 ```cpp
  23 for (auto it : j_object)
  24 {
  25     // "it" is of type json::reference and has no key() member
  26     std::cout << "value: " << it << '\n';
  27 }
  28 ```
  29
  30 Range-based for loop with `items()` function:
  31
  32 ```cpp
  33 for (auto& el : j_object.items())
  34 {
  35     std::cout << "key: " << el.key() << ", value:" << el.value() << '\n';
  36 }
  37 ```
  38
  39 The `items()` function also allows using
  40 [structured bindings](https://en.cppreference.com/w/cpp/language/structured_binding) (C++17):
  41
  42 ```cpp
  43 for (auto& [key, val] : j_object.items())
  44 {
  45     std::cout << "key: " << key << ", value:" << val << '\n';
  46 }
  47 ```
  48
  49 ## Return value
  50
  51 iteration proxy object wrapping the current value with an interface to use in range-based for loops
  52
  53 ## Exception safety
  54
  55 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
  56
  57 ## Complexity
  58
  59 Constant.
  60
  61 ## Notes
  62
  63 When iterating over an array, `key()` will return the index of the element as string (see example). For primitive types
  64 (e.g., numbers), `key()` returns an empty string.
  65
  66 !!! warning
  67
  68     Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See
  69     <https://github.com/nlohmann/json/issues/2040> for more information.
  70
  71 ## Examples
  72
  73 ??? example
  74
  75     The following code shows an example for `items()`.
  76
  77     ```cpp
  78     --8<-- "examples/items.cpp"
  79     ```
  80
  81     Output:
  82
  83     ```json
  84     --8<-- "examples/items.output"
  85     ```
  86
  87 ## Version history
  88
  89 - Added `iterator_wrapper` in version 3.0.0.
  90 - Added `items` and deprecated `iterator_wrapper` in version 3.1.0.
  91 - Added structured binding support in version 3.5.0.
  92
  93 !!! warning "Deprecation"
  94
  95     This function replaces the static function `iterator_wrapper` which was introduced in version 1.0.0, but has been
  96     deprecated in version 3.1.0. Function `iterator_wrapper` will be removed in version 4.0.0. Please replace all
  97     occurrences of `#!cpp iterator_wrapper(j)` with `#!cpp j.items()`.
  98
  99     You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
 100     function.