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
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
//! [`Radians<T>`]: a neutral ANGLE, carried in whatever `T` a declaration measures in — the
//! geometry house's second independent citizen, beside [`NormCoord`](super::NormCoord) rather than a
//! second reading of it.
//!
//! # It carries no invariant, and that is the ruling rather than an oversight
//!
//! [`NormCoord`](super::NormCoord) and [`Confidence`](crate::Confidence) both narrow their carrier
//! to a closed interval and both buy a total order by refusing `NaN`. An angle has no such interval
//! to be inside of: a roll, a yaw, a bearing, a rotation a matrix decomposes into — every one of them
//! is *some real number of radians*, unbounded and sign-carrying, and a producer that wants
//! `[-π, π]` or `[0, 2π)` or an unwrapped running total all want DIFFERENT normalisations that this
//! type has no business choosing between. So [`new`](Self::new) is `const fn` and refuses nothing:
//! the invariant this newtype states is the UNIT alone — *this value is radians and not degrees, not
//! turns, not an unmeasured number* — and normalisation stays where it has always been, at the
//! producer that knows which convention its own geometry wants.
//!
//! # A DUMB GENERIC HOLDER, on [`BoundingBox<T>`](super::BoundingBox)'s own idiom at ONE field
//!
//! `Radians(f32)` (#491) reshapes to `Radians<T>` on the standing law this family already states for
//! [`BoundingBox`](super::BoundingBox), [`Point2`](super::Point2) and [`Quad`](super::Quad): carriers
//! are generic and an invariant lives on the COMPONENT, never on the holder. [`new`](Self::new)
//! checks NOTHING and stays `const fn` — a `Radians<f64>` measured in a fusion pass's own wider width
//! and a `Radians<f32>` measured in a detector's are built the same way, and a holder that refused
//! one width for leaving some range would be a holder with an opinion about a unit it was never told.
//!
//! Unlike its three composite neighbours, this holder does not FAN a component out into several
//! columns: [`BoundingBox<T>`](super::BoundingBox) stores four `T`s and a derived fifth,
//! [`Point2<T>`](super::Point2) two, [`Quad<T>`](super::Quad) eight — so none of their fixed-arity
//! machinery applies here (the leaf guard, the per-slot indexing, an `OrderLeaves` tuple). ONE
//! `Radians<T>` is ONE `T` — no more columns, no derived leaf, no order of its own — so every face
//! below is a straight, TOTAL delegation to `T`'s own face, over however many columns T's own already
//! is. That is a stronger transparency than the three composites can offer, and it is why their leaf
//! guard has no counterpart here: nothing about a `Radians<T>` could ever disagree with `T`.
//!
//! # NO DEFAULT TYPE PARAMETER, on [`BoundingBox<T>`](super::BoundingBox)'s own ruling
//!
//! `Radians` bare does not compile, and the absence is a ruling rather than an oversight. A default
//! would make `f32` the SILENT reading of a type whose whole subject is that the width is the
//! producer's to name — [`BoundingBox<T>`](super::BoundingBox) already answered this question the
//! same way for the same reason; see its own note, which this one does not repeat. The two customers
//! this crate has actually met — a face's `roll`/`yaw`/`pitch`, a horizon's `angle` — measure in
//! `f32` and now spell `Radians<f32>`, the one syllable every `BoundingBox<NormCoord>` caller already
//! pays.
//!
//! # No `Eq`, `Ord` or `Hash` — for every `T` this holder is generic over
//!
//! Those three exist on [`NormCoord`](super::NormCoord) and [`Confidence`](crate::Confidence) because
//! their constructors refuse `NaN`, which is the one value that breaks a float's reflexivity and
//! totality. [`new`](Self::new) refuses nothing at any width, so `Radians<T>` is exactly as ordered
//! as the `T` it wraps — `#[derive(PartialEq, PartialOrd)]` and no more, which is the honest position
//! `f32` and `f64` are already in throughout this crate and the position a downstream `T` with no
//! `Eq` of its own is entitled to keep.
//!
//! # The wire VALUE crosses on `T`'s own roster reading, and the FILTER wears ONE fixed name
//!
//! `Radians<T>` publishes no scalar of its own: a value crosses as `T`'s own reading under
//! [`Builtin`](crate::Builtin) — `f32` for `Radians<f32>`, `f64` for `Radians<f64>` — on the ruling
//! that retired [`Score`](crate::Score)'s four named scalars: a dedicated scalar would have to say
//! something the roster does not, and the one thing an angle's scalar could say is the UNIT, which
//! belongs in this type's own documentation and in the field that names it rather than in a grammar a
//! client parses against.
//!
//! **The FILTER answers the other way, and it is FIXED rather than composed per `T`.**
//! [`ScalarFilter<Radians<T>>`](crate::ScalarFilter)'s GraphQL name is `RadiansFilter` for every
//! width, and that is a MECHANICAL finding rather than a style choice: [`ScalarWire::NAME`] is a
//! plain `const &'static str`, so nothing short of one hand-written impl per concrete width could
//! make it read `T`'s own name, and `concat!` — the tool [`derived_filter!`](crate::graphql::scalar)
//! composes the roster's OWN per-width names with — accepts only literal tokens, never a generic
//! parameter's associated const. So a per-`T` name of the kind
//! [`BoundingBoxF32Filter`](super::BoundingBoxFilter) composes is not written here because it is not
//! WRITABLE here, for the same wall the composites' own names cross with a runtime `format!` and this
//! trait's const cannot.
//!
//! That leaves two houses to weigh, and this type picks the one closer to the problem it already
//! solved once. [`ConfidenceFilter`](crate::ConfidenceFilter) collapsed FOUR real, GraphQL-exposed
//! widths into one hand-written, non-generic Rust type specifically so a schema holding more than one
//! of them would have one name for one type — a real collision, addressed by erasing the width from
//! the FILTER entirely. `Radians<T>` has ONE real customer (`f32`) and no second one asking for wire
//! exposure today, so erasing the width would spend a widthless operand type
//! ([`ConfidenceOperand`](crate::ConfidenceOperand) is not a small one) on a problem this type does
//! not yet have. Keeping the name FIXED and the impl GENERIC over every `T` with its own [`Builtin`]
//! reading is the smaller move: `Radians<f32>` keeps the exact name #491 published, `Radians<f64>`
//! (this file's own smoke width) gets the SAME machinery for free, and the one thing a fixed name
//! costs — `Registry::create_type` panicking if two DIFFERENT widths of `Radians` were ever exposed
//! in ONE schema — is a risk no caller has hit and the same risk any two unrelated types sharing a
//! name would run. If a second width becomes a real GraphQL customer, [`ConfidenceFilter`]'s road is
//! the one to take then; nothing here forecloses it.
//!
//! # `to_degrees`/`to_radians` are INHERENT on `f32`/`f64`, so a bound had to be MINTED
//!
//! No trait in `core` names `to_degrees`/`to_radians` — both are inherent methods on `f32` and `f64`
//! separately — so an unbounded `T` cannot spell either at all, and there is no pre-existing bound in
//! this crate to census and reuse: a search of the whole workspace for the pair outside this file
//! turns up nothing, and `T: Into<f64> + From<f64>` — the obvious std-`ops` road — does not compile
//! at the real customer either, `f32: From<f64>` not existing (the narrowing has no lossless
//! direction for `From` to name). [`RadianMath`] is the trait this file mints to answer it — one pair
//! of methods, named for the inherent ones they lift, and OPEN rather than sealed: unlike
//! [`ConfidenceCarrier`](crate::ConfidenceCarrier), which seals a vocabulary it has to MEASURE
//! (which values are not numbers, which two compare equal on different bits), converting between
//! degrees and radians is one unconditional identity with nothing to measure, so a downstream width
//! joins by implementing it — the ordinary extension seam, not a closed one.
//!
//! # The widening `From` a concrete `T` COULD publish is not one a generic `T` can
//!
//! `Radians(f32)`'s `From<Radians> for f32` does not survive the reshape, and the reason is the
//! orphan rule rather than a change of mind: `impl<T> From<Radians<T>> for T` puts the bare parameter
//! `T` in `Self` position, UNCOVERED, ahead of the first LOCAL type in the impl
//! (`Radians<T>`, one type over) — exactly the shape [`E0210`] refuses, because nothing local anchors
//! the impl until after the parameter it would have to cover has already appeared bare. A concrete,
//! per-width `impl From<Radians<f32>> for f32` would still compile — there is no parameter left to be
//! uncovered — but writing one is the per-concrete-type road this reshape is retiring everywhere
//! else, so [`get`](Self::get) stays the one honest, total extraction this generic form publishes,
//! and the widening test now reads it back through that door instead.
//!
//! [`E0210`]: https://doc.rust-lang.org/error_codes/E0210.html
//!
//! # No serde row, on this crate's own law
//!
//! No storage type this crate ships carries one — see
//! [`primitives::detect::Label`](crate::primitives::detect::Label)'s own note, where the sentence is
//! first spent, and the `serde` feature's manifest row, which states it for the crate whole: *nothing
//! in this crate uses serde, and nothing in its API becomes `Serialize`*. A generated document's
//! write is serde's, over the STORED representation the codegen already narrows every column to —
//! never over the declaring type directly — so a `Radians<T>` field reaches a document exactly as
//! bare a number as every other column of `T` does, without this type spending a derive to get there.
//!
//! # The first two customers
//!
//! A face's `roll`, `yaw` and `pitch` (each an `Option<Radians<f32>>`), and a horizon's `angle` — two
//! producers that already measured in `f32` radians before this type had a name, which is the
//! ordinary way a citizen here arrives.
use crate::;
/// **AN ANGLE, IN RADIANS** — a `T` underneath, and a different type so that a caller reading
/// `roll: Option<Radians<f32>>` never has to ask what unit a bare number would have left silent.
///
/// # Examples
///
/// ```
/// use ingraph::Radians;
///
/// let quarter_turn = Radians::new(core::f32::consts::FRAC_PI_2);
/// assert_eq!(quarter_turn.get(), core::f32::consts::FRAC_PI_2);
/// assert_eq!(quarter_turn.to_degrees(), 90.0);
/// ```
///
/// It refuses nothing — an angle is any real, and normalising it into a particular range is the
/// producer's business and not this newtype's:
///
/// ```
/// use ingraph::Radians;
///
/// assert_eq!(Radians::new(-10.0_f32).get(), -10.0);
/// assert!(Radians::new(f32::NAN).get().is_nan());
/// ```
///
/// A second width joins the same way, with none of the machinery above written twice:
///
/// ```
/// use ingraph::Radians;
///
/// let wide = Radians::new(1.25_f64);
/// assert_eq!(wide.to_degrees(), 1.25_f64.to_degrees());
/// ```
;
/// The width [`Radians::to_degrees`] and [`Radians::from_degrees`] need — `f32`'s and `f64`'s own
/// `to_degrees`/`to_radians`, lifted into a trait because both are INHERENT methods on their widths
/// and no trait in `core` names either, so an unbounded `T` cannot spell them at all. See the
/// module's own note for the census that found no pre-existing bound to reuse instead.
///
/// # An OPEN door, not a sealed one
///
/// [`ConfidenceCarrier`](crate::ConfidenceCarrier) seals its own vocabulary because what it measures
/// — which values are not numbers, which two compare equal while carrying different bits — takes a
/// MEASUREMENT this crate can check and an outside impl cannot. Converting between degrees and
/// radians is a single, unconditional identity (`× 180 / π` and its inverse) that carries no such
/// question, so there is nothing here for a seal to protect: a downstream width joins this trait by
/// implementing it for its own type, the ordinary extension seam
/// [`DefaultMarker`](crate::DefaultMarker)'s own note names, rather than a closed one.
/// **A SCALAR joins by stating WHATEVER `T` STATES** — [`Radians<T>`] fans out into no columns of
/// its own, so unlike the three composites one door over it has no leaf guard to write: it is one
/// `T`, so its shape IS `T`'s shape, total and unconditional.
/// **THE SAMENESS** — an angle is the same as another wherever `T`'s own [`ColumnEq`] says so.
/// [`BoundingBox<T>`](super::BoundingBox)/[`Point2<T>`](super::Point2)/[`Quad<T>`](super::Quad) each
/// fold this over their several fields; `Radians<T>` has exactly one, so the fold is that field's
/// own answer and nothing more — the [`column_eq!`](crate::column::column_eq) macro's shape is not
/// this row's, because that macro is `self == other` for a CONCRETE type with its own `PartialEq`,
/// and `T` here is neither concrete nor guaranteed one.
/// **THE STORED WORD is `T`'s**, in every dialect that has one. There is no interval to keep on the
/// way back in, so unlike [`NormCoord`](super::NormCoord) this row has no decode-side refusal
/// anywhere beneath it — a stored angle reads back exactly the `T` it was written as.
/// **ONE BIND OUT** — `T`'s, delegated, INCLUDING the value-only half: a `T` with a derived leaf of
/// its own (none of this crate's ships one, but the delegation costs nothing to state honestly) binds
/// its narrower value list here rather than the DEFAULT, which would have bound `T`'s full width
/// under a shorter left-hand side.
/// **AND THE VALUE BACK IN**, unconditionally — `T`'s own decode, wrapped. Unlike
/// [`NormCoord`](super::NormCoord) there is no refusal to make here: every stored `T` is an angle, so
/// the only way this can fail is `T`'s own decode failing first.
/// **AN ANGLE IS WHATEVER BSON `T` CROSSES AS** — a `Double` for `f32` and `f64` alike, since BSON's
/// only binary float is 64 bits and both widen into it. [`Score`](crate::Score)'s own row, delegated
/// rather than repeated: nothing about the value is encoded beyond `T`'s own crossing, because there
/// is no invariant here for a decode to re-establish.
/// **THE KEYSET POSITION** — `T`'s own bytes, delegated for FAITHFULNESS rather than for order,
/// exactly as `cursor::value`'s own float row states it: a negative angle's bytes may sort ABOVE a
/// positive one's at a signed width, which would be wrong for a storage form and is irrelevant here,
/// because a cursor's value is bound back and compared by the ENGINE's own numeric `>`/`<`, never by
/// comparing cursor bytes as a string. Unlike [`NormCoord`](super::NormCoord)'s row, the read makes
/// no second check on the way back: every bit pattern `T`'s own cursor codec can produce is an angle
/// this type admits.
/// **THE ADMISSION** — an angle is one element wherever its component is. `Vec<Radians<f32>>` is a
/// joint's rotation history, a sampled bearing track; nothing about the value refuses a list of them.
/// **THE SCALAR reading**, which is what a total order over the ADMITTED values earns —
/// `gt`/`gte`/`lt`/`lte` mean what they say over any two non-`NaN` angles, so this takes the uniform
/// [`ScalarFilter`](crate::ScalarFilter) exactly as [`NormCoord`](super::NormCoord) does, and with the
/// full eight operators: there is no interval here for `in`/`notIn` to be dishonest about. No bound on
/// `T` is needed here — [`ScalarFilter<Self>`](crate::ScalarFilter) names no requirement of its own —
/// exactly as the concrete form needed none.
/// **THE CROSSING IN — an angle arrives as `T`'s own roster reading**, on the [`Score`](crate::Score)
/// retirement's ruling: a named scalar would have to say something the roster does not, and what a
/// `Radians<T>` scalar would have said is the UNIT, which reaches a reader through this type's own
/// documentation and the field that names it rather than through a grammar.
///
/// Bounded through [`Builtin`](crate::Builtin)'s own [`ScalarWire`](crate::ScalarWire) reading of
/// `T` rather than through [`ToGraphqlInput`] directly: `f32` and `f64` publish no crossing of their
/// own under that trait (a plain numeric FIELD reaches the wire through async-graphql's native
/// support instead), so [`Builtin: ScalarWire<T>`](crate::ScalarWire) — the SAME row `T`'s own
/// `ScalarFilter<T>` already reaches — is the one bound that is both generic and satisfied at the
/// real customer. Total, unlike [`NormCoord`](super::NormCoord)'s own row: there is no interval to
/// refuse an operand against, so the error is whatever `T`'s own crossing carries.
/// **AND OUT**, mirroring the row above so the two directions cannot come to disagree — the mirror
/// law [`radians::tests`](self::tests) pins by round-tripping through both. BY VALUE rather than by
/// reference, the carrier shape every `Copy` citizen here takes.
/// **THE FILTER'S OWN NAME, FIXED ACROSS EVERY WIDTH** — [`Count`](crate::Count)'s `CardinalityFilter`
/// row, delegated one width further: the VALUE crosses as `T`'s own reading above, and the FILTER
/// wears the name `RadiansFilter` for every `T` this row is asked about, so that a schema holding
/// both a plain `f32` column and a `Radians<f32>` one never asks `Registry::create_type` to seat two
/// Rust types under `F32Filter`. See the module's own note for why the name is FIXED rather than
/// composed per `T` — the short version being that [`NAME`](crate::ScalarWire::NAME) is a plain
/// compile-time constant, so no generic impl could vary it by `T` even if this one wanted to.
///
/// Total, exactly as [`Count`]'s row is: every value `T`'s own crossing hands back is an angle, so
/// the error this row carries is whichever one `T`'s own [`ScalarWire`] names.