# List Library (List)

### Example Usage

```rust
#[main]
fn main() {
    const array = [1, 2, 3];
    assert_eq(array.len(), 3);
    assert_eq(List.len(array), 3);
}
```

## List.any(array: list) -> bool

Does this list contain any values?

```rust
const array = [1];
assert(array.any());
```

## List.append(array: list, other: list) -> void

Append another list to this list, leaving other unmodified.

```rust
const array = [1, 2, 3];
array.append([4, 5]);
assert_eq(array, [1, 2, 3, 4, 5]);
```

## List.at(array: list, index: int) -> unknown

Get the value at the given index, optionally by reference.

```rust
const array = [1, 2, 3];
let v = &array[1]; // &List.at(array, 1);
v = 5;
assert_eq(array, [1, 5, 3]);
```

## List.back(array: list) -> unknown

Get the value at the back of this list, optionally by reference.

```rust
const array = [1, 2];
assert_eq(array.back(), 2);
```

## List.clear(array: list) -> void

Clear all values from this list.

```rust
const array = [1, 2, 3];
array.clear();
assert_eq(array, []);
```

## List.contains(array: list, value: unknown) -> bool

Does this list contain the given value?

```rust
const array = [1];
assert(array.contains(1));
```

## List.empty(array: list) -> bool

Is this list empty?

```rust
const array = [1];
assert_not(array.empty());
```

## List.front(array: list) -> unknown

Get the value at the front of this list, optionally by reference.

```rust
const array = [1];
assert_eq(array.front(), 1);
```

## List.index\_of(array: list, v: unknown) -> int

If the list contains the given value, return the index of the first matched value. Returns -1 if the list does not contain the given value.

```rust
const array = [1, 2, 3];
assert_eq(array.index_of(2), 1);
```

## List.insert(array: list, index: int, val: unknown) -> void

Insert a value into this list at the given index.

```rust
const array = [2, 1];
array.insert(1, 3);
assert_eq(array, [2, 3, 1]);
```

## List.is\_uniform(array: list) -> bool

Returns true if every value in this list has the same specific type (does not account for object prototype inheritance).

```rust
const array = ["hi", true];
assert_not(array.is_uniform());
```

## List.join(array: list, sep: str) -> str

Join the values in this array together into a single string.

```rust
const array = ["hello", "world"];
assert_eq(array.join(", "), "hello, world");
```

## List.len(array: list) -> int

Return the length of this list.

```rust
const array = [1, 2, 3];
assert_eq(array.len(), 3);
```

## List.pop\_back(array: list) -> unknown

Remove a single value from the back of this list and return it.

```rust
const array = [1, 2, 3];
assert_eq(array.pop_back(), 3);
assert_eq(array, [1, 2]);
```

## List.pop\_front(array: list) -> unknown

Remove a single value from the front of this list and return it.

```rust
const array = [1, 2, 3];
assert_eq(array.pop_front(), 1);
assert_eq(array, [2, 3]);
```

## List.push\_back(array: list, ..) -> void

Push N values to the back of this list.

```rust
const array = [1, 2, 3];
array.push_back(4, 5);
assert_eq(array, [1, 2, 3, 4, 5]);
```

## List.push\_front(array: list, ..) -> void

Push N values to the front of this list.

```rust
const array = [1, 2, 3];
array.push_front(4, 5);
assert_eq(array, [5, 4, 1, 2, 3]);
```

## List.remove(array: list, index: int) -> unknown

Remove a value at the given index and return it. Returns null if index is out of bounds.

```rust
const array = [1];
assert_eq(array.remove(0), 1);
assert(array.empty());
```

## List.remove\_all(array: list, val: unknown) -> bool

Remove all occurrances of a value in this array (equals) and return true if any were removed.

```rust
const array = [2, 1, 1, 2];
assert(array.remove_all(2));
assert_eq(array, [1, 1]);
```

## List.remove\_first(array: list, val: unknown) -> unknown

Remove the first occurrance of a value in this array (equals) and return it.

```rust
const array = [2, 1, 1, 2];
assert_eq(array.remove_first(2), 2);
assert_eq(array, [1, 1, 2]);
```

## List.remove\_last(array: list, val: unknown) -> unknown

Remove the last occurrance of a value in this array (equals) and return it.

```rust
const array = [2, 1, 1, 2];
assert_eq(array.remove_last(2), 2);
assert_eq(array, [2, 1, 1]);
```

## List.replace(array: list, index: int, val: unknown) -> unknown

Replace/set the value at the given index with a new value, returning the old.

```rust
const array = [2, 1];
assert_eq(array.replace(1, 4), 1);
assert_eq(array, [2, 4]);
```

## List.reverse(array: list) -> void

Reverses this list in-place.

```rust
const array = [1, 2, 3];
array.reverse();
assert_eq(array, [3, 2, 1]);
```

## List.reversed(array: list) -> list

Return a new list that is reversed, leaving this list unmodified.

```rust
const array = [1, 2, 3];
const other = array.reversed();
assert_eq(array, [1, 2, 3]);
assert_eq(other, [3, 2, 1]);
```

## List.sort(array: list) -> void

Sort the values in this array according to their already defined ordering.

```rust
const array = [2, 1, 4, 3];
array.sort();
assert_eq(array, [1, 2, 3, 4]);
```

## List.to\_uniform(array: list, type: str) -> void

Try casting all values in this list to the given type (given as a string like you would in a Stof file). Will throw an error if a value cannot be cast.

```rust
const array = [1, "hi", true];
array.to_uniform("str");
assert_eq(array, ["1", "hi", "true"]);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stof.dev/libraries/type-libraries/list-library-list.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.