Tamale. Coord
(tamale v0.1.0)
Copy Markdown
Exact rational coordinates — the kernel's only number.
Coordinates appear wherever an anchor references a position rather than
an identity: Anchor.Metric intervals, Anchor.Relative offsets,
Op.Retime spans, and every Tamale.Warp endpoint. The kernel
interpolates and composes those values (Warp.at/2, Warp.compose/2),
so the coordinate type must be closed under scaling by rationals —
a requirement integers and floats both fail: integers cannot represent
frame 3 stretched by 4/3, and floats smear it into rounding dust that
no conformance vector can pin.
The kernel's answer is the rational pair {num, den}, normalized so
that den > 0 and gcd(|num|, den) == 1. Normalization makes the
representation canonical: two equal coordinates are always ==-equal
structs of the same shape, so plain term equality is exact equality.
Boundary rules
- Integers are accepted everywhere and promoted to
{n, 1}. - Floats are rejected.
cast/1reports them as{:error, {:invalid_coordinate, value}};cast!/1raises. This is the same doctrine as the canonical digest (docs/decisions/0005): normalizing domain floats into exact values — seconds as microseconds, frames as integers — is the channel adapter's job, with a declared resolution. - Kernel outputs are always normalized rationals.
Wire form
In conformance vectors and any JSON interchange a coordinate is:
- a JSON integer when
den == 1—4means{4, 1} - a
"num/den"string otherwise —"4/3"means{4, 3}
Floats are not representable on the wire; decode/1 rejects them.
Summary
Types
A normalized rational: {num, den} with den > 0 and the fraction
fully reduced.
Functions
Casts external data to a coordinate. Accepts integers and {num, den}
pairs; anything else — floats included — is
{:error, {:invalid_coordinate, value}}.
Raising variant of cast/1, for hand-written coordinates.
Decodes the wire form. Floats and malformed strings are
{:error, {:invalid_coordinate, value}}.
Divides a by b. Raises ArgumentError when b is zero.
Encodes a coordinate to its wire form: integer, or "num/den".
Promotes an integer to a coordinate.
Builds a normalized coordinate. Raises ArgumentError on a zero
denominator or non-integer parts — a caller bug, not data.
Types
Anything cast/1 accepts: a rational or a bare integer.
@type t() :: {integer(), pos_integer()}
A normalized rational: {num, den} with den > 0 and the fraction
fully reduced.
Functions
Casts external data to a coordinate. Accepts integers and {num, den}
pairs; anything else — floats included — is
{:error, {:invalid_coordinate, value}}.
Raising variant of cast/1, for hand-written coordinates.
Decodes the wire form. Floats and malformed strings are
{:error, {:invalid_coordinate, value}}.
Divides a by b. Raises ArgumentError when b is zero.
Encodes a coordinate to its wire form: integer, or "num/den".
Promotes an integer to a coordinate.
Builds a normalized coordinate. Raises ArgumentError on a zero
denominator or non-integer parts — a caller bug, not data.