# Zero-copy JSON views `#!cpp ` adds a read-only, non-owning way to look at a parsed JSON text, as an alternative to building a [`basic_json`](../../api/basic_json/index.md) tree with [`parse()`](../../api/basic_json/parse.md). ## The problem [`basic_json::parse()`](../../api/basic_json/parse.md) builds a tree of `basic_json` values: one allocation for every array and object, and every string copied into its own `std::string`. That is the right trade-off when the program goes on to read and write the value freely, but it does more work than necessary when only a small part of a large JSON text is actually needed, or when the same text is parsed over and over (many small messages, for instance) and most of the resulting tree is thrown away almost immediately. ## The idea [`basic_json_document::parse()`](../../api/basic_json_document/parse.md) parses the same JSON grammar, with the same options, but instead of a tree it builds a flat index of the values it found: one [16-byte entry](../../home/architecture.md#node-index-of-json-views) per value (and one per object key), in document order. Integers are converted while parsing and stored in their entry. Floating-point numbers and strings are referenced in place in the source text: a float is converted when it is read, and only strings that contain escape sequences are decoded, into one shared buffer owned by the document. [`basic_json_view`](../../api/basic_json_view/index.md) is a small, trivially copyable handle (two pointers) into that index. It gives you the read-only, type-inspection part of the `basic_json` interface — [`type()`](../../api/basic_json_view/type.md) and the `is_*()` predicates, [`size()`](../../api/basic_json_view/size.md)/[`empty()`](../../api/basic_json_view/empty.md) — as well as element access ([`operator[]`](../../api/basic_json_view/operator%5B%5D.md), [`at`](../../api/basic_json_view/at.md), [`front`](../../api/basic_json_view/front.md)/[`back`](../../api/basic_json_view/back.md)), lookup ([`find`](../../api/basic_json_view/find.md), [`contains`](../../api/basic_json_view/contains.md), [`count`](../../api/basic_json_view/count.md)), and iteration ([`begin`](../../api/basic_json_view/begin.md)/[`end`](../../api/basic_json_view/end.md), [`items`](../../api/basic_json_view/items.md)) — without ever allocating a `basic_json` value. When you do need an actual `basic_json` value for a subtree, [`materialize()`](../../api/basic_json_view/materialize.md) builds exactly the one [`parse()`](../../api/basic_json/parse.md) would have produced for it. The same small text, parsed both ways:
The same J​SON text parsed by basic_json::parse() and by json_document::parse() The text {"port": 6379, "price": 19.90, "tags": ["eu", "a\"b"]}. Top: basic_json::parse() builds a tree: the root json value points to a std::map whose three nodes are separate heap allocations; the price is stored as the double 19.9; the tags array is a std::vector of two json values, each pointing to its own std::string. Bottom: json_document::parse() keeps the 54 bytes of source text and builds a flat index of nine 16-byte nodes in document order: object, key port, unsigned integer 6379 (the converted value is in the node), key price, float, key tags, array, string eu, and an escaped string. Keys, the float, and the plain string point back into the source text; the escaped string points into the document's buffer of decoded strings. A json_view is two pointers: one to the document and one to a node, here the array. basic_json::parse(): a tree, every array, object, and string in its own heap allocation json std::map "port" 6379 "price" 19.9 double: 19.90 is gone "tags" • std::vector json json std::string eu std::string a"b a separate heap allocation json_document::parse(): the source text stays where it is; one flat index of 16-byte nodes source text, 54 bytes (borrowed, or owned by the document) { " p o r t " : 6 3 7 9 , " p r i c e " : 1 9 . 9 0 , " t a g s " : [ " e u " , " a \ " b " ] } 0 10 20 30 40 50 json_document: owns the node index and the buffer of decoded strings node index: 9 nodes × 16 bytes = 144 bytes, in document order 0 object len 3 next 9 1 key off 2 len 4 2 uint 6379 (converted) 3 key off 16 len 5 4 float off 24 len 5 5 key off 32 len 4 6 array len 2 next 3 7 string off 41 len 2 8 string escaped len 3 decoded strings a " b json_view v = doc.root()["tags"] doc* node* integers are converted while parsing and kept in their node; floats and strings point back into the text

Top: the tree of separate heap allocations that `basic_json::parse()` builds. Bottom: `json_document::parse()` keeps the source text and builds one flat index of 16-byte nodes that point back into it, plus a buffer of decoded strings.

