Collections

# XCX 3.0 Collections

Arrays

array:i: nums {10, 20, 30};
nums.size();           --- 3
nums.get(0);           --- 10
nums.push(40);         --- adds 40 to the end
i: last = nums.pop();  --- removes and returns last element
nums.sort();           --- sorts in-place
nums.reverse();        --- reverses in-place
nums.show();           --- prints contents to terminal

Array Methods

array:i: nums {5, 2, 8, 1};
nums.sort();            --- {1, 2, 5, 8}
nums.reverse();         --- {8, 5, 2, 1}
nums.push(99);          --- {8, 5, 2, 1, 99}
i: last = nums.pop();   --- last = 99, nums = {8, 5, 2, 1}
nums.insert(1, 15);     --- inserts 15 at position 1
nums.update(0, 5);      --- sets element 0 to 5
nums.delete(3);         --- removes element at position 3
b: found = nums.contains(5);
i: idx   = nums.find(5);
b: empty = nums.isEmpty();

Sets

Domains

Initialization

Sets can be initialized with explicit values or ranges. Ranges are inclusive on both sides.

set:N: small  {1,,5};                  --- {1, 2, 3, 4, 5}
set:N: evens  {0,,100 @step 2};        --- {0, 2, 4, ...}
set:Q: thirds {0.0,,1.0 @step 0.33};
set:C: letters {"A",,"Z"};            --- all uppercase letters

Sets automatically deduplicate elements.

Set Operations

set:N: setA {1,,5};
set:N: setB {3,,7};

set:N: u  = setA UNION setB;
set:N: i  = setA INTERSECTION setB;
set:N: d  = setA DIFFERENCE setB;
set:N: sd = setA SYMMETRIC_DIFFERENCE setB;

--- Unicode symbols are equivalent
setA ∪ setB
setA ∩ setB
setA \ setB
setA ⊕ setB

Set Methods

Random Selection and Iteration

--- Random selection from a set:
i: picked_set = random.choice from small;

--- Random selection from an array:
array:i: nums {1, 2, 3, 4, 5};
i: picked_arr = random.choice from nums;

Picking from an empty set or array returns false.

Iteration

for p in small do;
    >! p;
end;

Maps

map: ages {
    schema = [s <-> i]
    data = [ "alice" :: 30, "bob" :: 25 ]
};

--- Empty Map
map: scores {
    schema = [s <-> i]   --- both separators are equivalent (<-> and <=>)
    data = [EMPTY]
};

Map Methods

Map keys are converted to strings in the resulting JSON object.

Map Serialization (toJson)

Signature

.toJson() → json

Description

Serializes the map to a JSON object. All keys are converted to strings using their .toString() representation to satisfy JSON object key requirements.

map: scores {
    schema = [s <-> i]
    data = [ "alice" :: 100, "bob" :: 85 ]
};
json: j = scores.toJson();

JSON Output:

{
    "alice": 100,
    "bob": 85
}

Behavior for Special Cases

• Empty Map: Returns an empty object {}.
• Nested Structures: If a map contains arrays, other maps, or tables, they are recursively serialized to their JSON equivalents.
• Key Conversion: All map keys are converted to strings in the resulting JSON object using their standard .toString() representation.

Type Mapping

Always use .contains() before .get():

if (ages.contains("alice")) then;
    >! ages.get("alice");
end;

Tables

Relational data structures with optional auto-increment columns.

table: products {
    columns = [ id :: i @auto, name :: s, price :: f ]
    rows = [ ("Laptop", 2999.99), ("Phone", 1499.50) ]
};

--- Empty Table
table: logs {
    columns = [ id :: i @auto, msg :: s ]
    rows = [EMPTY]
};

The @auto modifier on an i column creates an auto-incremented ID — it is skipped in .insert() and .add().

[!NOTE] Additional column attributes (@pk, @unique, @optional, @default(v), @fk(t.col)) are used when connecting a table to a database. See Database Documentation for details.

Row Access

products[0].name    --- "Laptop" (sugar for .get(0))
products[1].price   --- 1499.50

Table Methods

Named Arguments for .add() and .insert()

When a table has database column attributes, values can be passed by column name instead of position. Named arguments are optional — positional calls remain fully valid.

table: users {
    columns = [
        id    :: i @auto @pk,
        name  :: s @unique,
        age   :: i,
        phone :: s @optional,
        role  :: s @default("user")
    ]
    rows = [EMPTY]
};

--- Positional (backward compatible)
users.add("Alice", 25, "", "user");

--- Named
users.add(name = "Alice", age = 25, phone = "", role = "user");

--- Mixed — positional args must come first
users.add("Alice", age = 25, role = "admin");

Namespace separation. The left side of = is always the column name. The right side is an expression from the local scope. These are two independent namespaces — no conflict:

s: name = "Alice";
users.add(name = name, age = 25);
--- left "name"  = column users.name
--- right "name" = local variable

Rules: positional args must precede named; @auto columns can never be passed; omitting a required (non-@optional, non-@default) column is a compile error; duplicate column names in the same call are a compile error. See Database Documentation for the full specification.

Filtering (where)

--- Shorthand syntax (column names usable directly)
table: expensive = products.where(price > 1000.0);
table: named     = products.where(name HAS "Pro");

--- Lambda
table: r = products.where(row -> row.price > 1000.0);

--- Chaining
table: result = products
    .where(price > 1000.0)
    .where(name HAS "Pro");

[!IMPORTANT] Name Conflicts in .where() (S301): Column names take precedence over local variables inside predicates. If a local variable has the same name as a column, rename the variable to avoid a compile error.

--- Wrong (conflict: 'token' exists both as column and parameter)
fiber verify(s: token) {
    table: sess = db.sessions.where(token == token);
};

--- Correct
fiber verify(s: t) {
    table: sess = db.sessions.where(token == t);
};

Joins

--- Key-based join
table: report = users.join(orders, "id", "user_id");

--- Lambda join
table: custom = tableA.join(tableB, (a, b) -> a.id == b.ref_id);

When joined tables share a column name (other than the join key), the resulting column is prefixed with {table_name}_.

Serialization (toJson)

Signature

.toJson() → json

Description

Serializes all rows of a table to a JSON array, where each row becomes an object with keys corresponding to column names. @auto columns are included in the result.

Format

Always returns a JSON array ([...]). An empty table returns [].

table: products {
    columns = [ id :: i @auto, name :: s, price :: f ]
    rows = [ ("Laptop", 2999.99), ("Phone", 1499.50) ]
};

json: result = products.toJson();

JSON Output:

[
    {"id": 1, "name": "Laptop", "price": 2999.99},
    {"id": 2, "name": "Phone",  "price": 1499.50}
]

Type Mapping

Behavior for Special Cases

• Empty Table: Returns an empty array [].
• Filtered Table: Only rows currently in the table (after .where()) are serialized.
• Joined Table: All columns from the joined result are included.