list

clear

|List| -> List

Clears the list by removing all of its elements, and returns the cleared list.

Example

x = [1, 2, 3]
x.clear()
# -> []

contains

|List, value: Any| -> Bool

Returns true if the list contains an element that matches the input value.

Matching is performed with the == equality operator.

Example

[1, 'hello', (99, -1)].contains 'hello'
# -> true

extend

|List, new_elements: Iterable| -> List

Extends the list with the output of the iterator, and returns the list.

Example

x = [1, 2, 3]
x.extend 'abc'
# -> [1, 2, 3, 'a', 'b', 'c']
x.last()
# -> c
x.extend [10, 20, 30]
# -> [1, 2, 3, 'a', 'b', 'c', 10, 20, 30]
x.last()
# -> 30

fill

|List, value: Any| -> List

Fills the list with copies of the provided value, and returns the list.

Example

x = [1, 2, 3]
x.fill 99
# -> [99, 99, 99]
x
# -> [99, 99, 99]

first

|List| -> Any

Returns the first value in the list, or Null if the list is empty.

Example

[99, -1, 42].first()
# -> 99

[].first()
# -> null

get

|List, index: Number| -> Any

|List, index: Number, default: Any| -> Any

Gets the element at the given index in the list.

If the list doesn't contain a value at that position then the provided default value is returned. If no default value is provided then null is returned.

Example

x = [99, -1, 42]

x.get 1
# -> -1

x.get -1
# -> null

x.get 5, 123
# -> 123

insert

|List, position: Number, value: Any| -> List

Inserts the value into the list at the given index position, and returns the list.

Elements in the list at or after the given position will be shifted to make space for the new value.

An error is thrown if position is negative or greater than the size of the list.

Example

x = [99, -1, 42]
x.insert 2, 'hello'
# -> [99, -1, 'hello', 42]
x
# -> [99, -1, 'hello', 42]

is_empty

|List| -> Bool

Returns true if the list has a size of zero, and false otherwise.

Example

[].is_empty()
# -> true

[1, 2, 3].is_empty()
# -> false

last

|List| -> Any

Returns the last value in the list, or Null if the list is empty.

Example

[99, -1, 42].last()
# -> 42

[].last()
# -> null

pop

|List| -> Any

Removes the last value from the list and returns it.

If the list is empty then Null is returned.

Example

x = [99, -1, 42]
x.pop()
# -> 42

x
# -> [99, -1]

[].pop()
# -> null

push

|List, value: Any| -> Any

Adds the value to the end of the list, and returns the list.

Example

x = [99, -1]
x.push 'hello'
# -> [99, -1, 'hello']
x
# -> [99, -1, 'hello']

remove

|List, position: Number| -> Any

Removes the value at the given position from the list and returns it.

Throws an error if the position isn't a valid index in the list.

Example

[99, -1, 42].remove 1
# [99, 42]

resize

|List, new_size: Number| -> List

|List, new_size: Number, default: Any| -> List

Grows or shrinks the list to the specified size, and returns the list. If the new size is larger, then copies of the default value (or null if no value is provided) are used to fill the new space.

Example

x = [1, 2]
x.resize 4, 'x'
# -> [1, 2, 'x', 'x']

x.resize 3
# -> [1, 2, 'x']

x.resize 4
# -> [1, 2, 'x', null]

resize_with

|List, new_size: Number, generator: || -> Any| -> List

Grows or shrinks the list to the specified size, and returns the list. If the new size is larger, then the provided function will be called repeatedly to fill the remaining space, with the result of the function being added to the end of the list.

Example

new_entries = (5, 6, 7, 8).iter()
x = [1, 2]
x.resize_with 4, || new_entries.next().get()
# -> [1, 2, 5, 6]

x.resize_with 2, || new_entries.next().get()
# -> [1, 2]

retain

|List, test: Any| -> List

Retains matching values in the list (discarding values that don't match), and returns the list.

If test is a function, then the function will be called with each of the list's values, and if the function returns true then the value will be retained, otherwise if the function returns false then the value will be discarded.

If the test value is not a function, then the list's values will be compared using the == equality operator, and then retained if they match.

Example

x = (1..10).to_list()
x.retain |n| n < 5
# -> [1, 2, 3, 4]
x
# -> [1, 2, 3, 4]

x = [1, 3, 8, 3, 9, -1]
x.retain 3
# -> [3, 3]
x
# -> [3, 3]

reverse

|List| -> List

Reverses the order of the list's contents, and returns the list.

Example

x = ['hello', -1, 99, 'world']
x.reverse()
# -> ['world', 99, -1, 'hello']
x
# -> ['world', 99, -1, 'hello']

sort

|List| -> List

Sorts the list in place, and returns the list.

|List, key: |Any| -> Any| -> List

Sorts the list in place, based on the output of calling a key function for each of the list's elements, and returns the list.

The key function's result is cached, so it's only called once per element.

Example

x = [1, -1, 99, 42]
x.sort()
# -> [-1, 1, 42, 99]
x
# -> [-1, 1, 42, 99]

x = ['bb', 'ccc', 'a']
x.sort size
# -> ['a', 'bb', 'ccc']
x
# -> ['a', 'bb', 'ccc']

x = [2, 1, 3]
# Sort in reverse order by using a key function
x.sort |n| -n
# -> [3, 2, 1]
x
# -> [3, 2, 1]

swap

|first: List, second: List| -> Null

Swaps the contents of the two input lists.

Example

x = [1, 2, 3]
y = [7, 8, 9]
x.swap y

x
# -> [7, 8, 9]

y
# -> [1, 2, 3]

to_tuple

|List| -> Tuple

Returns a copy of the list data as a tuple.

Example

[1, 2, 3].to_tuple()
# -> (1, 2, 3)

transform

|List, transformer: |Any| -> Any| -> List

Transforms the list data in place by replacing each value with the result of calling the provided transformer function, and then returns the list.

Example

x = ['aaa', 'bb', 'c']
x.transform size
# -> [3, 2, 1]
x
# -> [3, 2, 1]

x.transform |n| '{n}!'
# -> ['3!', '2!', '1!']
x
# -> ['3!', '2!', '1!']