deploy: 63c10a51fc

api/basic_json/is_discarded/index.md

@@ -47,7 +47,7 @@ After a successful parse, this function always returns `false`: discarded values
 
 ## Examples
 
-Example
+Example: `is_discarded()` for ordinary JSON values
 
 The following code exemplifies `is_discarded()` for all JSON types.
 
@@ -98,6 +98,43 @@ false
 false
 ```
 
+Example: discarded values from parsing
+
+The following code shows the two situations in which a discarded value can be observed: parsing invalid JSON with `allow_exceptions` set to `false`, and a parser callback that discards the top-level value (which is replaced by `null` and therefore does *not* remain discarded).
+
+```
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // parsing invalid JSON without exceptions yields a discarded value
+    json j_invalid = json::parse("[1,2,3", nullptr, false);
+
+    // a callback that discards the top-level value does not leave it
+    // "discarded" -- it is replaced by null instead
+    json j_discarded_by_callback = json::parse("[1,2,3]", [](int /*depth*/, json::parse_event_t event, json& /*parsed*/)
+    {
+        return event != json::parse_event_t::array_start;
+    });
+
+    std::cout << std::boolalpha;
+    std::cout << "j_invalid.is_discarded()               = " << j_invalid.is_discarded() << '\n';
+    std::cout << "j_discarded_by_callback                = " << j_discarded_by_callback << '\n';
+    std::cout << "j_discarded_by_callback.is_discarded() = " << j_discarded_by_callback.is_discarded() << '\n';
+}
+```
+
+Output:
+
+```
+j_invalid.is_discarded()               = true
+j_discarded_by_callback                = null
+j_discarded_by_callback.is_discarded() = false
+```
+
 ## Version history
 
 - Added in version 1.0.0.