Typed ry as a complete language
This draft makes typed ry a complete language of its own, on par with Roc and built for speed. A
typed program can be written entirely in ry’s own types (numbers, Bool, Str, List, Dict,
Set, records, tuples, tags and functions) without touching an R data type, and R values meet
those types only at an explicit boundary. Plain R code runs unchanged. Settled rules graduate into
the type system reference and the
standard library reference, which win wherever this page disagrees
with them.
The shape in one example
Section titled “The shape in one example”dot <- function(x: List<F64>, y: List<F64>) -> F64 { total <- 0 for (i in List.range(1, List.len(x))) total <- total + x[[i]] * y[[i]] total}
values: List<F64> <- List.map(List.range(0, 999999), \(i) Num.to_f64(i) / 999999)dot(values, List.reverse(values))Every value here is ry’s own. List.len returns an I64, and List.range(a, b) is the
List<I64> from a to b, both included and empty when b < a, so i is an I64. 0 is a literal, which takes the type its uses ask for, here F64. Nothing
can be NA, so the loop needs no missing-value checks, and List<F64> is one contiguous buffer of
unboxed doubles, so x[[i]] is a bounds check and a load.
The same function with an R vector is a type error that names the conversion (illustrative wording):
type-mismatch
x expected `List<F64>`, found `double[]`. Convert an R vector with `List.from_r()`Goals and constraints
Section titled “Goals and constraints”- Plain R stays plain R. No new form changes the meaning of text R accepts, and R’s own literals
keep their R values.
1is still adoubleand"a"acharactervector wherever nothing asks for a ry type. - Roc parity. Where Roc has a feature, typed ry has it or records why not. The comparison is the gap table below.
- Maximum performance. Every type has a representation the compiler can keep unboxed and
contiguous: no
NAencodings, no attributes, no recycling, value semantics with in-place update of a uniquely held value. The runtime contract states what the runtime must provide. - Hindley-Milner (
decisions/syntax-semantics.md, “Beta semantics: The type system is Hindley-Milner, and stays fast to check”). Every feature here is unification over the existing constraint mechanism, and the unifier gains nothing: records stay closed and there are no row variables (decisions/typed-stdlib.md, native records). - One boundary. An R value becomes a ry value only through a conversion function that checks
it. A ry value whose representation R already has (
F64,Bool,Strand Lists of them) fits the R type directly, because nothing R code relies on is lost.
What changes for existing ry code
Section titled “What changes for existing ry code”ry already has records, tuples, tags, match, Dict, Set and a strict vector, Array<T>. What
it lacks is its own scalars: numbers are R’s integer and double, a string is a length-one
character vector and a truth value an R logical, each of which may be NA. The standard library
takes R lists (standard-library design, “Values: R lists, R scalars and two new native kinds”).
This design changes four things:
- Scalars.
I64andF64are ry’s numbers,Boolits truth value andStrits string. None has anNA. List<T>is ry’s list. It is today’sArray<T>renamed, with the same[a, b, c]literal, and it holds ry values only.Arrayis removed rather than kept as a second name.- The standard library speaks ry types.
List.lenreturns anI64,Str.split_onreturns aList<Str>,List.sumtakes aListof numbers. R lists and vectors reach it throughList.from_rand its siblings. - Records gain an update form and patterns gain list and
asforms. Records stay closed, with no row variables, because typed ry stays small until a feature earns its place.
Gap analysis against Roc
Section titled “Gap analysis against Roc”Roc’s facts are from its language reference (docs/langref/) and builtins module
(src/build/roc/Builtin.roc) in the current Zig compiler, checked against the builtin modules of the
older Rust compiler (crates/compiler/builtins/roc/ at tag alpha4-rolling) where Roc changed.
“Roc” means the current compiler; “legacy Roc” means the Rust one. “Today” is ry before this design.
| Feature | Roc | ry today | Decision |
|---|---|---|---|
| Integer types | I8-I128, U8-U128 |
R’s 32-bit integer with NA |
I64 only, until a program needs another width |
| Fractional types | F32, F64, Dec |
R’s double |
F64 only, until a program needs another |
| Literal default | Dec for every literal (legacy: I64 for integers, Dec for fractions) |
R’s | R’s (double, integer) when nothing constrains a literal |
| Literal suffixes | 5.U8, 1.5.F32 (legacy: 5u8, 1.5f32) |
1L |
glued suffixes 5i64 and 1.5f64, plus R’s L, because R parses 5.I64 as the name-like number 5. followed by I64 |
| Integer overflow | crashes; _wrap, _saturated, _try variants |
NA with a warning |
an error; _wrap, _saturated, _checked variants |
| Mixed number types | no implicit conversion | R’s promotion | none, as Roc; Num.to_* converts |
Bool |
nominal tag union [False, True] |
logical with NA |
Bool, two values, written TRUE and FALSE |
Str |
UTF-8, small-string optimized | length-one character with NA |
Str, UTF-8, no NA |
| Interpolation | "${name}" |
none | f"hello {name}" |
List |
contiguous, unboxed, in place when unique | R list, or Array<T> |
List<T>, contiguous, unboxed, in place when unique |
| List operators | none; functions only | elementwise on Array |
item by item |
Dict, Set |
hash map, insertion order | native, insertion order | keys widen to every ry value but functions and floats-with-NaN |
| Records | structural, open (row variable) | structural, closed | unchanged: closed, no row variables |
| Record update | { ..r, x: 1 } |
r$x <- 1 |
both: (..r, x = 1) builds a copy |
| Field punning | { x, y } |
none | in patterns only: (x =, y =) binds x and y |
| Tuples | (a, b), t.0 |
(a, b), t[[1L]] |
unchanged |
| Tag unions | open and closed, row variable | open with .., no row variable |
unchanged |
| Recursive types | through nominal types | through type |
unchanged |
| Pattern matching | exhaustive, guards, list patterns, as |
exhaustive, guards, no list patterns | adds list patterns [x, ..rest] and p as name |
| Number patterns | literals | literals | adds suffixed literals |
| Closures | lambda sets, defunctionalized | R closures | R closures; lambda sets are the runtime’s job (contract) |
| Purity | -> pure, => effectful, ! names |
@pure |
@pure stays; effects stay untracked |
| Abilities | none: static dispatch on nominal types with where constraints (legacy: abilities Eq, Hash, Inspect, Encode, Decode) |
none (traits declined) | built-in structural ==, hashing and printing for every ry type but functions; no methods, no user abilities |
| Opaque types | := |
type nominal, @type opaque |
unchanged |
| Modules | import, exposing |
R namespaces, std |
unchanged; R packages are the module system |
| Results | Try(ok, err) (legacy Result), postfix ?, ?? for a default |
Result, no operator |
Result; Result.with_default for ??; a try prefix |
crash, dbg, expect |
builtins | stop, print, testthat |
R’s |
| Inference | HM with rows | HM with joins | unchanged: HM with joins |
| Generics | type variables | <T>, constraints |
unchanged; constraints gain number |
| Mutable variables, loops | var $x, for, while, ranges a..<b |
R’s <-, for, while, a:b |
R’s; for over a List<T> binds T |
| Length and index type | U64 |
integer |
I64 |
The sections below give each decision’s rules.
Numbers
Section titled “Numbers”| Type | Values | R counterpart |
|---|---|---|
I64 |
two’s complement, every bit pattern a value | none (R’s integer is 32 bits with NA) |
F64 |
IEEE 754, including NaN and the infinities |
shares R’s double representation |
Other widths (I8 to I128, the unsigned types, F32, Dec) return only when a program shows it
needs one. An R integer or raw value converts to I64. An I64 differs from R’s integer in
that every bit pattern is a value and overflow is an error where R returns NA with a warning, so
it does not share R’s representation.
An F64 and an R double hold the same bits, and an F64 is never NA. A NaN produced by
arithmetic is an ordinary F64, as in Roc. R’s NA_real_ is a NaN with a reserved payload, and
the boundary refuses it, so an F64 never holds R’s missing value.
Literals
Section titled “Literals”A number literal has R’s type unless a ry number type asks for it: 5 and 1.5 are double, and
5L is integer. So plain R code types exactly as before. A ry type asks for a literal in three
places:
-
An expected type. A literal checked against a ry number type takes it: an argument for a typed parameter, the value of an annotated variable, a function’s result, a
Listitem or a record field whose type is known. -
The other operand. In an arithmetic operator or comparison whose other operand has a ry number type, the literal takes that type, so
n + 1withn: I64is anI64. -
A variable written with a literal.
total <- 0givestotala literal type that its first arithmetic use decides. A use with a ry number typeNmakes itN. Any other use, or the end of the function, gives it R’s type. So intotal <- 0for (x in xs) total <- total + xwith
xs: List<F64>,totalis anF64, while in plain Rn <- 0; n <- n + 1Lkeepsnadouble, by R’s promotion order. The literal type is an inference variable with a literal constraint. The variable is decided by unification before any join of the variable’s writes sees it, so a join never meets an undecided literal.
- written directly before a literal is part of it, so -9223372036854775808i64 is an I64, as
in Roc.
| Literal | May become |
|---|---|
5, 5L, 0x1F, 1e3 |
any number type that holds the value, or R’s double (integer for 5L) |
1.5, 1e-3 |
F64, or R’s double |
5i64, 1.5f64 |
exactly that type |
A literal that does not fit the type it is asked to take, such as 1.5 as an
I64, is a type-mismatch at the literal. NA, NaN and Inf are R’s constants and never take
a ry type: Num.nan_f64 and Num.infinity_f64 are the ry spellings.
The suffixes are new syntax. R reads 1.5f64 as a number followed by a name, and 5i64 as the
complex 5i followed by 64, so each is a syntax error in R today. 5i alone keeps its R meaning,
and any other suffix is a syntax error in ry. A hex literal takes only the i64 suffix (0xFFi64),
because f is a hex digit: R reads 0x1Ff64 as the number 0x1FF64, and so does ry.
At run time a literal is the type the checker gave it: the preflight spells each unsuffixed literal
the checker typed I64 with its suffix before ry’s runtime reads the program, the mirror of erasing
annotations for GNU R. Code that skips the preflight (ry load, source()) falls back to the
interpreter’s conversion at the operator or annotated binding, which refuses NA and an inexact
value.
Arithmetic
Section titled “Arithmetic”Both operands of an arithmetic operator have the same number type, and the result has it too.
There is no implicit conversion between number types, so x + i with an F64 and an I64 is a
type-mismatch that suggests Num.to_f64(i).
| Operator | I64 |
F64 |
|---|---|---|
+ - *, unary - |
same type; overflow is an error | same type |
/ |
a type-mismatch that suggests %/% |
same type |
%/%, %% |
floored division and modulo, as R | as R |
^ |
same type, a non-negative integer exponent | same type |
== != < > <= >= |
Bool |
Bool |
%% and %/% keep R’s floored meaning rather than Roc’s truncating % and //, because an R
reader expects it and Num.rem and Num.div_trunc give Roc’s. Integer division by zero is an
error. Float division by zero follows IEEE 754, as in Roc.
Num.add_wrap, Num.add_saturated and Num.add_checked (and their sub, mul siblings) give
the other overflow behaviors, which ry could not offer while R’s integer reserved a bit pattern
for NA.
Conversions
Section titled “Conversions”Num.to_i64 and Num.to_f64 convert between the two number types. Num.to_i64 may lose the
value, so it has a _checked form that returns Result<I64, :OutOfBounds>, and the unchecked form
is an error when the value is not whole or does not fit, as Roc’s crash. Num.round, Num.floor, Num.ceiling and Num.truncate take a fractional number
and return an I64, as Roc’s do. This replaces the standard-library design’s rounding that keeps
the number type, which was written for R’s double.
Bool has two values. TRUE and FALSE are literals that become a Bool where one is demanded,
and Bool.true and Bool.false are always one. A comparison of ry numbers or strings is a Bool,
and !, &&, ||, & and | on Bool operands are a Bool. if and while take a Bool or
an R logical. A match on a Bool has two cases, so TRUE and FALSE arms cover it, where an R
logical also needs NA.
A Str is an immutable UTF-8 string with no NA. A string literal becomes a Str where one is
demanded. == and the ordering comparisons compare bytes, independent of the locale. There is no
indexing and no length, as in Roc, because a string’s length counts bytes or code points and
neither is what a reader means by characters: Str.count_utf8_bytes, Str.to_utf8 and
Str.walk_utf8 cover the needs. Str.concat, Str.join_with and interpolation (f"...") build
strings, and Num.to_str formats a number.
List<T>
Section titled “List<T>”A List<T> is an ordered sequence of ry values of one type, with value semantics:
[a, b, c]builds one, and every item has the item type. Items are never converted into each other, but literals take the item type, so[1, 2.5]is aList<F64>when the context asks for one.xs[[i]]reads the item at positioni, 1-based, and a position outside the list is an error.List.get(xs, i)returnsResult<T, :OutOfBounds>instead.xs[[i]] <- vrebindsxsto a list with that item replaced.xs[i]with aList<I64>of positions or aList<Bool>mask is aList<T>; negative positions leave items out, as in R.for (x in xs)bindsxasT.List.range(a, b)counts up fromatobinclusive and is empty whenb < a.a:bkeeps R’s meaning, including counting down, and takes R numbers only.- A
Listhas no names, no attributes, noNAand no recycling.
A List<T> holds ry values only: List<double> is an annotation error that suggests
List<F64>. Today’s Array<T> held R scalars, which is what this design removes.
Records, tuples and tags
Section titled “Records, tuples and tags”The literals, match and exhaustiveness are unchanged (records-and-tags.md and the type system
reference). Records stay closed and tag unions keep their anonymous ..: Roc’s row variables (open
records, pass-through tags) are left out, because typed ry adds a feature only once it earns its
place, and a closed record with a nominal type covers the programs ry targets. Two additions remain:
- Record update.
(..point, x = 3)is a copy ofpointwithxreplaced, and every replaced field must exist, as in Roc.point$x <- 3stays the statement form...pointis an ordinary R identifier, so(..point, x = 3)is today a record holding a variable named..point; a name starting with..first in a parenthesized record literal becomes a spread. A..restin a record pattern binds the remaining fields as a record. - Punning in patterns.
(x =, y =)binds the fieldsxandyto names of the same spelling, where(x, y)would be a tuple pattern. A record literal does not pun, because(x, y)is a tuple.
Pattern matching
Section titled “Pattern matching”Two pattern forms join the table in the type system reference:
| Pattern | Matches |
|---|---|
[], [p1, p2] |
a List of exactly that length whose items match |
[p1, ..], [p1, ..rest], [.., last] |
a List with at least those items; rest binds the remainder as a List<T> |
p as name |
what p matches, binding the whole value to name |
Patterns are ry syntax inside match, so ..rest there is a binder, not the R identifier it is in
an expression. Coverage treats a list pattern as a constructor per length, with .. covering every
longer length, as Maranget’s algorithm does for Roc’s list patterns. A suffixed number literal is a literal
pattern of its type.
Equality, hashing and printing
Section titled “Equality, hashing and printing”ry has no abilities or methods, because traits are declined (decisions/syntax-semantics.md). Roc derives
is_eq, to_hash and to_inspect for every structural type whose parts have them, and ry builds
the same three in, for every ry type except functions:
- Equality.
a == bon two values of the same ry type is structural equality, aBool, except on twoLists, whose==works item by item and gives aList<Bool>. A function is atype-mismatchthere, as Roc’s functions have nois_eq, and generic code says so with aneqconstraint (<T: eq>), which every ry type but a function satisfies. Floats compare as IEEE 754, soNaN != NaN. - Hashing. A
Dictkey orSetelement is any ry value but a function, hashed structurally. ANaNkey is an error when it is inserted. - Printing.
printandformatshow a ry value as the literal that rebuilds it (5i64,"a",[1, 2],(x = 1)), as records and dictionaries already print. - Ordering.
<and its siblings are defined on numbers andStr.List.sort_withtakes a comparison returning:LT | :EQ | :GT, andList.sort_ascandList.sort_desctake numbers or strings. - Encoding. Converting to JSON or another format is a library function over the R boundary, not an ability.
Functions and purity
Section titled “Functions and purity”Functions are R closures. Their types, generics and the inference of a function literal in context
are unchanged. Roc separates pure -> functions from effectful => ones. ry keeps its @pure
declaration (type system reference, “Purity”) and does not track effects otherwise, because an R
function may perform any effect and a typed program calls R functions.
The R boundary
Section titled “The R boundary”An R value enters ry’s types only through a conversion that checks it, and a failed check is an error that names the position and the reason.
| From R | Function | To ry |
|---|---|---|
double |
Num.from_r |
F64 |
integer |
Num.from_r |
I64 |
logical |
Bool.from_r |
Bool |
character |
Str.from_r |
Str |
double[], integer[], logical[], character[], raw[] |
List.from_r |
List<F64>, List<I64>, List<Bool>, List<Str>, List<I64> |
list[T] where T converts |
List.from_r |
List<T'> |
| named list | as.record |
a record |
Each refuses NA, attributes (names are dropped, a class is refused) and, for a scalar, a length
other than one. Going the other way, a ry value whose representation R shares fits the R type
directly, because R code loses nothing it relies on:
F64fitsdouble,BoolfitslogicalandStrfitscharacter;List<F64>,List<Bool>andList<Str>fitdouble[],logical[]andcharacter[], and aListof records, tuples or tags fitslist[...].
Every other ry value needs an explicit conversion: Num.to_r turns an I64 into R’s
integer when it fits in 32 bits and into a double otherwise (an error past 2^53), List.to_r
does the same item by item, and as.list converts records, tuples, tags, dictionaries and sets, as
it does today. Passing such a value to an R function is a type-mismatch that names the
conversion, and at run time the R function refuses it with the error records already give.
Typing rules in brief
Section titled “Typing rules in brief”- The ry scalar types are atomic types of their own. None fits another, and none fits an R type except the three shared ones above.
- A literal is typed by a fresh inference variable with a literal constraint (an integer or a
fractional number literal,
strorboolliteral). Unification binds it like any constrained variable, and a variable still unbound when its function is generalized takes R’s type. This is Roc’s literal typing with R’s defaults, and it is Hindley-Milner defaulting. - New constraints for generic code:
number(I64orF64) andeq(every ry type but a function), soList.sum : <T: number> fn(list: List<T>) -> T. The literal constraints are internal and never written. - The constraint lattice gains a ry side. Two ry constraints meet at the narrower one (an integer
and a fractional literal meet only at an error,
numberwith either is that one,eqwith any is the other). A ry constraint never meets an R one (numeric,atomic,scalar numeric,key), so a variable is either an R number or a ry number, and the meet is atype-mismatch.keyanditemwiden to admit everyeqry type. A literal constraint meetsnumericby taking R’s type and meets a ry constraint by staying a literal of that constraint. - The rule that a whole-number
doubleliteral fits anintegerparameter is the expected-type case of literal typing above, so it stays and needs no special case. - The existing
numericconstraint and R’s coercion order are unchanged, and apply to R types only.
Runtime contract
Section titled “Runtime contract”This section is the interface to the runtime work (crates/heap, crates/interp, crates/jit).
The language side relies on these properties, and the runtime may choose any representation that
provides them.
Scalars.
- Compiled code keeps every number,
BoolandStrhandle unboxed in registers and stack slots. No number type reserves a bit pattern, so anI64uses all 2^64 values. - The boxed form, used by the interpreter and anywhere R code can observe a value, is:
F64: a length-one Rdoublewithout attributes, which is exactly what the literal1.5evaluates to, so a literal needs no conversion;Bool: a length-one RlogicalholdingTRUEorFALSE;Str: a length-one Rcharacterholding a UTF-8CHARSXPthat is notNA_STRING;I64: a length-1 vector of ry’s own type code (I64SXP, 28) withREALSXP’s layout, holding the 64-bit value, with no attributes and never ALTREP, distinguishable from every R type by its type code.
- Integer arithmetic traps on overflow, integer division by zero is an error, and float arithmetic
is IEEE 754. No typed operation checks for
NA, because no ry value holds one.
Lists.
- A
List<T>is contiguous, with items stored unboxed at their natural width whenTis a number (8 bytes forF64andI64), as R’s 4-bytelogicalforBool, and as handles otherwise.List<F64>,List<Bool>andList<Str>use R’sdouble,logicalandcharactervector layouts, so they pass to R code and C code without a copy.List<I64>is theI64SXPvector at length n, so a scalar and a list share one representation. - An update through
xs[[i]] <- v,List.set,List.appendand the like reuses the storage when the list is uniquely held (decisions/typed-stdlib.md, “Standard library updates reuse a uniquely held value”), so a loop that appends is amortized constant time per item. - A
Listcarries no attributes, so a compiled loop over one needs only a bounds check per read.
Literals and boundaries.
- An R number reaching an operator or a typed parameter that requires a ry number converts there, and an inexact conversion is an error. Compiled code folds literal conversions.
- The boundary functions in The R boundary are the only places an R vector is
scanned for
NA. The conversion of a literal or an accepted scalar at an operator checks one value.
Closures.
- A typed closure captures by value whenever no variable it captures is written after the capture
or through
<<-, and the checker reports this per closure, so such a closure needs no R environment. A closure that fails the test keeps R’s environment semantics. matchcoverage is decided statically: a non-exhaustivematchon a closed type is an error, so compiled code needs no fallback arm.
What the language side provides now. Until the runtime has native integer kinds, the
interpreter carries a correct implementation: native numbers as heap objects, Lists of them as
flagged vectors, and arithmetic through a generic path. It is slow, and the runtime work replaces
it with the representations above.
The typed benchmark
Section titled “The typed benchmark”The typed benchmark programs (tools/bench/kernels/*.typed.R and
tools/bench/applications/*.typed.R) use only ry types: List<F64> instead of
double[], F64 and I64 scalars, Str for names, and the List and Num modules instead of
seq_len, sum and vapply. The harness’s clock and output are R calls at the boundary
(proc.time, cat), converted with Num.from_r.
Answered questions
Section titled “Answered questions”The draft asked four questions of taste. Each took the recommended answer:
- String interpolation is an
f"..."literal:f"hello {name}"is aStr. R readsf"..."as a syntax error, so no R text changes meaning. - Operators on lists work item by item, as R’s vectors and the old
Arraydid, on two lists of one length or a list and a single value, never recycled. - Propagating an error is a
tryprefix:try f(x)unwraps an:Okand returns an:Errfrom the enclosing function.try (f(x))andtrybefore anything but a name or call keep their R meanings. - Lengths and positions are
I64, soList.len(xs) - 3may go negative andxs[-1]stays expressible.
Settled choices
Section titled “Settled choices”- ry has two number types,
I64andF64, plusBoolandStr, none withNA. The draft first took all thirteen of Roc’s number types. An orchestrator decision cut the set toI64andF64, and another width returns only when a program shows it needs one. - Literals have R’s type unless an expected type, the other operand or a later use asks for a ry number type.
List<T>replacesArray<T>and holds ry values only.F64,Bool,Strand Lists of them share R’s representation and fit R types directly; every other crossing is an explicit conversion.- Records stay closed, with no row variables; list patterns,
aspatterns, record update and pattern punning join the syntax. - Equality, hashing and printing are built in for every ry type but functions.
Open questions
Section titled “Open questions”- Whether a project can declare that unconstrained literals default to ry types instead of R’s.