deploy: e9c3985f0a

features/parsing/parser_callbacks/index.md

@@ -53,6 +53,10 @@ these calls are made to the callback function:
 | `array_end`    | 1     | `[52.519444,13.406667]`                              |
 | `object_end`   | 0     | `{"location":[52.519444,13.406667],"name":"Berlin"}` |
 
+No built-in nesting depth limit
+
+The library has no built-in limit on recursion/nesting depth while parsing. A parser callback can only *discard* content it has already parsed (by returning `false`); it cannot make parsing fail once a nesting limit is exceeded partway through reading a deeply nested value. If you need to reject over-deep untrusted input outright, track `depth` in a callback and `throw` from it once your limit is exceeded (a thrown exception propagates out of `parse()` as usual).
+
 ## Return value
 
 Discarding a value (i.e., returning `false`) has different effects depending on the context in which the function was called:
@@ -237,3 +241,44 @@ This approach has two limitations:
 - The thrown exception cannot carry a `parse_error`-style byte offset, because position tracking only exists inside the parser and lexer, not at the callback layer.
 
 For strict validation with precise error positions, implementing a [SAX interface](https://json.nlohmann.me/features/parsing/sax_interface/index.md) instead gives access to the parser's position information directly.
+
+## Recipe: streaming a large homogeneous array
+
+A common use case is a huge top-level array of many similarly-shaped objects, too large to hold entirely in memory as a `json` value. A parser callback can hand off each completed element to a user function and then discard it, so memory usage stays bounded by a single element (plus the not-yet-parsed tail of the input) rather than the whole document. Since the top-level array's `array_start`/`array_end` are reported at `depth == 0` (its parent is the document root), the object elements it contains are reported at `depth == 1`:
+
+Example
+
+```
+std::ifstream input("large_array.json");
+
+auto callback = [](int depth, json::parse_event_t event, json& parsed) -> bool {
+    if (depth == 1 && event == json::parse_event_t::object_end) {
+        handle_element(parsed); // process the element, e.g. write it elsewhere
+        return false;           // discard it -- frees its memory before the next one is parsed
+    }
+    return true; // keep everything else, including the (by then empty) top-level array
+};
+
+json::parse(input, callback);
+```
+
+If the array's elements are scalars or nested arrays instead of objects, check for `parse_event_t::value` or `parse_event_t::array_end` at `depth == 1` instead. The same approach works for a top-level *object* of many homogeneous values by checking `object_end`/`value` events at `depth == 1` there too.
+
+## Recipe: max nesting depth via a callback
+
+Since there is no built-in nesting-depth limit (see the note above), a callback can enforce one manually by tracking the maximum `depth` seen and throwing once it is exceeded:
+
+Example
+
+```
+constexpr int max_depth = 32;
+
+auto callback = [](int depth, json::parse_event_t /*event*/, json& /*parsed*/) -> bool {
+    if (depth > max_depth) {
+        throw std::runtime_error("maximum nesting depth exceeded");
+    }
+    return true;
+};
+
+json::parse(input, callback);
+```