Return the first member of duplicate keys from lookups again

Looking up the last member of a duplicate key cannot stop at a match, so
every lookup scanned the whole object (1.6 to 3.4 times slower for small
objects). operator[](key), at, find, value, contains, count, and JSON
pointer resolution return the first member again, as yyjson and simdjson
do; materialize() and get<map>() keep the last value, as parse().

The documentation says so in the feature page and on each lookup page,
and explains how to get the value parse() would give. The integer index
templates and the discarded chaining of operator[] stay.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/basic_json_view/at.md

@@ -15,7 +15,7 @@ basic_json_view at(IntegerType idx) const;
 basic_json_view at(const json_pointer& ptr) const;
 ```
 
-1. Returns the value of the object member with key `key` -- the last one, should the key occur more than once (see
+1. Returns the value of the object member with key `key` -- the first one, should the key occur more than once (see
    [Notes on duplicate keys](operator[].md#notes)).
 2. Returns the array element at index `idx`. The template accepts every integer type except `#!cpp bool` and
    `#!cpp std::size_t` and forwards to the `size_type` overload, as for [`operator[]`](operator[].md); a negative
@@ -35,7 +35,7 @@ basic_json_view at(const json_pointer& ptr) const;
 
 ## Return value
 
-1. the value of the last member with key `key`
+1. the value of the first member with key `key`
 2. the element at index `idx`
 3. the value `ptr` resolves to, starting at this value
 
@@ -75,7 +75,7 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
 ## Complexity
 
 1. Linear in the number of members: as for [`ordered_json`](../ordered_json.md), members are compared one after
