Data Structures in CLS: Arrays, Tuples, Records, and Structs

CLS has four built-in composite data structures — arrays, tuples, records, and structures — each optimised for a different use case. Arrays are ordered, mutable, and homogeneous. Tuples are ordered, immutable, and heterogeneous. Records are key-value maps. Structures are named flat schemas that bundle related fields under a single constructor call. All four are first-class values and can be nested, passed to functions, or stored in variables.

Primitives (int, float, bool, String, char) are passed by value. Arrays, tuples, records, and structure instances share a reference in the interpreter — assigning one variable to another does not deep-copy the collection.

Arrays

An array is an ordered, mutable sequence of values. Array literals use square brackets, and elements are separated by commas. The type annotation for an array of T is written T[].

var numbers: int[] = [1, 2, 3, 4, 5];
var names: String[] = ["Alice", "Bob", "Carol"];
var empty: int[]    = [];

Index access

Arrays are zero-indexed. Use arr[index] to read or write a specific position.

print(numbers[0]);    # → 1
print(numbers[2]);    # → 3

numbers[0] = 99;
print(numbers[0]);    # → 99

Length

The built-in len() intrinsic returns the number of elements.

print(len(numbers));  # → 5

Iteration

Arrays are iterable with for each and the indexed variant:

for each item in (numbers) {
    print(item);
}

for each item and idx in (numbers) {
    print(idx, ":", item);
}

Array methods preview

Arrays expose a set of mutation and query methods. A full reference is available on the Primitive Methods page; the most commonly used are:

Method	Description
`arr.push(value)`	Append a value to the end
`arr.pop()`	Remove and return the last element
`arr.shift()`	Remove and return the first element
`arr.unshift(value)`	Prepend a value to the front
`arr.indexOf(value)`	First index of `value`, or `-1`
`arr.includes(value)`	`true` if `value` is present
`arr.join(sep)`	Concatenate elements into a string
`arr.reverse()`	Reverse the array in place

var fruits = ["apple", "banana", "cherry"];
fruits.push("date");
print(fruits);                    # → ["apple", "banana", "cherry", "date"]
print(fruits.includes("banana")); # → true
print(fruits.join(", "));         # → "apple, banana, cherry, date"

Tuples

A tuple is an ordered, immutable sequence that can hold values of different types. Tuple literals use parentheses with comma-separated elements. The type annotation mirrors the literal form: (Int, String, Bool).

var point: (int, int)           = (10, 20);
var record: (int, String, bool) = (1, "hello", true);

Positional access

Elements are accessed by integer index, just like arrays:

print(point[0]);    # → 10
print(point[1]);    # → 20
print(record[1]);   # → "hello"

Tuples are immutable — attempting to assign to an index (t[0] = 5) will produce a runtime error. Use an array if you need mutation.

Tuples vs arrays

	Array	Tuple
Literal	`[1, 2, 3]`	`(1, "x", true)`
Type annotation	`int[]`	`(int, String, bool)`
Mutability	Mutable	Immutable
Element types	Homogeneous	Heterogeneous
Primary use	Collections	Fixed-shape multi-return, coordinates

Records

A record (also called an object or map) is an unordered collection of key-value pairs. Keys are strings; values can be any type. The type annotation Record<String, Int> describes a record whose values are all Int.

var user = {
    "name": "CLS",
    "version": 2,
    "active": true
};

Field access

Fields can be read using bracket notation with a string key:

print(user["name"]);     # → "CLS"
print(user["version"]);  # → 2

Common record methods

Method	Description
`rec.keys()`	Array of all keys
`rec.values()`	Array of all values
`rec.has(key)`	`true` if the key exists

print(user.keys());           # → ["name", "version", "active"]
print(user.has("version"));   # → true

Type annotation

var scores: Record<String, int> = {
    "Alice": 95,
    "Bob":   87,
    "Carol": 91
};

When all values share the same type, Record<String, int> (or another concrete type) is the right annotation. For mixed-type shapes, prefer a structure (see below) or an untyped var.

Structures

A structure defines a named flat schema — a set of typed fields that can be instantiated with a positional constructor. Structures have no methods or inheritance; they are pure data containers, lighter than classes.

Declaration

structure Person {
    name: String,
    age: int
};

Fields are listed as name: Type pairs separated by commas. There are no default values in the basic form; every field must be supplied at construction time.

Construction

Call the structure name as a function, passing field values positionally in declaration order:

var p = Person("Alice", 30);

Field access and mutation

Use dot notation to read or write individual fields:

print("Name:", p.name);           # → Name: Alice
print("Age:", toString(p.age));   # → Age: 30

# Mutate a field
p.name = "Bob";
print("Updated name:", p.name);   # → Updated name: Bob

Full structure example

structure Person {
    name: String,
    age: int
};

function main(args: String[]) -> int {
    var p = Person("Alice", 30);

    print("Nombre:", p.name);
    print("Edad:",   toString(p.age));

    p.name = "Bob";
    print("Nombre cambiado:", p.name);
    print("all structure:", p);

    return 0;
};

Structures vs classes

	`structure`	`class`
Methods	❌	✅
Inheritance	❌	✅ (`extends`)
`me` / `self`	❌	✅
Constructor syntax	Positional call	`class` body
Use case	Plain data record	Stateful object

Use structure when you need a lightweight named container for data. Use class when you need encapsulated behaviour, inheritance, or me references.

String interpolation

Strings in CLS support two interpolation forms: simple identifier substitution with $name and arbitrary expression substitution with ${expr}.

var name = "CLS";
var version = 2;

var msg  = "Hello, $name!";            # → "Hello, CLS!"
var info = "Version: ${version + 1}";  # → "Version: 3"

The ${...} form accepts any expression — arithmetic, function calls, member access, or nested interpolation.

Primitive Methods

Full reference for array, string, record, and tuple built-in methods.

Enums

Typed variants with identity — iteratable and switch-compatible.

Syntax & Types

Data & Control Flow

OOP & Modules

Data Structures in CLS: Arrays, Tuples, Records, and Structs

Arrays

Index access

Length

Iteration

Array methods preview

Tuples

Positional access

Tuples vs arrays

Records

Field access

Common record methods

Type annotation

Structures

Declaration

Construction

Field access and mutation

Full structure example

Structures vs classes

String interpolation

Primitive Methods

Enums

Build docs developers (and LLMs) love

Syntax & Types

Data & Control Flow

OOP & Modules

Documentation Index

​Arrays

​Index access

​Length

​Iteration

​Array methods preview

​Tuples

​Positional access

​Tuples vs arrays

​Records

​Field access

​Common record methods

​Type annotation

​Structures

​Declaration

​Construction

​Field access and mutation

​Full structure example

​Structures vs classes

​String interpolation

Primitive Methods

Enums

Build docs developers (and LLMs) love

Arrays

Index access

Length

Iteration

Array methods preview

Tuples

Positional access

Tuples vs arrays

Records

Field access

Common record methods

Type annotation

Structures

Declaration

Construction

Field access and mutation

Full structure example

Structures vs classes

String interpolation