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

   1 # <small>nlohmann::basic_json::</small>is_discarded
   2
   3 ```cpp
   4 constexpr bool is_discarded() const noexcept;
   5 ```
   6
   7 This function returns `#!cpp true` for a JSON value if either:
   8
   9 - the value was discarded during parsing with a callback function (see [`parser_callback_t`](parser_callback_t.md)), or
  10 - the value is the result of parsing invalid JSON with parameter `allow_exceptions` set to `#!cpp false`; see
  11   [`parse`](parse.md) for more information.
  12
  13 ## Return value
  14
  15 `#!cpp true` if type is discarded, `#!cpp false` otherwise.
  16
  17 ## Exception safety
  18
  19 No-throw guarantee: this member function never throws exceptions.
  20
  21 ## Complexity
  22
  23 Constant.
  24
  25 ## Notes
  26
  27 !!! note
  28
  29     Discarded values are never compared equal with [`operator==`](operator_eq.md). That is, checking whether a JSON
  30     value `j` is discarded will only work via:
  31
  32     ```cpp
  33     j.is_discarded()
  34     ```
  35
  36     because
  37
  38     ```cpp
  39     j == json::value_t::discarded
  40     ```
  41
  42     will always be `#!cpp false`.
  43
  44 !!! note
  45
  46     When a value is discarded by a callback function (see [`parser_callback_t`](parser_callback_t.md)) during parsing,
  47     then it is removed when it is part of a structured value. For instance, if the second value of an array is discared,
  48     instead of `#!json [null, discarded, false]`, the array `#!json [null, false]` is returned. Only if the top-level
  49     value is discarded, the return value of the `parse` call is discarded.
  50
  51 This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur
  52 during parsing, but will be removed when inside a structured value or replaced by null in other cases.
  53
  54 ## Examples
  55
  56 ??? example
  57
  58     The following code exemplifies `is_discarded()` for all JSON types.
  59
  60     ```cpp
  61     --8<-- "examples/is_discarded.cpp"
  62     ```
  63
  64     Output:
  65
  66     ```json
  67     --8<-- "examples/is_discarded.output"
  68     ```
  69
  70 ## Version history
  71
  72 - Added in version 1.0.0.