112 lines
3.6 KiB
Markdown
112 lines
3.6 KiB
Markdown
# 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()
|
|
})
|
|
```
|
|
|