1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
//! The set fold's MECHANISM: [`Bests`], and the two accumulators a declaration chooses between —
//! [`Seen`](super::Seen)'s family one grain over.
use HashMap;
use crateScored;
/// A KEYED ACCUMULATOR over the entities a set query has scored so far — the fold's one moving part.
///
/// # Why an accumulator and not the membership beside it
///
/// The dedup stage asks *have I seen this key* and drops the second sighting; the set fold asks
/// *what has this key scored so far* and COMBINES the second sighting into the first. The two
/// questions want the same capability of a key — some way to tell two of them apart — and different
/// things of the container, so [`Seen`](super::Seen) answers one and this answers the other. The
/// grain is the reason both exist: a set query runs the engine once per QUERY VECTOR, so one entity
/// legitimately appears in several of the engine's answers, and collapsing it the dedup's way would
/// throw away every contribution but the first.
///
/// # Why the mechanism is DECLARED rather than fixed
///
/// It is the same BOUNDS choice on the key type the dedup word already makes, which is why the same
/// word makes it:
///
/// | word | this trait's implementor | what the key must satisfy |
/// |---|---|---|
/// | `dedup(hash)` | [`HashBests`] | [`Hash`](core::hash::Hash) + [`Eq`] |
/// | `dedup(eq)` | [`EqBests`] | [`PartialEq`] |
///
/// A declaration that reached for `eq` because its key cannot hash must not find the set road
/// closed to it for the same reason, and a declaration on `hash` must not silently pay a linear
/// scan. So the word picks both members of the pair, and a framework widening is an ARM — an
/// ordered accumulator arrives as one more implementor of this trait beside one more implementor of
/// [`Seen`](super::Seen), and no signature above either moves.
///
/// # No `Clone` on either row, which is where the two families differ
///
/// A membership holds a COPY of every key the survivor list also holds, so both its implementors
/// bound `K: Clone`. An accumulator holds the key ITSELF — the fold's output is the accumulator's
/// contents rather than a list beside it — so nothing here clones and nothing here asks a key to be
/// cloneable.
/// `dedup(hash)` — accumulation through a [`HashMap`], the default.
///
/// Two hashes per sighting rather than one, which is the price of taking the running total OUT to
/// combine it: an occupied entry cannot lend its value to a closure that consumes it and put the
/// result back through the same borrow. A stream of any size still wants this over the scan below.
;
/// `dedup(eq)` — accumulation through a list walked by field-wise equality.
///
/// Quadratic in the number of DISTINCT ENTITIES, stated rather than hidden exactly as
/// [`EqSeen`](super::EqSeen) states its own: it is the price of asking only [`PartialEq`] of the
/// key, the entity count is bounded by what a retrieve returns rather than by the corpus, and a
/// declaration reaches for this word when the alternative is not retrieving at all.
///
/// The remove-and-reinsert is what keeps FIRST-SIGHTING ORDER, which costs a shift per repeat
/// sighting on a container that is already linear to search. Order is not load-bearing for the
/// answer — [`drain`](Bests::drain) promises none and the fold sorts afterwards — but it is what
/// makes a tie between two equal set scores resolve the same way twice.
;