pxt-calliope/docs/reference/js/collections.md
2016-03-29 21:17:57 -07:00

3.6 KiB

The Collections Library

#docs

A collection allows you to store an arbitrary number of elements. If you have a collection of numbers, you can add new numbers to the collection; remove numbers; check if a number is in there; iterate over all the numbers in the collection.

Creation

A collection is created as follows. Note that we are providing the type of the elements that are meant to go in the collection.

let c = (<number[]>[])

At the moment, you can create collections of numbers, booleans, strings, and any of the object types that you defined.

Important: if your collection is a global variable, make sure you initialise it at the beginning of your script.

c = (<boolean[]>[])

Trying to use an uninitialised collection will crash the simulator, and display a sad face on the device.

Adding and finding elements; counting

c.push(3)

The line above just added the number 3 to the collection. One can think of a collection as a list, where add appends the element at the end of the list.

At this stage, our collection has size 1, meaning that the line below will display 1.

basic.showNumber(c.length, 150)

We can add another number as follows.

c.push(5)

At this stage, the count of elements in the collection is 2. We mentioned earlier that a collection is like a list: adding elements appends them at the end of the list. This means that, at this point in the program, the first element in the list is 3 (we added it earlier), and the second element in the list is 5 (we just added it).

basic.showNumber(c[0], 150)

Can you guess what the line above does? Remember that in computing, indexing starts at zero. This function takes the first element in the list. This means that the line above displays 3.

We can ask questions such as: "what is the index of this element"? The line below displays 1, meaning that the number 5 is first found at index 1 (it is the second element in the list).

basic.showNumber(c.indexOf(5, 0), 150)

Iterating over the elements

A classic pattern consists in iterating over all the elements in the collection. Here's one way to do it:

for (let i = 0; i < c.length; i++) {
    basic.showString("The element at index " + i.toString() + " is " + c[i].toString(), 150)
}

The code above will first print The element at index 0 is 3, then The element at index 1 is 5.

Modifying and removing elements

One can modify an existing collection using set at, which changes the element at a given index.

c[0] = 7

The line above modifies the collection c so that, after the line above, the first element of the collection is now 7.

Removing elements can be done in two different ways. We can remove the first occurrence of an element.

c.remove(5)

This removes the first occurrence of 5 in the list. At this point in the program, our list now has just one element (at index 0). If we wish, we can use remove at to remove the element at a given index.

c.splice(0, 1)

Now, the collection is empty.

Complete example

This program will record the current acceleration measured on x when you press A; when you press B, the program will print out all the acceleration values that were measured, then will clear the collection.

let accelerations = (<number[]>[])
input.onButtonPressed(Button.A, () => {
    accelerations.push(input.acceleration("x"))
})
input.onButtonPressed(Button.B, () => {
    for (let i1 = 0; i1 < accelerations.length; i1++) {
        basic.showString(accelerations[i1].toString(), 150)
    }
    accelerations.clear()
})