Skip to main content

Module newtype

Module newtype 

Source
Expand description

THE NEWTYPE DEVICE’s model — the kits a declared wrapper opts into, and the pass-through row each one installs. The NEWTYPE DEVICE’s model: what #[derive(ingraph::NewType)] emits for a single-field struct this crate declares — one citizenship row per KIT the declaration opted into, every one of them a pass-through to the type inside.

§What it is, beside the three devices that already existed

devicethe type it equipswhat it knows about that type
#[derive(ingraph::Enum)] #[ingraph(remote = "…")]a vocabulary SOMEBODY ELSE declaredits variants, restated
#[ingraph::entity(remote = "…")] / record(remote)a struct SOMEBODY ELSE declaredits fields, restated
#[derive(ingraph::Filter)] #[ingraph(operator(<family>))]a value THIS crate declaresthat it is one operand — and it MINTS the filter
thisa value THIS crate declaresthat it WRAPS one, and which faces it wants

The line between the last two is the CONSTRUCTION CONTRACT. The element mode mints a filter type and gives the element the citizenship that filter needs, whole and unchosen; this device chooses, and every face it writes is the INNER type’s answer wearing the outer type’s name. So a newtype that wants a filter and nothing else takes two words, and one that wants to be a column in two dialects and never crosses a wire takes two others.

§THE EMISSION LAW: every pass-through is FULLY QUALIFIED

<Inner as Trait>::method(&self.0, …), never self.0.method(…), and the associated types and consts alike. Four things follow from it, and the fourth is the one that decides it:

  • method resolution is pinned. A bare self.0.push_bind(qb) resolves by autoref and by inherent-before-trait, so an inner type growing an INHERENT method of that name silently takes the call away from the trait the row is implementing.
  • the obligation’s landing point IS the diagnostic’s. The row carries Inner: Trait in its where clause, so a missing kit on the inner type is E0277 naming that type and that trait, at the declaration — rather than a method-not-found inside an expansion.
  • it is the house’s own absolute-path doctrine, one grain in: an emission spells every framework name from a root, and a delegation spells every callee from its trait.
  • one spelling serves every receiver and every carrier. &self, self, no receiver at all, an associated const, a GAT — the qualified form is the same shape for all of them, and it is the only shape that is also correct where the inner type is a GENERIC PARAMETER. self.0.cmp(…) on a Confidence<S> cannot say which S’s row it meant; <S as Trait>::cmp(&self.0, …) can.

§The GATE is one source, and every READ path is spent on it

A newtype that carries an invariant has exactly one door — scalar(parse = "…") for a value read WIDE out of text, scalar(check = "…") for one anchored in a range — and the device spends that door on every path a value ARRIVES on: the scalar’s parse, its is_valid, the cursor’s read_cursor, and the dialect decode. What has no gate to spend passes straight through.

The asymmetry is the point. A WRITE is a value the type already holds, so nothing can be wrong with it and the inner’s own row is the whole answer. A READ is bytes somebody else wrote — a client’s cursor, a column another writer filled, a JSON operand — and a newtype whose type says [0.0, 1.0] must not be handed a 1.5 because it came back from a column.

Structs§

Kits
Every kit a declaration opted into.
NewTypeModel
A declared NEWTYPE, as the device reads it.
ScalarKit
The scalar kit, as a declaration wrote it.

Enums§

Gate
The DOOR a declaration put in front of its own values — scalar(parse = "…") or scalar(check = "…"), and never both.