## How to use it Include `` in addition to (or instead of) ``. Parse into a [`json_document`](../../api/json_document.md), inspect its [`root()`](../../api/basic_json_document/root.md), and `materialize()` when you need a real value. `materialize()` works on any view, not just the root, so you can turn just the subtree you need into a value: ??? example "Example: parse a document, inspect its root, and materialize it" ```cpp #include #include using nlohmann::json_document; int main() { std::cout << std::boolalpha; // json_document is basic_json_document: same value types // and containers as the ordinary json specialization json_document doc = json_document::parse(R"({"pi": 3.14, "numbers": [1, 2, 3]})"); std::cout << doc.root().is_object() << '\n'; std::cout << doc.root().materialize().dump() << '\n'; } ``` Output: ```json true {"numbers":[1,2,3],"pi":3.14} ``` [`ordered_json_document`](../../api/ordered_json_document.md) is the equivalent for [`ordered_json`](../../api/ordered_json.md), just as [`ordered_json`](../../api/ordered_json.md) is to [`json`](../../api/json.md). A view behaves like a `basic_json` value in most respects, but not in all: lookups of a repeated key, the order in which an object's members are visited, and what a missing key does to chained `operator[]` are the most visible differences. [Differences from `basic_json`](differences.md) lists all of them. ## Where to go next - [Ownership and lifetime](lifetime.md) - when a document borrows its source text, and how long a view stays valid - [Differences from `basic_json`](differences.md) - everything a view does differently from a parsed `basic_json` value - [Reading values](reading.md) - converting with `get()`, reading strings and numbers without copying, and writing a view back with `dump()` - [Writing generic code](generic_code.md) - functions and `from_json()` overloads that accept views - [Editing a document](editing.md) - patching a document in place, keeping its member order and number spellings - [Images](images.md) - saving a parsed document and loading it back without parsing ## Choosing between `json`, `ordered_json`, the SAX interface, and `json_view` | | [`json`](../../api/json.md) / [`ordered_json`](../../api/ordered_json.md) | [SAX interface](../parsing/sax_interface.md) | [`json_document`](../../api/json_document.md) / [`json_view`](../../api/json_view.md) | [`json_editable_document`](../../api/json_editable_document.md) / [`json_editable_view`](../../api/json_editable_view.md) | |---|---|---|---|---| | **Ownership** | owns every value | owns nothing; you decide what to keep, in your handler | borrows or owns the *text*; the index is always owned by the document | same as `json_document`; edits go to storage the document owns | | **Mutability** | freely mutable | not applicable (a one-shot event stream) | read-only | [`set`](../../api/basic_json_document/set.md)/[`push_back`](../../api/basic_json_document/push_back.md)/[`insert`](../../api/basic_json_document/insert.md)/[`erase`](../../api/basic_json_document/erase.md) edit in place; the source text is never rewritten | | **What you get** | a full tree you can read, write, and keep as long as you like | a sequence of callbacks; whatever your handler builds from them | a flat index plus, on demand, [`materialize()`](../../api/basic_json_view/materialize.md)d `json`/`ordered_json` values for the parts you actually use | the same, plus [`dump()`](../../api/basic_json_view/dump.md) of an edited document that keeps the member order and, with [`number_format::source`](../../api/basic_json_view/number_format.md), the spelling of every untouched number | | **Typical use** | general-purpose JSON handling: config, request/response bodies you build or modify, anything you hold onto | validating or projecting a text into your own data structure without ever holding the whole thing as JSON | large or high-volume input where you only need part of it, or need it repeatedly, and can keep the source text (or a copy) alive for as long as the document lives | a document you read, patch a few fields of, and write back — a configuration file, for instance — where the rest of it should come back exactly as it was | | **Caching/reload** | not applicable — re-parse, or roll your own serialization | not applicable | [`save()`](../../api/basic_json_document/save.md)/[`load()`](../../api/basic_json_document/load.md): cache the parsed index as an [image](images.md) and reload it without parsing | same, saving the document's current — possibly edited — state |

Each column is one way to work with JSON in this library, and each row compares one property of them.

## See also - [`basic_json_document`](../../api/basic_json_document/index.md) - the document that owns the parsed index (parse, access, images, edits) - [`basic_json_view`](../../api/basic_json_view/index.md) - the non-owning handle to a value in a document - [`json_document`](../../api/json_document.md) - and [`ordered_json_document`](../../api/ordered_json_document.md) - the read-only documents - [`json_editable_document`](../../api/json_editable_document.md) - and [`ordered_json_editable_document`](../../api/ordered_json_editable_document.md) - the documents that can be edited in place - [Architecture](../../home/architecture.md#node-index-of-json-views) - the layout of the node index - [SAX interface](../parsing/sax_interface.md) - event-based parsing without building a tree - [Performance](../performance.md) - benchmarks and tuning of parsing and serialization - [Large, Streamed, and Partial Input](../parsing/large_and_partial_input.md) - reading only the part of a text you need ## Version history - Added in version 3.13.0.