Arrays Collections

Arrays & Collections

SQ# provides dynamic arrays, hashmaps, and namespaces for data storage and organization.

Arrays

Arrays are zero-based, dynamic, mutable, by-reference — same as SQF.

Creation

_arr = [1, 2, 3];              // literal
_arr = [];                     // empty
_arr resize 10;                // pre-allocate [nil, nil, ...]
_arr = +_otherArr;             // shallow copy
_arr = +_otherArr;             // deep copy (unary +)

Element Access

_arr select 0;                 // first element
_arr # 0;                      // hash-select syntax (sugar)
_arr[0];                       // bracket syntax (sugar)
_arr select 99;                // out of range → nil (no error!)

Mutation

_arr pushBack 42;              // append — returns new index
_arr append [5, 6];            // bulk append
_arr set [0, 99];              // replace element
_arr deleteAt 2;               // remove — returns deleted value
_arr deleteRange [1, 2];       // remove range
_arr resize 5;                 // grow (nil fill) or shrink

Search & Check

_arr find "target";            // index, or -1
"target" in _arr;              // true/false membership
count _arr;                    // length

Sort & Reverse

_arr sort true;                // ascending (nil to end)
_arr sort false;               // descending
reverse _arr;                  // in-place reverse

Iteration

// forEach — most common
_arr forEach {
    print f"[{_forEachIndex}] {_x}";
};

// for loop — when index matters
for "_i" from 0 to (count _arr - 1) do {
    _elem = _arr select _i;
    _arr set [_i, process(_elem)];
};

Copying

_shallow = +_arr;              // new array, same element references
_deep = +_arr;                 // unary + copies sub-arrays too

Frozen Arrays (Immutable)

_frozen = freeze _arr;         // immutable snapshot — safe to share across schedulers
isFrozen _frozen;              // true
scheduler _frozen;             // -1 (no owner)

_mutable = thaw _frozen;       // create new mutable copy

HashMaps

Key-value dictionaries with O(1) lookup.

Creation

_map = createHashMap;                                   // empty
_map = createHashMapFromArray ["a", 1, "b", 2, "c", 3]; // from flat array

Operations

_map set ["health", 100];      // store
_map set ["name", "player"];
_hp = _map get "health";       // retrieve — nil if missing
_name = _map get "name";
_missing = _map get "xyz";     // nil

Key Types

Valid keys: Number, String, Boolean, Code, NaN. Arrays must be frozen to be keys:

_map set [42, "answer"];               // OK
_map set [freeze [1, 2], "coord"];     // OK
_map set [[1, 2], "coord"];            // THROWS — mutable array

Iteration

HashMaps do not support forEach directly. Use a helper:

// If host provides keys/values commands:
_keys = _map keys;
{ print f"{_x} = {_map get _x}" } forEach _keys;

Nested Structures

_player = createHashMap;
_player set ["name", "John"];
_stats = createHashMap;
_stats set ["hp", 100];
_stats set ["xp", 500];
_player set ["stats", _stats];

// Access nested value
_xp = (_player get "stats") get "xp";  // 500

Namespaces

Named global variable stores (SQF compat):

// missionNamespace — default global namespace
missionNamespace setVariable ["myData", 42];
_val = missionNamespace getVariable "myData";  // 42

// Custom namespace
_myNS = createNamespace;
_myNS setVariable ["config", _configData];

Common Patterns

Using HashMap as Struct

_unit = createHashMapFromArray [
    "name", "Soldier",
    "hp", 100,
    "position", [0, 0, 0],
    "alive", true
];

Frequency Counter

_freq = createHashMap;
_items forEach {
    _count = _freq get _x;
    if (isNil "_count") then { _count = 0 };
    _freq set [_x, _count + 1];
};

Set (Unique Values)

_set = createHashMap;
{ _set set [_x, true] } forEach _values;
_uniques = []; // extract keys if host supports it

Lookup Table

_damageTable = createHashMapFromArray [
    "fire", 25,
    "ice", 15,
    "lightning", 40,
    "poison", 10
];
_dmg = _damageTable get _elementType;

Thread Safety

Arrays and HashMaps are owned by the scheduler that created them. Cross-scheduler access requires:

• freeze — make immutable snapshot
• sendTo — transfer ownership
• shared — atomic variables (numbers only)

// Prepare data for another scheduler:
_frozen = freeze _bigArray;
// _frozen is now readable from any scheduler

See Also

• count — array/string length
• select — element at index
• pushBack — append element
• append — bulk append
• deleteAt — remove by index
• find — search index
• in — membership check
• forEach — iterate
• sort — sort in-place
• freeze — make immutable
• thaw — make mutable copy
• createHashMap — empty hashmap
• createHashMapFromArray — from array
• get — hashmap/array/shared access
• set — hashmap/array/shared write