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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
//! [`NormCoord`]: a coordinate in the closed unit interval, and the one instantiation of this
//! family's parameter that the crate NAMES.
use ;
use crate::;
/// **A NORMALIZED COORDINATE** — one axis of a position in the unit square, in `[0.0, 1.0]`.
///
/// An [`f32`] underneath, and a different type for the reason every newtype in
/// [`primitives`](crate::primitives) is one: it carries an INVARIANT its representation cannot
/// state. A coordinate is FINITE and lies in the closed unit interval, so [`new`](Self::new) is the
/// only way in and it refuses everything else. That refusal is what buys the total order below —
/// with `NaN` excluded, `partial_cmp` never answers [`None`], so [`Ord`] is a fact about the type
/// rather than a convention its users have to keep.
///
/// # It is ONE INSTANTIATION and not the family's subject
///
/// [`BoundingBox`](super::BoundingBox), [`Point2`](super::Point2) and [`Quad`](super::Quad) are
/// GENERIC over their component, and this type is one thing a caller may put there. A detector
/// working in the normalized frame writes `BoundingBox<NormCoord>`; a metric one writes
/// `BoundingBox<f64>`; a raster one writes `BoundingBox<u32>` and has no unit square to be checked
/// against. **The openness is the holders', and this is the normalized world's answer to it** — the
/// crate names no other, because naming a metre or a pixel would be naming a UNIT this framework
/// has no reason to hold an opinion about.
///
/// # `-0.0` is admitted and NORMALISED, which is what keeps `Hash` and `Eq` in agreement
///
/// It satisfies the range check, compares equal to `+0.0`, and carries different bits — so
/// admitting it unchanged would make two equal values hash differently. `+ 0.0` maps it to `+0.0`
/// and is the identity everywhere else in the interval. That is
/// [`Confidence`](crate::Confidence)'s own clause at this width, and it is spent here for the same
/// reason rather than because the two types are one.
///
/// # Why it is not a [`Confidence`](crate::Confidence)
///
/// The two invariants read the same — a finite number in `[0.0, 1.0]` — and the types are
/// deliberately distinct, which is the position [`MediaTimestamp`](crate::MediaTimestamp) holds
/// against [`Timestamp`](crate::Timestamp) one house over. A confidence is a DEGREE OF BELIEF and a
/// coordinate is a POSITION; `BoundingBox<Confidence<f32>>` would be a box of beliefs, and GraphQL's
/// one flat namespace would publish the box's four fields under a name that says a detector's
/// certainty where it means its left edge. The shared interval is a coincidence of arithmetic, not
/// one invariant with two names.
///
/// # Examples
///
/// ```
/// use ingraph::NormCoord;
///
/// assert_eq!(NormCoord::new(0.25).unwrap().get(), 0.25);
/// assert_eq!(NormCoord::ZERO.get(), 0.0);
/// assert_eq!(NormCoord::ONE.get(), 1.0);
///
/// assert!(NormCoord::new(1.5).is_none());
/// assert!(NormCoord::new(-0.1).is_none());
/// assert!(NormCoord::new(f32::NAN).is_none());
/// assert!(NormCoord::new(f32::INFINITY).is_none());
/// ```
///
/// The negative zero is admitted and arrives as the positive one:
///
/// ```
/// use ingraph::NormCoord;
///
/// let signed = NormCoord::new(-0.0).unwrap();
/// assert_eq!(signed, NormCoord::ZERO);
/// assert!(signed.get().is_sign_positive());
/// ```
;
/// The coordinate, as the plain number.
///
/// ONE direction, and the missing one is the type's whole subject: `From<f32> for NormCoord` would
/// say that any float IS a coordinate, which is exactly the claim this newtype exists to stop being
/// made silently. Minting one is [`NormCoord::new`], where the caller meets the refusal.
/// The widening every consumer that measures in doubles reaches for, and it is EXACT: every `f32`
/// is an `f64`, so nothing about the value moves and the interval is preserved by construction.
// `PartialEq` is derived and `Eq` is not, for `Confidence`'s reason: `f32`'s equality is already the
// right one here, and its REFLEXIVITY is a property of THIS type rather than of the float — `x == x`
// fails for `NaN` alone, and a coordinate is never one.
/// **THE ONE ARITHMETIC THE UNIT INTERVAL IS CLOSED UNDER**, and the whole reason this row exists is
/// [`BoundingBox::area`](super::BoundingBox::area).
///
/// A product of two values in `[0.0, 1.0]` is in `[0.0, 1.0]` — the true product is at most either
/// factor, rounding to nearest is monotone, `1.0` is representable, and neither factor can be `NaN`
/// or an infinity — so this operator is TOTAL and the [`new`](Self::new) below it never refuses. The
/// `expect` is a proof obligation discharged by the constructor that refused every value which could
/// break it, which is [`BoundingBox::right`](super::BoundingBox::right)'s own arrangement one door
/// over.
///
/// # WHY NO `Add`, `Sub` OR `Div` FOLLOW IT — the census, stated where a reader will look
///
/// **None of the other three is closed on this interval**, and the type will not publish an operator
/// that leaves its own domain. `0.6 + 0.7` is `1.3`, `0.2 - 0.8` is `-0.6`, `0.5 / 0.1` is `5.0`;
/// each would have to panic, saturate or clamp, and a coordinate that quietly became `ZERO` because
/// somebody subtracted in the wrong order is precisely the *value minted around the hole* this
/// house's decode refuses one screen down.
///
/// The visible consequence is [`Quad::bounds`](super::Quad::bounds), whose extents are `max - min`
/// and which is therefore bounded on a component whose subtraction is total: `f32`, `f64`, a pixel
/// width, a downstream newtype that says so — and NOT this type. That is out of bounds rather than
/// refused, and it is recorded at that method.
///
/// # It is a POSITION and a product of two of them is not one, which is the pun this row admits
///
/// Stated rather than hidden: multiplying two COORDINATES means nothing, and what is multiplied at
/// the one call site is two EXTENTS — a width and a height, both measured as fractions of the frame,
/// whose product is the fraction of the frame the rectangle covers. So the operator is honest about
/// its arithmetic and narrow about its meaning, and the meaning is documented at
/// [`BoundingBox::area`](super::BoundingBox::area) where it is spent.
///
/// # Examples
///
/// ```
/// use ingraph::NormCoord;
///
/// let half = NormCoord::new(0.5).unwrap();
/// assert_eq!((half * half).get(), 0.25);
/// assert_eq!((NormCoord::ONE * half).get(), 0.5);
/// assert_eq!((NormCoord::ZERO * half).get(), 0.0);
/// ```
/// **A SCALAR joins by stating NOTHING** — one column, wherever it is stored.
///
/// The empty segment list is [`ColumnKind`]'s default and this row spells it anyway, because the
/// three holders above are guarded by a leaf assertion read off exactly this const: a component
/// that came to span two columns would break their fixed arity, and the row a reader checks that
/// against should be the type's own rather than a default they have to know about.
// A coordinate is the same as a coordinate when its bits are — `-0.0` is normalised to `+0.0` at
// construction, so this type's own derived `PartialEq` already agrees with its `Hash`.
column_eq!
/// **THE STORED WORD is the float's**, in every dialect that has one.
///
/// A coordinate is an `f32` in the column and a `NormCoord` in the row, and the interval is kept by
/// the DECODE rather than by the schema — no dialect here has a `CHECK` this crate emits, so the
/// promise is enforced where a value crosses back in. See the assemble row below, which refuses.
/// **ONE BIND OUT** — the float, delegated.
/// **AND THE VALUE BACK IN**, through the constructor rather than around it.
///
/// A database is exactly the place that can hand back a number this type says cannot exist — a
/// hand-written `UPDATE`, a restore, a column shared with something else — so the read refuses
/// rather than clamping into range. That is [`Count`](crate::Count)'s posture at its own column and
/// [`MediaTimeRange`](crate::MediaTimeRange)'s at its pair: loudly, at the row that holds it, never
/// a value quietly minted around the hole.
/// **THE KEYSET POSITION** — the float's own bytes, and the order they sort in is the order the
/// values have.
///
/// [`f32`]'s row is what encodes it, and a coordinate inherits the encoding rather than restating
/// it: the two are one number, and a second spelling here is a second thing to keep in agreement.
/// **THE ADMISSION** — a coordinate is one element of one.
///
/// `Vec<NormCoord>` is a polyline's x's, a histogram's bin edges, a sampling grid. Nothing about
/// the value refuses a list of them, and the row that says so is one line.
/// **The SCALAR reading**, which is what a total order earns.
///
/// A coordinate has `gt`/`gte`/`lt`/`lte` that mean what they say — *the left edge is past the
/// midline* is a question — so it takes the uniform [`ScalarFilter`](crate::ScalarFilter) rather
/// than a kind of its own. The INTERVAL is not restated as a filter word: an operand outside it is
/// refused at the crossing below, which is where a value becomes this type.
/// **THE CROSSING IN — a coordinate arrives as the roster's own `f32`**, and the interval is kept
/// HERE.
///
/// No `#[Scalar]` of its own, and the absence is the [`Score`](crate::Score) retirement's ruling
/// rather than an omission: a named scalar has to say something the roster does not, and what a
/// `NormCoord` scalar would have said is the INTERVAL — a constructor's promise rather than a
/// grammar, which a client can act on nowhere. So a coordinate column and a plain `f32` column
/// publish one SDL scalar, the interval reaches a reader through the FIELD's documentation, and
/// every operand reaches it through [`NormCoord::new`], which this row calls.
/// **AND OUT**, mirroring the row above so the two directions cannot come to disagree.
///
/// BY VALUE rather than by reference, which is the carrier shape and costs a register move: a
/// coordinate is [`Copy`].
/// **What a coordinate refuses a value with** — one sentence, at the two doors that mint one from
/// the outside: a stored column and a wire operand.
///
/// It carries no value, which is [`OutsideTheInterval`](crate::OutsideTheInterval)'s own shape and
/// its reason: what is wrong is a property of the number the caller already has in hand, and a copy
/// of it here would be a second spelling of the same digits. The COLUMN's name arrives with the
/// [`sqlx::Error::ColumnDecode`] this is wrapped in, and a wire operand travels back to a client in
/// async-graphql's own error context.
;