#Types and Values

Rig distinguishes inline copy values from explicit references. A Record copies its fields; a reference copies a handle to shared storage. Choosing a type therefore also communicates how values are stored, copied, and mutated.

#Types Are Values

A type is a value one stage above the values it describes. A runtime type such as Int has type Type_1:

(define Point:Type_1 Point=(Record x:Int y:Int) origin:Point origin=(record x=0 y=0))

Point names the result of a type-construction expression. It is not a separate nominal declaration: another Record with the same field names and types is the same structural type, regardless of field order. Named references provide nominal identity when an API needs it.

Type constructors can be called from ordinary staged functions.

#Scalars

Family Types
Signed integers Int8, Int16, Int32, Int
Unsigned integers Nat8, Nat16, Nat32, Nat
Floating point Float32, Float
Boolean Bool
Unit Null

Int, Nat, and Float are 64-bit types. Bool has the values true and false; the unit value is null.

Numeric operations use equal operand types. add, sub, mul, div, eq, and lt support the numeric families; integer types also support rem. Integer addition, subtraction, and multiplication wrap at the selected width. Integer division by zero and signed minimum divided by negative one trap.

Conversions are explicit and named for their destination: (int byte), (nat8 number), or (float value32). Integer conversion traps if the destination cannot represent the value. Float narrowing follows IEEE rounding. Integer-to-float and float-to-integer conversion are not currently provided.

Void is uninhabited: an expression such as (trap) has that type because it never returns a value.

#String, Text, and Bytes

String is an inline fixed-capacity UTF-8 value, currently limited to 56 bytes. Text is an immutable reference to dynamically sized UTF-8 data. The same literal spelling can construct either, according to its expected type:

(define label:String label="ready" description:Text description="An immutable UTF-8 message." encoded:(List Nat8) encoded=(bytes description) decoded:(Variant error:Int value:Text) decoded=(try_text encoded))

text converts a String to newly allocated Text. string copies Text into a String and traps if it exceeds the fixed capacity. A literal expected as Text is constructed directly; it does not first pass through String.

bytes exposes Text's immutable UTF-8 bytes without copying or allocating. try_text validates an immutable byte list once and, on success, shares its storage as Text. Its error payload is the zero-based byte offset of the invalid sequence, including the leading byte of an incomplete final sequence.

Escaped literals support \", \\, \n, \r, and \t. Other escapes, including Unicode escape syntax, are rejected; write UTF-8 characters directly.

Quote-run literals use three or more matching quotes and are raw. In block form, the closing delimiter's indentation defines the margin stripped from the content:

(define message:Text message=""" first line indented line """)

The opening and closing line breaks are excluded. Nonblank lines must contain the closing delimiter's exact indentation prefix. A longer delimiter permits shorter quote runs inside the content. There is no string interpolation.

#Records

Records are structural products. Field access uses ordinary call notation, with the field name as the operation:

(define point:(Record x:Int y:Int) point=(record y=20 x=22) horizontal:Int horizontal=(x point) total:Int total=(select point (fn x:Int y:Int do=(add x y))))

select evaluates the Record once and passes selected fields to an inline function. Parameter names select fields; annotations must match their exact types. The function may select a subset, in any parameter order. Its result becomes the result of select.

Record construction requires exactly the fields of its expected type. Field order does not affect the Record type or how fields are accessed.

#Variants

A Variant has one active case, with a payload whose type belongs to that case:

(define choice:(Variant none:Null some:Int) choice=(variant some=42) answer:Int answer=(match choice none=(fn _:Null do=0) some=(fn value:Int do=value)))

match requires exactly one branch for every case. Each branch is an inline function that receives one argument, the case payload. The branches that return a value must agree on the result type. A payload-free case is written explicitly as (variant none=null).

Option and Result do not need privileged language types. Their conventional shapes are (Variant none:Null some:T) and (Variant error:E value:T). They are ordinary Variants inside Rig, with standard Option and Result projections at Component boundaries.

#Ordered Collections

Type Storage and behavior
(Sequence T n) Inline, fixed-length copy value
(List T) Immutable shared storage with runtime length
(Block T) Shared mutable storage with fixed capacity and runtime length

Use (sequence 1 2 3) or (list 1 2 3) under the corresponding expected type. All three collection kinds support (length values) and (get values index). Indexes are zero-based Int values; invalid access traps.

Immutability applies to the container's element slots. A List containing Mutable handles still refers to shared mutable state.

A Block starts empty. Its capacity is chosen at allocation and never grows implicitly:

(define snapshot:(Fn (List Int)) snapshot=(fn do=(let buffer:(Block Int) buffer=(block capacity=4) in=(do (push buffer 10) (push buffer 20) (list from=buffer)))))

push appends to the initialized prefix; set replaces an existing element. truncate shortens the prefix to an exact length, and capacity reports the allocated slots. These operations trap on invalid ranges or capacity exhaustion.

(copy destination destination_index source source_index count) bulk-copies from a Block or List into a Block. Overlapping Block ranges behave as if the source range were read first. Copying may extend the destination's initialized prefix, but not leave a gap or exceed capacity.

(list from=buffer) copies the visible prefix into a new immutable List. Later mutations to the Block cannot affect that snapshot. Copying the Block handle itself would instead preserve shared mutation.

#References

The single-value reference family makes capabilities explicit:

Type Construct Read Replace Transfer End identity
(Box T) box get
(Mutable T) mutable get set
(Movable T) movable get set move take

get copies the payload. set replaces it and returns Null. Copies of a handle share the same identity:

(define counter:(Mutable Int) counter=(mutable 0) alias:(Mutable Int) alias=counter increment:(Fn Int) increment=(fn do=(do (set alias (add (get counter) 1)) (get counter))))

move preserves a Movable's identity and payload but returns a fresh handle generation. All older aliases become stale. take ends the identity, invalidates its aliases, and returns the payload. Access through a stale handle traps. Rig checks this dynamically rather than restricting where handles may be copied or stored.

An optional type-level name= establishes package-owned identity, such as (Movable Int name="file"). Only the defining package may construct or operate on that named reference; other packages use its exported functions. The name is a compile-time String value, not a label repeated at allocation.

References may nest inside composites and break recursive layout cycles. Garbage collection reclaims unreachable storage; it does not run resource-release operations on your behalf.

#Recursive Data

A group made entirely of direct Type_1 bindings can refer to its own types during construction:

(define Chain:Type_1 Chain=(Variant end:Null link:(Box (Record value:Int rest:Chain)))) (define empty:Chain empty=(variant end=null))

The Box makes the recursive layout finite. A Record or Variant that contains itself directly has no finite inline size and is rejected. Each cycle must cross an explicit reference edge.

Keep participating type bindings in one define, or one local let for a generic constructor. They must use direct intrinsic Type_N annotations; ordinary value initializers remain sequential. Recursive types are structural, not nominal merely because they have a recursive name.

A recursively called type factory is still an ordinary computation and may diverge. Putting a Box around its result does not stop that computation. Tie the data cycle with a local Type binding, then return that type from the factory.

#Value Size

Inline does not mean unlimited. The current compiler limits fixed-size values to 256 logical slots, including fields, Variant payloads, and Sequence elements. A String or complete function value uses eight slots; a reference uses one. Use explicit indirection when a value needs shared or larger storage. Function captures have their own smaller capture budget.