Collections

Introduction

A variable that is not atomic, is called a collection. Collections have one of two different variabletypes, which are LIST and OBJECT. A list is a numbered array of items, while an object consists of key-value pairs. A value can be atomic or a collection itself. The built-in package with functions regarding collections is also called Collection.

For more practical examples, visit the tutorial about collections.

Declaration

Declaring collections closely follows JSON syntax:

var emptyList = [];
var emptyObject = {};

var simpleList = ["a", "b", "c"];
var simpleObject = {
    "first": "a",
    "second": "b",
    "third": "c",
    "this is a complex key": "d"
};

var nestedObject = {
    "first": {
        "seventh": "a",
        "tenth": "b"
    },
    "second": "c",
};

Accessing items

Dot notation

The dot notation is used for objects where the keys are hardcoded and don't have spaces. It does not use quotes.

System.print(nestedObject.first.tenth);
System.print(nestedObject.second);

Bracket notation 

System.print(simpleList[0]); // use the first element, which has index 0
System.print(simpleObject["this is a complex key"]); // use element with literal key
var key_from_variable = "second";
System.print(simpleObject[key_from_variable]); // use element with a key from a variable

Changing and adding elements

The bracket- and dot notation are used the same way when reassigning elements.

nestedObject.first.tenth = "new";
nestedObject.second = "new";
simpleList[0] = "new";
simpleObject["this is a complex key"] = "new";
var key_from_variable = "second";
simpleObject[key_from_variable] = "new";

To add new elements, assign values to keys that did not exist yet, or provide no key at all by using empty brackets. The new elements will be added at the bottom.

simpleList[List.length(simpleList)] = "new";
simpleList[] = "new";
simpleList[15] = "new"; // null values will be added between the previously highest index and the new index 15
simpleObject["new key"] = "new";

Passing and copying behavior

Xill collection variables implicitly hold references to their collection as value, instead of the collection itself. While doing most operations, this is hidden and it seems like the value of the variable is the actual content, just like it is for atomic variables. But when copying such a variable, only a reference is copied. And when passing one of these variables to a function, only that reference is passed. In both cases, there is only one collection, and more than one reference. Since passing always goes by value, reassigning one reference doesn't reassign the referenced collection, or other references to the same collection. But since more references point to the same collection, editing elements in the collection can be done with any of these variable instances, in any scope.

var simpleList_reference_copy = simpleList;
simpleList_reference_copy[] = "new";
// this adds a new element to the one list that is referenced by both 'simpleList' and 'simpleList_reference_copy'

There is still a way to make an independent copy of a collection. Use the function Collection.duplicate() if you need an extra instance of the same collection. 

var simpleList_copy = List.duplicate(simpleList);
simpleList_copy[] = "new";
// this adds a new element to the list that is referenced by 'simpleList_copy'.
// it leaves the original list, referenced by 'simpleList', untouched