-   another, in document order, scanning all of them, since the last match is wanted. Each comparison first checks the
+   another, in document order, stopping at the first match. Each comparison first checks the
    key's length -- already known from the index, without reading the key bytes -- before comparing its content.
 2. Linear in `idx`: elements are skipped one at a time from the first one, since they are not a fixed size in the
    index (unlike `BasicJsonType`'s array, which is random-access).
@@ -84,6 +84,13 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
 
 ## Notes
 
+!!! warning "Duplicate keys: the first member wins"
+
+    If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
+    [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
+    `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
+    the last value.
+
 Unlike [`operator[]`](operator[].md), which returns a [discarded](is_discarded.md) view for a missing key or an
 out-of-range index, `at` always throws -- exactly as `BasicJsonType::at` does, and with the same messages, so
 existing error handling written against `BasicJsonType::at` keeps working unchanged when switched to a view. This

docs/mkdocs/docs/api/basic_json_view/begin.md

@@ -24,7 +24,7 @@ Constant.
 
 For an object, iteration visits **every** member, including all occurrences of a duplicate key -- unlike
 [`operator[]`](operator[].md), [`at`](at.md), [`find`](find.md), [`contains`](contains.md), and [`count`](count.md),
-which all resolve to the *last* member with a given key. See the
+which all resolve to the *first* member with a given key. See the
 [Notes on duplicate keys](operator[].md#notes) of `operator[]`.
 
 Because objects are iterated in document order rather than sorted by key, the order seen here can differ from what

docs/mkdocs/docs/api/basic_json_view/contains.md

@@ -33,7 +33,7 @@ No-throw guarantee: this function never throws exceptions.
 ## Complexity
 
 1. Linear in the number of members: as for [`ordered_json`](../ordered_json.md), members are compared one after
-   another, in document order, scanning all of them, since the last match is wanted. Each comparison first checks the
+   another, in document order, stopping at the first match. Each comparison first checks the
    key's length -- already known from the index, without reading the key bytes -- before comparing its content.
 2. Linear in the number of reference tokens of `ptr` and, for each token, in the number of members of the object at
    that level or the index into the array -- as for [`operator[]`](operator[].md#complexity) and
@@ -41,6 +41,13 @@ No-throw guarantee: this function never throws exceptions.
 
 ## Notes
 
+!!! warning "Duplicate keys: the first member wins"
+
+    If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
+    [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
+    `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
+    the last value.
+
 Overload 1 always returns `#!cpp false` when the value is not an object -- including a [discarded](is_discarded.md)
 view.
 

docs/mkdocs/docs/api/basic_json_view/count.md

@@ -24,11 +24,18 @@ No-throw guarantee: this function never throws exceptions.
 ## Complexity
 
 Linear in the number of members: as for [`ordered_json`](../ordered_json.md), members are compared one after another,
-in document order, scanning all of them, since the last match is wanted. Each comparison first checks the key's length
+in document order, stopping at the first match. Each comparison first checks the key's length
 -- already known from the index, without reading the key bytes -- before comparing its content.
 
 ## Notes
 
+!!! warning "Duplicate keys: the first member wins"
+
+    If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
+    [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
+    `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
+    the last value.
+
 This method always returns `#!cpp 0` when the value is not an object -- including a [discarded](is_discarded.md)
 view.
 
@@ -36,7 +43,7 @@ Unlike [`BasicJsonType::count()`](../basic_json/count.md), whose return value ca
 an `ObjectType` that allows multiple entries per key, `count()` here never does: it is exactly
 [`contains()`](contains.md) as `#!cpp 0`/`#!cpp 1`. This holds even if the source text has a duplicate key -- see the
 [Notes on duplicate keys](operator[].md#notes) of `operator[]` -- because a `#!cpp count() > 1` result would require
-counting every member with a matching key (the lookup functions resolve to the *last* one).
+counting every member with a matching key (the lookup functions resolve to the *first* one).
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json_view/find.md

@@ -6,7 +6,7 @@ iterator find(const char* key) const;
 iterator find(const string_t& key) const;
 ```
 
-Finds a member with key `key` -- the last one, should the key occur more than once (see
+Finds a member with key `key` -- the first one, should the key occur more than once (see
 [Notes on duplicate keys](operator[].md#notes)). If the value is not an object, or no member has this key,
 [`end()`](end.md) is returned.
 
@@ -26,11 +26,18 @@ No-throw guarantee: this function never throws exceptions.
 ## Complexity
 
 Linear in the number of members: as for [`ordered_json`](../ordered_json.md), members are compared one after another,
-in document order, scanning all of them, since the last match is wanted. Each comparison first checks the key's length
+in document order, stopping at the first match. Each comparison first checks the key's length
 -- already known from the index, without reading the key bytes -- before comparing its content.
 
 ## Notes
 
+!!! warning "Duplicate keys: the first member wins"
+
+    If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
+    [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
+    `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
+    the last value.
+
 Unlike [`BasicJsonType::find`](../basic_json/find.md), which always returns `#!cpp end()` for a non-object type, this
 also does so for a [discarded](is_discarded.md) view -- there is no separate "invalid" iterator to return.
 

docs/mkdocs/docs/api/basic_json_view/get.md

@@ -87,9 +87,9 @@ exception thrown while converting through `materialize()` (the last bullet) is d
 !!! info "Duplicate keys"
 
     `#!cpp std::map`/`#!cpp std::unordered_map` conversions keep the *last* value of a repeated key, like
-    [`materialize()`](materialize.md) and [`BasicJsonType::parse()`](../basic_json/parse.md) do. This is the member
-    [`operator[]`](operator[].md)/[`at`](at.md)/[`find`](find.md)/[`contains`](contains.md) resolve to, too (see the
-    [Notes on duplicate keys](operator[].md#notes)).
+    [`materialize()`](materialize.md) and [`BasicJsonType::parse()`](../basic_json/parse.md) do. This is the opposite
+    of [`operator[]`](operator[].md)/[`at`](at.md)/[`find`](find.md)/[`contains`](contains.md), which resolve to the
+    *first* occurrence (see the [Notes on duplicate keys](operator[].md#notes)).
 
 !!! info "No pointers, references, or implicit conversion"
 

docs/mkdocs/docs/api/basic_json_view/items.md

@@ -48,7 +48,7 @@ Constant.
 
 As for [`begin()`](begin.md)/[`end()`](end.md), `items()` visits **every** member of an object, including all
 occurrences of a duplicate key -- unlike [`operator[]`](operator[].md), [`at`](at.md), [`find`](find.md),
-[`contains`](contains.md), and [`count`](count.md), which resolve to the *last* member with a given key. See the
+[`contains`](contains.md), and [`count`](count.md), which resolve to the *first* member with a given key. See the
 [Notes on duplicate keys](operator[].md#notes) of `operator[]`.
 
 !!! danger "Lifetime issues"
@@ -63,8 +63,8 @@ occurrences of a duplicate key -- unlike [`operator[]`](operator[].md), [`at`](a
 
     The example below shows a settings object whose source text records every update to a key as a duplicate
     member, in the order they happened. `items()` walks all of them, so the update history is visible, while
-    [`operator[]`](operator[].md) sees the *last* one, and so does [`materialize()`](materialize.md) -- like
-    [`BasicJsonType::parse()`](../basic_json/parse.md).
+    [`operator[]`](operator[].md) only ever sees the *first* one and [`materialize()`](materialize.md) -- like
+    [`BasicJsonType::parse()`](../basic_json/parse.md) -- keeps only the *last*.
 
     ```cpp
     --8<-- "examples/basic_json_view__items.cpp"

docs/mkdocs/docs/api/basic_json_view/operator[].md

@@ -15,7 +15,7 @@ basic_json_view operator[](IntegerType idx) const;
 basic_json_view operator[](const json_pointer& ptr) const;
 ```
 
-1. Returns the value of the object member with key `key` -- the last one, should the key occur more than once (see
+1. Returns the value of the object member with key `key` -- the first one, should the key occur more than once (see
    the [Notes](#notes) below) -- or a [discarded](is_discarded.md) view if there is no such member.
 2. Returns the array element at index `idx`, or a [discarded](is_discarded.md) view if `idx` is out of range. The
    template accepts every integer type except `#!cpp bool` and `#!cpp std::size_t` (`#!cpp int`, `#!cpp unsigned`,
@@ -38,7 +38,7 @@ basic_json_view operator[](const json_pointer& ptr) const;
 
 ## Return value
 
-1. the value of the last member with key `key`, or a discarded view if no member has this key (or if this view is
+1. the value of the first member with key `key`, or a discarded view if no member has this key (or if this view is
    [discarded](is_discarded.md))
 2. the element at index `idx`, or a discarded view if `#!cpp idx >= size()` or `idx` is negative (or if this view is
    [discarded](is_discarded.md))
@@ -80,7 +80,7 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
 ## Complexity
 
 1. Linear in the number of members: as for [`ordered_json`](../ordered_json.md), members are compared one after
-   another, in document order, scanning all of them, since the last match is wanted. Each comparison first checks the
+   another, in document order, stopping at the first match. Each comparison first checks the
    key's length -- already known from the index, without reading the key bytes -- before comparing its content, so a
    key of a different length than `key` is rejected without touching the source text.
 2. Linear in `idx`: elements are skipped one at a time from the first one, since they are not a fixed size in the
@@ -105,15 +105,18 @@ document.
     key on an array or a primitive, or an index on an object or a primitive, is `type_error.305` as for
     `BasicJsonType`. [`at`](at.md) still throws for a discarded view, as it does for a missing key.
 
-!!! info "Duplicate keys"
+!!! warning "Duplicate keys: the first member wins"
 
     If the source text has an object with a duplicate key, `#!cpp operator[]` (and [`at`](at.md), [`find`](find.md),
     [`contains`](contains.md), [`count`](count.md), [`value`](value.md), and JSON pointer resolution) all resolve to
-    the *last* member with that key. This is the member [`materialize()`](materialize.md) (and
-    [`BasicJsonType::parse()`](../basic_json/parse.md)) keeps, so a lookup in the view and in the materialized value
-    agree. [`begin()`](begin.md)/[`end()`](end.md) and [`items()`](items.md) iterate over *all* members, including
-    duplicates, in document order. A lookup scans all members for this: it cannot stop at the first match. See the
-    example below and [`size()`](size.md#notes).
+    the *first* member with that key, because a lookup can stop as soon as it finds a match. This is different from
+    [`materialize()`](materialize.md) (and [`BasicJsonType::parse()`](../basic_json/parse.md)), which replay every
+    member in order and so keep the *last* value for a repeated key, so `#!cpp v["a"]` and
+    `#!cpp v.materialize()["a"]` can differ. To get the value `parse()` would give, use
+    [`materialize()`](materialize.md) or iterate the members with [`items()`](items.md) and keep the last match.
+    [`begin()`](begin.md)/[`end()`](end.md) and [`items()`](items.md) iterate over *all* members, including
+    duplicates, in document order. See [Duplicate keys](../../features/json_view.md#duplicate-keys) and
+    [`size()`](size.md#notes).
 
 !!! info "JSON pointer resolution"
 

docs/mkdocs/docs/api/basic_json_view/value.md

@@ -12,7 +12,7 @@ T value(const json_pointer& ptr, const T& default_value) const;
 string_t value(const json_pointer& ptr, const char* default_value) const;
 ```
 
-1. Returns the value of the object member with key `key` -- the last one, should the key occur more than once (see
+1. Returns the value of the object member with key `key` -- the first one, should the key occur more than once (see
    [Notes on duplicate keys](operator[].md#notes)) -- converted to `T`, or `default_value` if there is no such member.
 2. Returns the value a JSON pointer `ptr` refers to, starting at this value, converted to `T`, or `default_value` if
    `ptr` cannot be resolved.
@@ -39,7 +39,7 @@ equivalent) deduce `string_t`, not `const char*`, for their return type and for
 
 ## Return value
 
-1. the last member with key `key`, converted to `T`, or `default_value`
+1. the first member with key `key`, converted to `T`, or `default_value`
 2. the value `ptr` resolves to, converted to `T`, or `default_value`
 
 ## Exception safety
@@ -68,7 +68,7 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
 ## Complexity
 
 1. Linear in the number of members: as for [`operator[]`](operator[].md#complexity), members are compared one after
-   another, in document order, scanning all of them, since the last match is wanted. Plus the complexity of converting
+   another, in document order, stopping at the first match. Plus the complexity of converting
    the found member to `T` (see [`get`](get.md)).
 2. Linear in the number of reference tokens of `ptr` and, for each token, in the number of members of the object at
    that level or the index into the array -- as for the [`operator[]`](operator[].md#complexity) and
@@ -77,6 +77,13 @@ None of these exceptions carry a [`JSON_DIAGNOSTICS`](../macros/json_diagnostics
 
 ## Notes
 
+!!! warning "Duplicate keys: the first member wins"
+
+    If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
+    [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
+    `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
+    the last value.
+
 !!! info "Differences to `at` and `operator[]`"
 
     Unlike [`at`](at.md), this function does not throw if `key`/`ptr` resolves to no value. Unlike

docs/mkdocs/docs/examples/basic_json_view__items.cpp

@@ -7,8 +7,8 @@ int main()
 {
     // a settings object whose source text records every update to a key as
     // a duplicate member. items() visits all of them, in document order, so
-    // the update history is visible; operator[] and materialize() -- like
-    // basic_json::parse() -- see the last one
+    // the update history is visible; operator[] only ever sees the first
+    // one, and materialize() -- like basic_json::parse() -- keeps the last
     json_document updates = json_document::parse(R"({"retries": 1, "timeout": 30, "retries": 5})");
     const auto settings = updates.root();
 
@@ -17,6 +17,6 @@ int main()
         std::cout << item.key() << '=' << item.value().materialize().dump() << '\n';
     }
 
-    std::cout << "last \"retries\" seen by operator[]: " << settings["retries"].materialize().dump() << '\n';
+    std::cout << "first \"retries\" seen by operator[]: " << settings["retries"].materialize().dump() << '\n';
     std::cout << "last \"retries\" kept by materialize(): " << settings.materialize()["retries"].dump() << '\n';
 }

docs/mkdocs/docs/examples/basic_json_view__items.output

@@ -1,5 +1,5 @@
 retries=1
 timeout=30
 retries=5
-last "retries" seen by operator[]: 5
+first "retries" seen by operator[]: 1
 last "retries" kept by materialize(): 5

docs/mkdocs/docs/features/json_view.md

@@ -134,16 +134,8 @@ document: `#!cpp auto v = json_document::parse(text).root();` does not compile.
   `operator[]` on a discarded view returns a discarded view without throwing: `#!cpp v["a"]["b"][0]` can be tested
   once at the end. Type errors on values that exist (a key on an array, an index on an object) still throw, and
   [`at`](../api/basic_json_view/at.md) throws for every missing value.
-- **Duplicate keys are visible.** If an object in the source text repeats a key,
-  [`begin()`](../api/basic_json_view/begin.md)/[`end()`](../api/basic_json_view/end.md) and
-  [`items()`](../api/basic_json_view/items.md) visit *every* occurrence (and [`size()`](../api/basic_json_view/size.md)
-  counts all of them), while [`operator[]`](../api/basic_json_view/operator%5B%5D.md),
-  [`at`](../api/basic_json_view/at.md), [`find`](../api/basic_json_view/find.md),
-  [`contains`](../api/basic_json_view/contains.md), and [`count`](../api/basic_json_view/count.md) resolve to the
-  *last* occurrence -- the one `basic_json::parse()` (and so
-  [`materialize()`](../api/basic_json_view/materialize.md)) keeps for a repeated key -- which makes a lookup scan all
-  members instead of stopping at a match.
-  See the [Notes on duplicate keys](../api/basic_json_view/operator%5B%5D.md#notes) of `operator[]`.
+- **Duplicate keys: lookups find the first member, `parse()` keeps the last.** See [Duplicate keys](#duplicate-keys)
+  below.
 - **No [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) path.** Exceptions thrown by `basic_json_view`'s own
   element access and lookup functions never carry the JSON Pointer path `JSON_DIAGNOSTICS` would otherwise add: the
   view has no `basic_json` value to point at, so the exception is created without one, regardless of how
@@ -151,6 +143,51 @@ document: `#!cpp auto v = json_document::parse(text).root();` does not compile.
 - **`dump()` and comparison are not (yet) provided** by `basic_json_view`. For now,
   [`materialize()`](../api/basic_json_view/materialize.md) is the way to get a value you can do those things with.
 
+## Duplicate keys
+
+!!! warning "A lookup in a view and in the parsed value can give different answers"
+
+    If an object in the source text repeats a key, [`operator[]`](../api/basic_json_view/operator%5B%5D.md),
+    [`at`](../api/basic_json_view/at.md), [`find`](../api/basic_json_view/find.md),
+    [`value`](../api/basic_json_view/value.md), [`contains`](../api/basic_json_view/contains.md),
+    [`count`](../api/basic_json_view/count.md), and JSON pointer resolution all return the **first** member with that
+    key. `basic_json::parse()` instead keeps the **last** value of a repeated key, so for `#!cpp {"a":1,"a":2}`,
+    `#!cpp view["a"]` is `#!cpp 1` while `#!cpp parse(text)["a"]` is `#!cpp 2`.
+
+[`begin()`](../api/basic_json_view/begin.md)/[`end()`](../api/basic_json_view/end.md) and
+[`items()`](../api/basic_json_view/items.md) visit *every* occurrence, in document order, and
+[`size()`](../api/basic_json_view/size.md) counts all of them, so `#!cpp view.size()` can be larger than
+`#!cpp view.materialize().size()`.
+
+**Why the first?** A lookup can stop as soon as it finds a match. Returning the last member would force every lookup
+to scan all members of the object, even when the key is found at the very first one: this made lookups in small
+objects 1.6 to 3.4 times slower. Other zero-copy parsers that index the source text, such as yyjson and simdjson, also
+return the first member. RFC 8259 only says that names within an object SHOULD be unique and that the behavior of a
+receiver that sees duplicates is unpredictable, so neither choice is wrong.
+
+**What stays the same as `parse()`?** [`materialize()`](../api/basic_json_view/materialize.md) and
+[`get<std::map<...>>()`](../api/basic_json_view/get.md) replay every member in order, so they keep the *last* value
+exactly like `#!cpp basic_json::parse()` (at the position of the first occurrence of the key, for an
+[`ordered_json`](../api/ordered_json.md)).
+
+**How do I get the value `parse()` would give?** Either call `#!cpp view.materialize()` and look the key up in the
+result, or iterate the members and keep the last match:
+
+```cpp
+// the last member with the key "a", as parse() would keep it
+json_view last;
+for (const auto item : view.items())
+{
+    if (item.key() == "a")
+    {
+        last = item.value();
+    }
+}
+```
+
+If you cannot trust the source text to have unique keys, check [`size()`](../api/basic_json_view/size.md) against the
+number of distinct keys, or reject duplicates when iterating.
+
 ## Getting values out without copying
 
 [`get<T>()`](../api/basic_json_view/get.md) converts many `T` directly from the flat index, without ever building a