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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
//! The framework's CARDINALITY: [`Count`], and the refusal a stored one that is not a count earns.
/// **HOW MANY — a cardinality, and the currency every count in this framework is answered in.**
///
/// A [`u64`] underneath, and a different type on purpose. What the newtype adds is an INVARIANT its
/// representation cannot state: *a cardinality counts rows that EXIST*, so it is bounded by the
/// physical store — no database holds 2^63 rows, and no walk this framework makes produces a count
/// that is not a length of something already in memory. **Its dialect crossings are allowed to spend
/// that invariant, which is exactly what a bare `u64`'s crossings must not.**
///
/// That one sentence is the whole difference, and it is why this type exists rather than an sqlx
/// `Encode` row for `u64`. A bare `u64` is an ARBITRARY 64-bit magnitude — a hash, a file offset, an
/// id minted by something else — and the top half of its range is ordinary traffic, so narrowing one
/// into an `i64` is a value silently lost. That is why `u64` has no SQLite or PostgreSQL carrier at
/// all and why [`BeU64`](crate::BeU64) is the escape a `u64` column declares.
/// A `Count` is not arbitrary. It is bounded by a fact about the machine, so the same narrowing
/// crosses no information at all — and the saturating arm below is DOCUMENTED UNREACHABLE rather
/// than merely improbable.
///
/// # Its per-dialect knowledge lives in its CARRIER ROWS, which is where every type's does
///
/// There is no new trait here and no associated type threaded through the fold contract. A `Count`
/// column is `Count` in every dialect — the width is one — and each backend's family states how one
/// binds:
///
/// | dialect | stored as | the crossing |
/// |---|---|---|
/// | MySQL | `BIGINT UNSIGNED` | native, identity — the value is the column |
/// | SQLite | `INTEGER` | [`to_signed`](Self::to_signed), saturating; [`from_signed`](Self::from_signed) on the way back |
/// | PostgreSQL | `int8` | the same pair |
/// | MongoDB | `Int64` | [`to_signed`](Self::to_signed), the same authority |
///
/// One codec and it belongs to the type, which is [`BeU64::to_blob`](crate::BeU64::to_blob)'s own
/// law one house over: four families each writing `i64::try_from(…)` into their own row would be
/// four encodings that agree today and are free to stop.
///
/// # A NEGATIVE stored value is a CORRUPT ROW, and it is refused by name
///
/// Nothing that wrote through [`to_signed`](Self::to_signed) can produce one — the narrowing
/// saturates at [`i64::MAX`] and has no negative arm — so a negative column is a row this code did
/// not write: a hand-edited database, a column shared with something else, a bit flip. The read
/// refuses it as [`NegativeCount`] rather than clamping to zero or reinterpreting the bits, which is
/// `NonZeroColumnError`'s own posture one type over: loudly, at the row that holds it, never a value
/// quietly minted around the hole.
///
/// # The API is what has been ASKED FOR, and no arithmetic suite stands beside it
///
/// A count is produced by a fold and read back out of a column. It is not added to, not multiplied,
/// and not counted down — so there is no `Add`, no `Sum` and no `checked_*` family here. The day one
/// is demanded it is one impl; a suite written ahead of the demand is a surface with no caller to
/// hold it honest, which is the rule the module above grows by.
///
/// # Examples
///
/// ```
/// use ingraph::Count;
///
/// let tracks = Count::new(3);
/// assert_eq!(tracks.get(), 3);
/// assert_eq!(u64::from(tracks), 3);
/// ```
///
/// The stored form is signed, and the saturation is the arm no count reaches:
///
/// ```
/// use ingraph::Count;
///
/// assert_eq!(Count::new(7).to_signed(), 7);
/// assert_eq!(Count::new(u64::MAX).to_signed(), i64::MAX);
/// assert_eq!(Count::from_signed(7), Ok(Count::new(7)));
/// assert!(Count::from_signed(-1).is_err());
/// ```
;
/// The count, as the plain magnitude — [`get`](Count::get) in the spelling a generic caller writes.
///
/// ONE direction, and the missing one is the type's whole subject: `From<u64> for Count` would say
/// that any 64-bit magnitude IS a cardinality, which is exactly the claim this newtype exists to
/// stop being made silently. Minting one is [`Count::new`], where the caller writes the word.
/// **Why a stored column is not a cardinality** — the read-path refusal a [`Count`] column makes,
/// and the only value it has to make one about.
///
/// It carries the value it refused, because that value is the evidence: a reader looking at a
/// corrupt row wants to know what was in it, and the column's own NAME arrives with the
/// `sqlx::Error::ColumnDecode` this is wrapped in. `NonZeroColumnError` carries nothing for the
/// opposite reason — there is only one value it can be about.