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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
//! The three facts a STORED composite states about itself, and the one authority all of them read:
//! how many columns a [`Timebase`] spans, how those columns are bound out, and how they are read
//! back in.
//!
//! ```text
//! SEGMENTS num, den the width — what a holder's INSERT list and DDL name
//! Carrier ?, ? the bind — one placeholder per segment, the comma between them ours
//! Assemble num → i32 ← den the decode — read by NAME, so a transposition cannot typecheck away
//! CursorValue 8 bytes the keyset position, big-endian, exactly as the columns hold it
//! ```
//!
//! # ONE list, read four ways
//!
//! [`SEGMENTS`] is the whole of what makes those four agree. The comparison pushes a frame per
//! entry, the row puts a column per entry, the bind pushes a placeholder per entry and the decode
//! reads one per entry — so a rename here moves `WHERE tb_num = ?`, `SELECT tb_num`, the `VALUES`
//! width and the read together. Nothing counts the columns; the list is the count.
//!
//! # What is gated and what is not
//!
//! The width and the cursor position are UNGATED, because neither names a database: a composite
//! spans two columns wherever it is stored, and a keyset position is bytes. The bind and the decode
//! ride the `sqlx` feature, because both are written against sqlx's own types — a `QueryBuilder` and
//! a `Row` — and a build with no SQL family has neither.
//!
//! # The bind writes the REDUCED pair, and it is the same reduction the crossing binds
//!
//! [`Timebase::reduced`] is THE authority, and it is public so that this path and the query path can
//! call the same one rather than each dividing correctly. Reducing on one side only is a SILENT
//! MISS: a row written from `2/180000` and a filter binding `1/90000` simply never meet, with no
//! error and no wrong value to look at.
//!
//! What that costs is the pair the stream DECLARED, which storage does not keep — see
//! [`Timebase`]'s [`Display`](core::fmt::Display), which does.
use ;
use crate::;
use mediatime as mt;
use Timebase;
/// The numerator's segment — the name a frame pushes and a column carries.
///
/// `pub(crate)` rather than `pub(super)`, because the citizens that NEST this one address these
/// columns directly: a timestamp's `exact` facet binds the timebase halves beside the `pts`, and it
/// reads the names from here rather than respelling them — one authority, at every depth.
pub const NUM: &FieldName = new;
/// The denominator's segment.
pub const DEN: &FieldName = new;
/// **The two columns a timebase spans**, and the one authority every half of the crossing reads.
///
/// `num` and `den` rather than the wire's `numerator`/`denominator`, and the difference is which
/// side of the crossing each vocabulary belongs to: a column name is DDL a database already holds,
/// where a field name is a schema commitment to a client. The wire took the longer spelling because
/// `mediatime`'s own serde face publishes those two names; the columns keep the short ones because
/// renaming a column is a migration and this cut is not one.
pub const SEGMENTS: & = &;
/// **The STORAGE half of the width** — what a holder's row reads to know this field is two columns
/// and not one. It names no dialect, because a width has none.
/// **One leaf, and it is the value.** A timebase means numerator then denominator, which is the sequence it is written in — the
/// citizen that NESTS this one is the one with a sequence to state, and it states its own.
// Two timebases are one column value when they are the same rational — `mediatime`'s own
// `PartialEq` cross-multiplies rather than comparing the pair as written, so `2/180000` and
// `1/90000` already answer equal here exactly as `reduced()` makes them one row.
column_eq!
/// **The DECLARED half of the same two columns** — the words a `CREATE TABLE` spells them with, one
/// per segment above.
///
/// Both halves are `i32`, so the words are that width's own in whichever dialect is asked rather
/// than a spelling written here: the numerator and a non-zero denominator are what the
/// [`Carrier`](crate::Carrier) row binds, and a dialect that stores an `i32` differently moves this
/// row with it. Generic over the dialect for the reason the carrier row is — nothing in the
/// delegation is per-dialect, and the arity is fixed at two.
/// A pair of columns does not hold a timebase, and this says which invariant they broke.
///
/// The two are the constructor's two, met on the way IN from a database rather than on the way in
/// from a client: `mediatime` refuses a negative half and [`NonZeroI32`] refuses a zero denominator,
/// and a column is an `INTEGER` that can hold either. So a decode has to test what the type
/// guarantees, and the alternative — trusting the column — is a `Timebase` whose invariants are a
/// hope about someone else's DDL.
///
/// It is a decode error rather than a parse error, and it is a separate type from
/// [`ParseTimebaseError`](super::ParseTimebaseError) for that reason: nothing here was spelled, so
/// there is no separator to be missing and no half that failed to be an integer. What is left is
/// exactly the two domain rules.
/// The two columns as one value, or the invariant they broke.
///
/// Shared by the two readers below — the row decode and the cursor — so that a timebase arriving
/// from a database and one arriving from a client's page token are admitted by the same rule.
/// **The KEYSET position**: eight bytes, two big-endian `i32`s, in the order [`SEGMENTS`] names.
///
/// A page resumes by binding the last row's values back, so what is written here is what the COLUMNS
/// hold — the reduced pair — and not the declared one. A cursor carrying `2/180000` where the row
/// holds `1/90000` would compare against a value no column has.
///
/// FIXED WIDTH, which is what makes the read total, and the DOMAIN is checked on top of the width: a
/// cursor is a string a CLIENT hands back, so seven bytes are refused rather than zero-extended, and
/// a forged `den` of zero is refused rather than turned into a `Timebase` whose type says it cannot
/// exist.
/// **N BINDS OUT.** The engine's `VALUES` loop writes the comma between FIELDS; the comma between a
/// field's own columns is this one, because the count is this type's — so a holder's `INSERT` names
/// `tb_num, tb_den` and binds `?, ?` with neither list told the number.
///
/// Generic over the dialect where the fixture that models this names one concretely, and the
/// difference is coherence rather than taste: that fixture also serves MongoDB, whose marker is
/// foreign to it, so its two headers would overlap. This crate ships one family, so one header
/// serves it — and `i32: Carrier<Db>` is the whole requirement, both halves being `i32` by
/// construction.
/// **AND N COLUMNS BACK IN** — the bind above read the other way, and the third fact a stored
/// composite states.
///
/// Generic over the ROW where the bind is generic over the DIALECT, and the asymmetry is the two
/// traits' parameters rather than a choice made here: a bind is a dialect's fact, while a read is
/// [`sqlx::Row`]'s method.
///
/// `under` arrives carrying the holder's own segment for a field that lends its name, and carrying
/// nothing extra for one marked `flatten` — so this one body serves both without knowing which it is
/// reading. By NAME in both cases, which is what a transposition cannot survive: both columns are
/// integers, so `num` and `den` read positionally would swap without a type error anywhere.