Maps

Maps in Chuks are unordered collections of key-value pairs. Keys must be primitive types (strings, integers, booleans), but values can be anything — including other collections or custom types. All map methods are built-in and require no imports.

Declaration and Initialization

Maps are declared using the map[KeyType]ValueType syntax.

// Map from strings to integers
var scores: map[string]int = {
    "Alice": 95,
    "Bob": 88
};

// Map with string keys and any values
var settings: map[string]any = {
    "darkMode": true,
    "theme": "ocean",
    "version": 2
};

Accessing Elements

Use square bracket notation with the key. If a key doesn’t exist, the returned value is null.

var score = scores["Alice"];
scores["Charlie"] = 92;      // Add or update

Properties

length: int

Returns the number of key-value pairs in the map.

println(scores.length); // 2

size: int

Alias for length.

println(scores.size); // 2

Methods

set(key: K, value: V): map[K]V

Sets the value for the given key and returns the map, allowing method chaining.

var m: map[string]int = {};
m.set("a", 1).set("b", 2).set("c", 3);
println(m); // {a: 1, b: 2, c: 3}

get(key: K): V?

Returns the value for the given key, or null if not found. The result type is V? — narrow with a null check, or coalesce with ??.

var m: map[string]int = {"x": 10, "y": 20};

var v1: int? = m.get("x");   // 10
var v2: int? = m.get("z");   // null

// Provide a default with ??
var safe: int = m.get("z") ?? 0;  // 0

Returning V? (instead of V) means null is unambiguously distinguishable from a legitimate zero-ish value (0, "", false). If you know the key is present — or you want a typed default in one step — prefer getOr.

getOr(key: K, default: V): V

Returns the value for the given key, or the provided default if the key is missing. Unlike get, the result type is V (not V?), so no narrowing or ?? is needed.

var m: map[string]int = {"alice": 95};

var a: int = m.getOr("alice", 0);     // 95
var b: int = m.getOr("missing", 0);   // 0

getOr is the zero-allocation path for hot lookups with a fixed default.

has(key: K): bool

Returns true if the map contains the given key.

var m: map[string]int = {"x": 10};
println(m.has("x")); // true
println(m.has("z")); // false

keys(): []K

Returns an array of all keys. Order is not guaranteed.

var names = scores.keys();
// names might be ["Alice", "Bob"] or ["Bob", "Alice"]

values(): []V

Returns an array of all values.

var allScores = scores.values();
// allScores might be [95, 88]

entries(): []any

Returns an array of [key, value] pairs.

var m: map[string]int = {"x": 1, "y": 2};
var pairs: any = m.entries();
println(pairs); // [["x", 1], ["y", 2]]

delete(key: K): void

Removes the key-value pair for the given key. Does nothing if the key doesn’t exist.

scores.delete("Alice");
// scores now only contains {"Bob": 88}

clear(): void

Removes all elements from the map.

scores.clear();
println(scores.length); // 0

forEach(callback: function): void

Executes a callback for each key-value pair. Callback receives (value, key, map).

var m: map[string]int = {"a": 1, "b": 2, "c": 3};
m.forEach(function(val: any, key: any, mp: any): any {
    println(key, "=", val);
});

getName(value: V): K

Returns the key associated with the given value. Useful for reverse lookups.

var m: map[string]int = {"Alice": 95, "Bob": 88};
println(m.getName(95)); // "Alice"

isValid(value: V): bool

Returns true if the value exists in the map.

var m: map[string]int = {"Alice": 95, "Bob": 88};
println(m.isValid(95));  // true
println(m.isValid(100)); // false

Iterating Over Maps

Use a for...in loop to iterate over map keys:

var scores: map[string]int = {"math": 90, "science": 85};
for (var key in scores) {
    println(key + ": " + scores[key]);
}

Or use the forEach method for a functional style:

scores.forEach(function(val: any, key: any, mp: any): any {
    println(key + " = " + val);
});