deploy: 94fe31eb9b

api/basic_json_view/at.md

@@ -112,8 +112,8 @@ for a missing key or an out-of-range index, `at` throws for those too (`out_of_r
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
-    using json_view = nlohmann::json_view;
+    using nlohmann::json_document;
+    using nlohmann::json_view;
     
     int main()
     {
@@ -166,7 +166,7 @@ for a missing key or an out-of-range index, `at` throws for those too (`out_of_r
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     using json_pointer = nlohmann::json::json_pointer;
     
     int main()

api/basic_json_view/at/index.md

@@ -79,8 +79,8 @@ The example below reads required fields out of a service configuration with `at`
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
-using json_view = nlohmann::json_view;
+using nlohmann::json_document;
+using nlohmann::json_view;
 
 int main()
 {
@@ -130,7 +130,7 @@ The example below shows that `at` with a JSON pointer throws exactly the excepti
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 using json_pointer = nlohmann::json::json_pointer;
 
 int main()

api/basic_json_view/back.md

@@ -48,7 +48,7 @@ Unlike [`BasicJsonType::back()`](../basic_json/back.md), which has undefined beh
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/back/index.md

@@ -38,7 +38,7 @@ The example below reads only the final status of a build log with `back()`. Even
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/basic_json_view.md

@@ -1,20 +1,32 @@
 # <small>nlohmann::basic_json_view::</small>basic_json_view
 
 ```cpp
+// (1)
 basic_json_view() noexcept = default;
+
+// (2) only for Mode == view_mode::editable
+basic_json_view(const basic_json_view<BasicJsonType, view_mode::read_only>& other) noexcept;
 ```
 
-Creates an invalid (discarded) view: [`type()`](type.md) is `#!cpp value_t::discarded` and
-[`is_discarded()`](is_discarded.md) is `#!cpp true`.
+1. Creates an invalid (discarded) view: [`type()`](type.md) is `#!cpp value_t::discarded` and
+   [`is_discarded()`](is_discarded.md) is `#!cpp true`.
+2. Converts a view of a read-only document into a view of an editable document (implicitly), so that a function
+   taking a [`json_editable_view`](../json_editable_view.md) accepts both. The result is a view of the same value of
+   the same read-only document. See [`view_mode`](../view_mode.md) for why there is no conversion the other way.
 
-This is the only constructor a caller can use directly. Every other view is obtained from a
+## Parameters
+
+`other` (in)
+:   a view of a read-only document with the same `BasicJsonType`
+
+Apart from these, a view is obtained from a
 [`basic_json_document`](../basic_json_document/index.md), via [`root()`](../basic_json_document/root.md) or by
 navigating into a container with [`operator[]`](operator[].md), [`at`](at.md), [`front`](front.md), [`back`](back.md),
 [`find`](find.md), or iteration.
 
 ## Exception safety
 
-No-throw guarantee: this constructor never throws exceptions.
+No-throw guarantee: these constructors never throw exceptions.
 
 ## Complexity
 
@@ -64,6 +76,7 @@ placeholder for "no value yet" and later be assigned a real view.
 
 - [is_discarded](is_discarded.md) - return whether the view is invalid
 - [root](../basic_json_document/root.md) - the view of a document's root value
+- [view_mode](../view_mode.md) - whether a document and its views can be edited
 
 ## Version history
 

api/basic_json_view/basic_json_view/index.md

@@ -1,16 +1,25 @@
 # nlohmann::basic_json_view::basic_json_view
 
 ```
+// (1)
 basic_json_view() noexcept = default;
+
+// (2) only for Mode == view_mode::editable
+basic_json_view(const basic_json_view<BasicJsonType, view_mode::read_only>& other) noexcept;
 ```
 
-Creates an invalid (discarded) view: [`type()`](https://json.nlohmann.me/api/basic_json_view/type/index.md) is `value_t::discarded` and [`is_discarded()`](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) is `true`.
+1. Creates an invalid (discarded) view: [`type()`](https://json.nlohmann.me/api/basic_json_view/type/index.md) is `value_t::discarded` and [`is_discarded()`](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) is `true`.
+1. Converts a view of a read-only document into a view of an editable document (implicitly), so that a function taking a [`json_editable_view`](https://json.nlohmann.me/api/json_editable_view/index.md) accepts both. The result is a view of the same value of the same read-only document. See [`view_mode`](https://json.nlohmann.me/api/view_mode/index.md) for why there is no conversion the other way.
 
-This is the only constructor a caller can use directly. Every other view is obtained from a [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md), via [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) or by navigating into a container with [`operator[]`](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json_view/at/index.md), [`front`](https://json.nlohmann.me/api/basic_json_view/front/index.md), [`back`](https://json.nlohmann.me/api/basic_json_view/back/index.md), [`find`](https://json.nlohmann.me/api/basic_json_view/find/index.md), or iteration.
+## Parameters
+
+`other` (in) : a view of a read-only document with the same `BasicJsonType`
+
+Apart from these, a view is obtained from a [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md), via [`root()`](https://json.nlohmann.me/api/basic_json_document/root/index.md) or by navigating into a container with [`operator[]`](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json_view/at/index.md), [`front`](https://json.nlohmann.me/api/basic_json_view/front/index.md), [`back`](https://json.nlohmann.me/api/basic_json_view/back/index.md), [`find`](https://json.nlohmann.me/api/basic_json_view/find/index.md), or iteration.
 
 ## Exception safety
 
-No-throw guarantee: this constructor never throws exceptions.
+No-throw guarantee: these constructors never throw exceptions.
 
 ## Complexity
 
@@ -57,6 +66,7 @@ true
 
 - [is_discarded](https://json.nlohmann.me/api/basic_json_view/is_discarded/index.md) - return whether the view is invalid
 - [root](https://json.nlohmann.me/api/basic_json_document/root/index.md) - the view of a document's root value
+- [view_mode](https://json.nlohmann.me/api/view_mode/index.md) - whether a document and its views can be edited
 
 ## Version history
 

api/basic_json_view/begin.md

@@ -47,7 +47,7 @@ the duplicates.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/begin/index.md

@@ -36,7 +36,7 @@ The example below iterates a log record's members with `begin()`/[`end()`](https
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/cbegin.md

@@ -33,8 +33,8 @@ Constant.
     #include <numeric>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
-    using json_view = nlohmann::json_view;
+    using nlohmann::json_document;
+    using nlohmann::json_view;
     
     int main()
     {

api/basic_json_view/cbegin/index.md

@@ -29,8 +29,8 @@ The example below sums many measurements with `std::accumulate`, using `cbegin()
 #include <numeric>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
-using json_view = nlohmann::json_view;
+using nlohmann::json_document;
+using nlohmann::json_view;
 
 int main()
 {

api/basic_json_view/cend.md

@@ -33,8 +33,8 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
-    using json_view = nlohmann::json_view;
+    using nlohmann::json_document;
+    using nlohmann::json_view;
     
     int main()
     {

api/basic_json_view/cend/index.md

@@ -29,8 +29,8 @@ The example below checks that every record of a batch is an object with `std::al
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
-using json_view = nlohmann::json_view;
+using nlohmann::json_document;
+using nlohmann::json_view;
 
 int main()
 {

api/basic_json_view/contains.md

@@ -78,7 +78,7 @@ view.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {
@@ -124,7 +124,7 @@ view.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     using json_pointer = nlohmann::json::json_pointer;
     
     int main()

api/basic_json_view/contains/index.md

@@ -59,7 +59,7 @@ The example below counts how many of a batch of records carry an optional `retry
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {
@@ -102,7 +102,7 @@ The example below checks an optional, nested field with a JSON pointer, and show
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 using json_pointer = nlohmann::json::json_pointer;
 
 int main()

api/basic_json_view/count.md

@@ -54,7 +54,7 @@ If the source text repeats a key, `count()` returns more than `#!cpp 1` for it,
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/count/index.md

@@ -40,7 +40,7 @@ The example below validates that every transaction of a batch carries exactly on
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/dump.md

@@ -86,8 +86,8 @@ parsing already reduces every number to its parsed value.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
-    using json_view = nlohmann::json_view;
+    using nlohmann::json_document;
+    using nlohmann::json_view;
     
     int main()
     {

api/basic_json_view/dump/index.md

@@ -55,8 +55,8 @@ The example below forwards a single record out of a larger batch, and re-seriali
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
-using json_view = nlohmann::json_view;
+using nlohmann::json_document;
+using nlohmann::json_view;
 
 int main()
 {

api/basic_json_view/empty.md

@@ -45,7 +45,7 @@ is `#!cpp false` for any string, regardless of its length.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/empty/index.md

@@ -42,7 +42,7 @@ The example below uses [`size()`](https://json.nlohmann.me/api/basic_json_view/s
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/end.md

@@ -36,7 +36,7 @@ way to reach the last element by stepping back from `end()`. Use [`back()`](back
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/end/index.md

@@ -32,7 +32,7 @@ The example below scans a (possibly large) array of readings for the first one o
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/find.md

@@ -55,7 +55,7 @@ also does so for a [discarded](is_discarded.md) view -- there is no separate "in
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/find/index.md

@@ -42,7 +42,7 @@ The example below scans a batch of events for those that carry an optional `user
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/front.md

@@ -45,7 +45,7 @@ view.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/front/index.md

@@ -38,7 +38,7 @@ The example below reads only the earliest entry of a build log with `front()`, w
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/get.md

@@ -19,16 +19,36 @@ For the types below, the conversion works directly on the flat index -- no `Basi
   document's own buffer of decoded strings (see [`get_string()`](get_string.md))
 - `BasicJsonType` -- equivalent to [`materialize()`](materialize.md)
 - `basic_json_view` -- returns `#!cpp *this`
-- `#!cpp std::vector<U, A>` -- from an array, element by element, each converted with `#!cpp get<U>()`; `#!cpp
-  std::vector<basic_json_view>` keeps a view of every element instead of a value
-- `#!cpp std::map<K, V, C, A>` and `#!cpp std::unordered_map<K, V, H, E, A>`, if `K` is constructible from a `#!cpp
-  (const char*, std::size_t)` pair -- from an object, member by member, each value converted with `#!cpp get<V>()`; with a repeated
-  key, the *last* value is kept, as [`BasicJsonType::parse()`](../basic_json/parse.md) (and
-  [`materialize()`](materialize.md)) does; `#!cpp std::map<std::string, basic_json_view>` keeps views of the members
-  instead of values
+- `#!cpp std::vector<U, A>` of the types above -- from an array, element by element, each converted with
+  `#!cpp get<U>()`; `#!cpp std::vector<basic_json_view>` keeps a view of every element instead of a value
+- `#!cpp std::map<K, basic_json_view, C, A>` and `#!cpp std::unordered_map<K, basic_json_view, H, E, A>`, if `K` is
+  constructible from a `#!cpp (const char*, std::size_t)` pair -- views of the members of an object; with a repeated
+  key, the view of the *last* member is kept, as [`BasicJsonType::parse()`](../basic_json/parse.md) keeps its value
 
-Every other `T` -- `#!cpp std::list`, `#!cpp std::pair`, `#!cpp std::array`, enumerations, user types with a
-`from_json()`, ... -- is converted by `#!cpp materialize().get<T>()`: the subtree is built into a real `BasicJsonType`
+A default-constructible `T` whose `from_json()` accepts views reads the view directly as well, without building a
+`BasicJsonType` value. This covers the library's own conversions of the standard library types -- all other
+`#!cpp std::vector`s, `#!cpp std::map`/`#!cpp std::unordered_map` (also with other key types), `#!cpp std::list`,
+`#!cpp std::deque`, `#!cpp std::set`, `#!cpp std::forward_list`, `#!cpp std::valarray`, `#!cpp std::array`, C arrays,
+`#!cpp std::pair`, `#!cpp std::tuple`, `#!cpp std::optional`, enumerations, `#!cpp std::filesystem::path`, ... --
+which give the same values as `#!cpp materialize().get<T>()` (from an object, a repeated key keeps the *last* value,
+as [`BasicJsonType::parse()`](../basic_json/parse.md) does), as well as the types of the
+[`NLOHMANN_DEFINE_TYPE_*`](../macros/nlohmann_define_type_intrusive.md) and
+[`NLOHMANN_DEFINE_DERIVED_TYPE_*`](../macros/nlohmann_define_derived_type.md) macros and the enumerations of
+[`NLOHMANN_JSON_SERIALIZE_ENUM`](../macros/nlohmann_json_serialize_enum.md), and any `from_json()` constrained to
+accept views, e.g. with [`is_json_view`](../is_json_view.md). A `from_json()` that also accepts types that are no JSON
+values at all, such as the unconstrained `#!cpp template<typename BasicJsonType> void from_json(const BasicJsonType&,
+T&)` of [arbitrary type conversions](../../features/arbitrary_types.md), is not called with a view: it may use
+`BasicJsonType` functions a view does not have. See [Writing generic code](../../features/json_view.md#writing-generic-code).
+
+!!! warning "Duplicate keys"
+
+    Such a `from_json()` looks members up in the view, where a repeated key finds the **first** member, while
+    `#!cpp materialize().get<T>()` sees the **last** one, as [`BasicJsonType::parse()`](../basic_json/parse.md)
+    keeps it: for `#!cpp {"x":1,"x":2}`, `#!cpp get<point>()` reads `#!cpp x == 1`. See
+    [Duplicate keys](../../features/json_view.md#duplicate-keys).
+
+Every other `T` -- user types whose `from_json()` is written for `BasicJsonType` only, types without a default
+constructor, `#!cpp std::tuple`s holding references, ... -- is converted by `#!cpp materialize().get<T>()`: the subtree is built into a real `BasicJsonType`
 value first (as [`BasicJsonType::parse()`](../basic_json/parse.md) would), and converted from there exactly as
 [`BasicJsonType::get<T>()`](../basic_json/get.md) would convert it.
 
@@ -53,12 +73,15 @@ Strong guarantee: there are no changes to the view or the document it refers to.
   throws for the same JSON type and `T`.
 - For `#!cpp std::vector<U, A>`: throws `type_error.302` if the value is not an array; otherwise, whatever converting
   an element to `U` throws.
-- For `#!cpp std::map`/`#!cpp std::unordered_map`: throws `type_error.302` if the value is not an object; otherwise,
-  whatever converting a member to the mapped type throws.
+- For `#!cpp std::map`/`#!cpp std::unordered_map` of views: throws `type_error.302` if the value is not an object.
+- For a `T` whose `from_json()` reads the view: whatever that `from_json()` throws; for the library's conversions and
+  the macros, the same exceptions with the same messages as [`BasicJsonType::get<T>()`](../basic_json/get.md) of the
+  same value.
 - For every other `T`: whatever [`materialize().get<T>()`](../basic_json/get.md) throws -- typically `type_error.302`,
   or whatever a user-provided `from_json()` throws.
 
-None of the exceptions thrown directly by this function (the first three bullets above) carry a
+None of the exceptions thrown directly by this function or by a `from_json()` that reads the view (the first four
+bullets above) carry a
 [`JSON_DIAGNOSTICS`](../macros/json_diagnostics.md) path: the view has no `BasicJsonType` value to point at. An
 exception thrown while converting through `materialize()` (the last bullet) is different: it is thrown by a real
 `BasicJsonType` value, so it **does** carry a `JSON_DIAGNOSTICS` path if `BasicJsonType` was built with it enabled.
@@ -76,6 +99,8 @@ document.
 - `#!cpp std::map`/`#!cpp std::unordered_map`: linear in the number of members for walking them, plus the container's
   own insertion cost per member (logarithmic for `#!cpp std::map`, amortized constant for `#!cpp
   std::unordered_map`), times the complexity of converting one member to the mapped type.
+- a `T` whose `from_json()` reads the view: the cost of that `from_json()`; for the macros, linear in the number of
+  members times the cost of a lookup, plus the cost of converting the members.
 - every other `T`: the cost of [`materialize()`](materialize.md) and of destroying the `BasicJsonType` value
   afterwards, plus that of [`BasicJsonType::get<T>()`](../basic_json/get.md).
 
@@ -116,8 +141,8 @@ document.
     #include <string>
     #include <vector>
     
-    using json_document = nlohmann::json_document;
-    using json_view = nlohmann::json_view;
+    using nlohmann::json_document;
+    using nlohmann::json_view;
     
     // address has no direct conversion in get<T>(), so get<address>() falls back
     // to materialize().get<address>() -- a real nlohmann::json value is built

api/basic_json_view/get/index.md

@@ -16,10 +16,16 @@ For the types below, the conversion works directly on the flat index -- no `Basi
 - [`string_view_t`](https://json.nlohmann.me/api/basic_json_view/#member-types) -- **no copy**: the returned view points into the document's [`source()`](https://json.nlohmann.me/api/basic_json_document/source/index.md) text, or, for a string that contains escape sequences, into the document's own buffer of decoded strings (see [`get_string()`](https://json.nlohmann.me/api/basic_json_view/get_string/index.md))
 - `BasicJsonType` -- equivalent to [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md)
 - `basic_json_view` -- returns `*this`
-- `std::vector<U, A>` -- from an array, element by element, each converted with `get<U>()`; `std::vector<basic_json_view>` keeps a view of every element instead of a value
-- `std::map<K, V, C, A>` and `std::unordered_map<K, V, H, E, A>`, if `K` is constructible from a `(const char*, std::size_t)` pair -- from an object, member by member, each value converted with `get<V>()`; with a repeated key, the *last* value is kept, as [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) (and [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md)) does; `std::map<std::string, basic_json_view>` keeps views of the members instead of values
+- `std::vector<U, A>` of the types above -- from an array, element by element, each converted with `get<U>()`; `std::vector<basic_json_view>` keeps a view of every element instead of a value
+- `std::map<K, basic_json_view, C, A>` and `std::unordered_map<K, basic_json_view, H, E, A>`, if `K` is constructible from a `(const char*, std::size_t)` pair -- views of the members of an object; with a repeated key, the view of the *last* member is kept, as [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) keeps its value
 
-Every other `T` -- `std::list`, `std::pair`, `std::array`, enumerations, user types with a `from_json()`, ... -- is converted by `materialize().get<T>()`: the subtree is built into a real `BasicJsonType` value first (as [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) would), and converted from there exactly as [`BasicJsonType::get<T>()`](https://json.nlohmann.me/api/basic_json/get/index.md) would convert it.
+A default-constructible `T` whose `from_json()` accepts views reads the view directly as well, without building a `BasicJsonType` value. This covers the library's own conversions of the standard library types -- all other `std::vector`s, `std::map`/`std::unordered_map` (also with other key types), `std::list`, `std::deque`, `std::set`, `std::forward_list`, `std::valarray`, `std::array`, C arrays, `std::pair`, `std::tuple`, `std::optional`, enumerations, `std::filesystem::path`, ... -- which give the same values as `materialize().get<T>()` (from an object, a repeated key keeps the *last* value, as [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) does), as well as the types of the [`NLOHMANN_DEFINE_TYPE_*`](https://json.nlohmann.me/api/macros/nlohmann_define_type_intrusive/index.md) and [`NLOHMANN_DEFINE_DERIVED_TYPE_*`](https://json.nlohmann.me/api/macros/nlohmann_define_derived_type/index.md) macros and the enumerations of [`NLOHMANN_JSON_SERIALIZE_ENUM`](https://json.nlohmann.me/api/macros/nlohmann_json_serialize_enum/index.md), and any `from_json()` constrained to accept views, e.g. with [`is_json_view`](https://json.nlohmann.me/api/is_json_view/index.md). A `from_json()` that also accepts types that are no JSON values at all, such as the unconstrained `template<typename BasicJsonType> void from_json(const BasicJsonType&,T&)` of [arbitrary type conversions](https://json.nlohmann.me/features/arbitrary_types/index.md), is not called with a view: it may use `BasicJsonType` functions a view does not have. See [Writing generic code](https://json.nlohmann.me/features/json_view/#writing-generic-code).
+
+Duplicate keys
+
+Such a `from_json()` looks members up in the view, where a repeated key finds the **first** member, while `materialize().get<T>()` sees the **last** one, as [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) keeps it: for `{"x":1,"x":2}`, `get<point>()` reads `x == 1`. See [Duplicate keys](https://json.nlohmann.me/features/json_view/#duplicate-keys).
+
+Every other `T` -- user types whose `from_json()` is written for `BasicJsonType` only, types without a default constructor, `std::tuple`s holding references, ... -- is converted by `materialize().get<T>()`: the subtree is built into a real `BasicJsonType` value first (as [`BasicJsonType::parse()`](https://json.nlohmann.me/api/basic_json/parse/index.md) would), and converted from there exactly as [`BasicJsonType::get<T>()`](https://json.nlohmann.me/api/basic_json/get/index.md) would convert it.
 
 ## Template parameters
 
@@ -37,10 +43,11 @@ Strong guarantee: there are no changes to the view or the document it refers to.
 
 - For the directly-converted types listed above (other than `BasicJsonType` and `basic_json_view`, which never throw): throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) if the value's type does not match `T` -- the same exception, with the same message, that [`BasicJsonType::get<T>()`](https://json.nlohmann.me/api/basic_json/get/index.md) throws for the same JSON type and `T`.
 - For `std::vector<U, A>`: throws `type_error.302` if the value is not an array; otherwise, whatever converting an element to `U` throws.
-- For `std::map`/`std::unordered_map`: throws `type_error.302` if the value is not an object; otherwise, whatever converting a member to the mapped type throws.
+- For `std::map`/`std::unordered_map` of views: throws `type_error.302` if the value is not an object.
+- For a `T` whose `from_json()` reads the view: whatever that `from_json()` throws; for the library's conversions and the macros, the same exceptions with the same messages as [`BasicJsonType::get<T>()`](https://json.nlohmann.me/api/basic_json/get/index.md) of the same value.
 - For every other `T`: whatever [`materialize().get<T>()`](https://json.nlohmann.me/api/basic_json/get/index.md) throws -- typically `type_error.302`, or whatever a user-provided `from_json()` throws.
 
-None of the exceptions thrown directly by this function (the first three bullets above) carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at. An exception thrown while converting through `materialize()` (the last bullet) is different: it is thrown by a real `BasicJsonType` value, so it **does** carry a `JSON_DIAGNOSTICS` path if `BasicJsonType` was built with it enabled. That path is relative to the root of the view's subtree, because `materialize()` builds only the subtree (with parent pointers): it is empty if the failing value is the subtree's root itself, and it never is the path within the whole document.
+None of the exceptions thrown directly by this function or by a `from_json()` that reads the view (the first four bullets above) carry a [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) path: the view has no `BasicJsonType` value to point at. An exception thrown while converting through `materialize()` (the last bullet) is different: it is thrown by a real `BasicJsonType` value, so it **does** carry a `JSON_DIAGNOSTICS` path if `BasicJsonType` was built with it enabled. That path is relative to the root of the view's subtree, because `materialize()` builds only the subtree (with parent pointers): it is empty if the failing value is the subtree's root itself, and it never is the path within the whole document.
 
 ## Complexity
 
@@ -49,6 +56,7 @@ None of the exceptions thrown directly by this function (the first three bullets
 - `BasicJsonType`: linear in the size of the subtree, see [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md).
 - `std::vector<U, A>`: linear in the number of elements, times the complexity of converting one element to `U`.
 - `std::map`/`std::unordered_map`: linear in the number of members for walking them, plus the container's own insertion cost per member (logarithmic for `std::map`, amortized constant for `std::unordered_map`), times the complexity of converting one member to the mapped type.
+- a `T` whose `from_json()` reads the view: the cost of that `from_json()`; for the macros, linear in the number of members times the cost of a lookup, plus the cost of converting the members.
 - every other `T`: the cost of [`materialize()`](https://json.nlohmann.me/api/basic_json_view/materialize/index.md) and of destroying the `BasicJsonType` value afterwards, plus that of [`BasicJsonType::get<T>()`](https://json.nlohmann.me/api/basic_json/get/index.md).
 
 ## Notes
@@ -77,8 +85,8 @@ The example below reads typed fields straight into C++ variables, collects a vie
 #include <string>
 #include <vector>
 
-using json_document = nlohmann::json_document;
-using json_view = nlohmann::json_view;
+using nlohmann::json_document;
+using nlohmann::json_view;
 
 // address has no direct conversion in get<T>(), so get<address>() falls back
 // to materialize().get<address>() -- a real nlohmann::json value is built

api/basic_json_view/get_string.md

@@ -60,8 +60,8 @@ since floating-point values and unescaped strings are read from the source lazil
     #include <nlohmann/json_view.hpp>
     #include <string>
     
-    using json_document = nlohmann::json_document;
-    using json_view = nlohmann::json_view;
+    using nlohmann::json_document;
+    using nlohmann::json_view;
     
     int main()
     {

api/basic_json_view/get_string/index.md

@@ -43,8 +43,8 @@ The example below pulls one field out of a JSON text that stands in for a large
 #include <nlohmann/json_view.hpp>
 #include <string>
 
-using json_document = nlohmann::json_document;
-using json_view = nlohmann::json_view;
+using nlohmann::json_document;
+using nlohmann::json_view;
 
 int main()
 {

api/basic_json_view/get_to.md

@@ -5,12 +5,13 @@ template<typename T>
 T& get_to(T& v) const;
 ```
 
-Converts the value to `T` and stores it in `v`, in one of two ways:
+Converts the value to `T` and stores it in `v`, in one of three ways:
 
 - For the types that [`get<T>()`](get.md) converts directly -- arithmetic types, `#!cpp bool`,
   `#!cpp std::nullptr_t`, [`string_view_t`](index.md#member-types), `#!cpp std::basic_string`, `BasicJsonType`,
-  `basic_json_view`, `#!cpp std::vector`, and `#!cpp std::map`/`#!cpp std::unordered_map` with string keys -- `v` is
-  assigned: `#!cpp v = get<T>()`.
+  `basic_json_view`, vectors of these, and maps of views -- `v` is assigned: `#!cpp v = get<T>()`.
+- For a type whose `from_json()` accepts views (see [`get<T>()`](get.md)), that `from_json()` is called with the
+  view and the existing `v`, without building a `BasicJsonType` value.
 - For every other type, the subtree is built into a `BasicJsonType` value and `#!cpp materialize().get_to(v)` is
   called, i.e. `from_json()` is invoked with the existing `v`, exactly as
   [`BasicJsonType::get_to()`](../basic_json/get_to.md) does.
@@ -65,8 +66,8 @@ them with those of a default-constructed `T`.
     #include <nlohmann/json_view.hpp>
     #include <string>
     
-    using json_document = nlohmann::json_document;
-    using json_view = nlohmann::json_view;
+    using nlohmann::json_document;
+    using nlohmann::json_view;
     
     int main()
     {

api/basic_json_view/get_to/index.md

@@ -5,9 +5,10 @@ template<typename T>
 T& get_to(T& v) const;
 ```
 
-Converts the value to `T` and stores it in `v`, in one of two ways:
+Converts the value to `T` and stores it in `v`, in one of three ways:
 
-- For the types that [`get<T>()`](https://json.nlohmann.me/api/basic_json_view/get/index.md) converts directly -- arithmetic types, `bool`, `std::nullptr_t`, [`string_view_t`](https://json.nlohmann.me/api/basic_json_view/#member-types), `std::basic_string`, `BasicJsonType`, `basic_json_view`, `std::vector`, and `std::map`/`std::unordered_map` with string keys -- `v` is assigned: `v = get<T>()`.
+- For the types that [`get<T>()`](https://json.nlohmann.me/api/basic_json_view/get/index.md) converts directly -- arithmetic types, `bool`, `std::nullptr_t`, [`string_view_t`](https://json.nlohmann.me/api/basic_json_view/#member-types), `std::basic_string`, `BasicJsonType`, `basic_json_view`, vectors of these, and maps of views -- `v` is assigned: `v = get<T>()`.
+- For a type whose `from_json()` accepts views (see [`get<T>()`](https://json.nlohmann.me/api/basic_json_view/get/index.md)), that `from_json()` is called with the view and the existing `v`, without building a `BasicJsonType` value.
 - For every other type, the subtree is built into a `BasicJsonType` value and `materialize().get_to(v)` is called, i.e. `from_json()` is invoked with the existing `v`, exactly as [`BasicJsonType::get_to()`](https://json.nlohmann.me/api/basic_json/get_to/index.md) does.
 
 ## Template parameters
@@ -52,8 +53,8 @@ The example below reads several fields of a service configuration directly into
 #include <nlohmann/json_view.hpp>
 #include <string>
 
-using json_document = nlohmann::json_document;
-using json_view = nlohmann::json_view;
+using nlohmann::json_document;
+using nlohmann::json_view;
 
 int main()
 {

api/basic_json_view/index.md

@@ -3,7 +3,7 @@
 Defined in header `<nlohmann/json_view.hpp>`
 
 ```
-template<typename BasicJsonType, bool Editable = false>
+template<typename BasicJsonType, view_mode Mode = view_mode::read_only>
 class basic_json_view;
 ```
 
@@ -26,13 +26,13 @@ Moving the document itself does not invalidate its views: the index is heap-allo
 
 [`operator[]`](https://json.nlohmann.me/api/basic_json_view/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json_view/at/index.md), [`contains`](https://json.nlohmann.me/api/basic_json_view/contains/index.md), and [`value`](https://json.nlohmann.me/api/basic_json_view/value/index.md) also accept a [`json_pointer`](https://json.nlohmann.me/api/json_pointer/index.md). Unlike `basic_json`, there are no implicit conversion operators (no `operator ValueType()`), and no `get_ptr()` or `get_ref()`; see [`get`](https://json.nlohmann.me/api/basic_json_view/get/index.md).
 
-`basic_json_view` itself is always read-only -- it never has a `set` or `push_back` of its own. A view of an **editable** document (`Editable == true`) sees every edit made through [`basic_json_document::set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) and [`basic_json_document::push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md): once a value is changed, every view that still refers to it -- including ones taken before the change -- reads the new value. See [Edits](https://json.nlohmann.me/api/basic_json_document/#edits).
+`basic_json_view` itself is always read-only -- it never has a `set` or `push_back` of its own. A view of an **editable** document (`view_mode::editable`) sees every edit made through [`basic_json_document::set`](https://json.nlohmann.me/api/basic_json_document/set/index.md) and [`basic_json_document::push_back`](https://json.nlohmann.me/api/basic_json_document/push_back/index.md): once a value is changed, every view that still refers to it -- including ones taken before the change -- reads the new value. See [Edits](https://json.nlohmann.me/api/basic_json_document/#edits).
 
 ## Template parameters
 
 `BasicJsonType` : a specialization of [`basic_json`](https://json.nlohmann.me/api/basic_json/index.md), matching the [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md) the view was taken from.
 
-`Editable` : whether the view is of an editable document, matching the [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md) it was taken from (optional, `false` by default). See [Edits](https://json.nlohmann.me/api/basic_json_document/#edits).
+`Mode` : a [`view_mode`](https://json.nlohmann.me/api/view_mode/index.md): whether the view is of an editable document, matching the [`basic_json_document`](https://json.nlohmann.me/api/basic_json_document/index.md) it was taken from (optional, `view_mode::read_only` by default). See [Edits](https://json.nlohmann.me/api/basic_json_document/#edits).
 
 ## Specializations
 
@@ -43,6 +43,7 @@ Moving the document itself does not invalidate its views: the index is heap-allo
 
 ## Member types
 
+- **basic_json_type** - `BasicJsonType` (it also marks the class for [`is_json_view`](https://json.nlohmann.me/api/is_json_view/index.md))
 - **value_t** - the JSON type enumeration, see [`basic_json::value_t`](https://json.nlohmann.me/api/basic_json/value_t/index.md)
 - **string_t**, **number_integer_t**, **number_unsigned_t**, **number_float_t**, **json_pointer** - the corresponding member types of `BasicJsonType`
 - **size_type** - `std::size_t`

api/basic_json_view/is_array.md

@@ -29,7 +29,7 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_array/index.md

@@ -28,7 +28,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_binary.md

@@ -31,7 +31,7 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_binary/index.md

@@ -28,7 +28,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_boolean.md

@@ -29,7 +29,7 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_boolean/index.md

@@ -28,7 +28,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_discarded.md

@@ -42,7 +42,7 @@ A `basic_json_view` is not convertible to `#!cpp bool`: such a conversion would
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_discarded/index.md

@@ -34,7 +34,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_null.md

@@ -29,7 +29,7 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_null/index.md

@@ -28,7 +28,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_number.md

@@ -29,7 +29,7 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_number/index.md

@@ -28,7 +28,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_number_float.md

@@ -35,7 +35,7 @@ integer-looking token in the source text.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_number_float/index.md

@@ -32,7 +32,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_number_integer.md

@@ -34,7 +34,7 @@ values; use [`is_number_unsigned`](is_number_unsigned.md) to test for those spec
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_number_integer/index.md

@@ -32,7 +32,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_number_unsigned.md

@@ -29,7 +29,7 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_number_unsigned/index.md

@@ -28,7 +28,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_object.md

@@ -29,7 +29,7 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_object/index.md

@@ -28,7 +28,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_primitive.md

@@ -29,7 +29,7 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_primitive/index.md

@@ -28,7 +28,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_string.md

@@ -29,7 +29,7 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_string/index.md

@@ -28,7 +28,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/is_structured.md

@@ -29,7 +29,7 @@ Constant.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/is_structured/index.md

@@ -28,7 +28,7 @@ The example below classifies several parsed documents by the type of their root
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/items.md

@@ -70,7 +70,7 @@ and [`contains`](contains.md), which resolve to the *first* member with a given
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/items/index.md

@@ -56,7 +56,7 @@ The example below shows a settings object whose source text records every update
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/materialize.md

@@ -53,7 +53,7 @@ never caches the result.
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
+    using nlohmann::json_document;
     
     int main()
     {

api/basic_json_view/materialize/index.md

@@ -41,7 +41,7 @@ The example below skips messages that are not useful -- a discarded value, or an
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
+using nlohmann::json_document;
 
 int main()
 {

api/basic_json_view/number_format.md

@@ -33,8 +33,8 @@ source
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
-    using json_view = nlohmann::json_view;
+    using nlohmann::json_document;
+    using nlohmann::json_view;
     
     int main()
     {

api/basic_json_view/number_format/index.md

@@ -23,8 +23,8 @@ The example below writes back a price list received from a supplier: with `numbe
 #include <iostream>
 #include <nlohmann/json_view.hpp>
 
-using json_document = nlohmann::json_document;
-using json_view = nlohmann::json_view;
+using nlohmann::json_document;
+using nlohmann::json_view;
 
 int main()
 {

api/basic_json_view/number_token.md

@@ -55,8 +55,8 @@ buffer -- and is valid exactly as long as that text is, see the [validity rules]
     #include <iostream>
     #include <nlohmann/json_view.hpp>
     
-    using json_document = nlohmann::json_document;
-    using json_view = nlohmann::json_view;
+    using nlohmann::json_document;
+    using nlohmann::json_view;
     
     int main()
     {