# Arrays
Arrays is a common value type for processing multiple items in a list. Arrays in BBScript 2 can be created via a series of elements separated by whitespace and surrounded by square brackets.
```bbscript
[item1 item2 item3]
(= list [foo bar])
```
They can be of any length and can contain any type inside. They can contain any number of item inside. Arrays can also be nested inside of other arrays.
If a function is passed into the array, BBScript will attempt to process the function during the creation of the array. Arrays are zero indexed.
---
## `count`
Returns the number of items inside the array.
```bbscript
(count array)
```
array
: The array to be checked. Must resolve to an array.
Return
: Returns the number of items in the array
---
## `index`
Returns the element at the given index of the array. If provided a value, will replace the element at the given index with the value instead and return it.
```bbscript
(index array index value)
```
array
: The array to be accessed. Must resolve to an array.
index
: The index of the element to access. Zero-indexed based. Must be less than total length and zero or positive. Must resolve to a number.
: `0` is the first element, `1` is the second, `2` is the third, etc.
value optional
: If provided, will replace the element at index with the given value.
Return
: Returns the value of the element at the given index
---
## `contain`
Returns true or false based on if the array contains the value given.
```bbscript
(contain array needle)
```
array
: The array to be searched. Must resolve to an array.
needle
: The element to search for. Can be any value.
Return
: Returns true if the array contains an element matching the needle, otherwise returns false.
---
## `find`
Returns the index of the first element matching the given needle in the array.
```bbscript
(find array needle)
```
array
: The array to be searched. Must resolve to an array.
needle
: The element value to find the index of.
Return
: Returns the zero index based position of the first occuring element to match the needle in the array. If it cannot be found, returns -1.
---
## `append`
Adds the given value to the end of the array.
```bbscript
(append array value)
```
array
: The array to be added to. Must resolve to an array.
value
: The value to be added. Can be any value.
Return
: Returns the length of the new array.
---
## `insert`
Inserts a new value into the array at the given index.
```bbscript
(insert array index value)
```
array
: The array to be added to. Must resolve to an array.
index
: The zero index based position to add the new value at. Does not replace the existing value.
value
: The value to be added as a new element into the array.
---
## `pop`
Removes the last element in the array and returns its value.
```bbscript
(pop array)
```
array
: The array to remove the value from. Must resolve to an array.
Return
: Returns the value of the element removed.
---
## `remove`
Removes the element at the index given from the array and returns its value.
```bbscript
(remove array index)
```
array
: The array to remove the value from. Must resolve to an array.
index
: The zero index based position of the element to be removed.
Return
: Returns the value of the element removed.
---
## `slice`
Performs a slice of the array and returns the subset of the array at the given start and end index.
```bbscript
(slice array start end)
```
array
: The array to take the subset from. Must resolve to an array.
start
: The start index of the first element to include in the subset. Must resolve to a number.
end
: The end index of the first element after the start to not be included in the subset. Must resolve to a number.
Return
: Returns a subset array containing elements between the start and end index given.
**Example**: The following code will return `[b c d]`.
```bbscript
(slice [a b c d e] 1 4)
```
---
## `join`
Combines an array of strings together to make one single string.
```bbscript
(join array separator)
```
array
: The array of strings to combine. Must resolve to an array of strings.
separator optional
: If provided, will insert the separator between each element at join.
: _Default_ - empty string `""`
**Example**:
```bbscript
(join [a b c d])
```
Returns `"abcd"`
```bbscript
(join [a b c d] "!")
```
Returns `"a!b!c!d"`
See also [BBScript 2 Strings](./BBScript:-BBScript-2:-Strings.md)
---
## `each`
Performs a given function on each element of an array. This acts like a `for-of` loop in Javascript.
```bbscript
(each array (function) token)
```
array
: The array of elements to perform the function on.
(function)
: The function to apply the logic on a given element. The element can be referenced using the token provided.
token optional
: The token to use to reference the element. Must resolve to a string.
: _Default_ - by default, uses `_`
**Example**:
```bbscript
(= sum 0)
(each [1 2 3] (group
(print _)
(= sum (+ sum _))
))
(print sum)
```
Will print:
```
1
2
3
6
```
See also [`group`](./BBScript:-BBScript-2:-Variables-&-Logic.md#group)
---
## `reverse`
Reverses the element order of the array.
```bbscript
(reverse array)
```
array
: The array to be reversed.
Return
: Returns the array reversed. The reversal is also done in place.
---
## `shuffle`
Shuffles the order of the elements in the array.
```bbscript
(shuffle array)
```
array
: The array to be shuffled
Return
: Returns a shuffled array.