# Array

The **`Array`** object, as with arrays in other programming languages, enables [storing a collection of multiple items under a single variable name](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/First_steps/Arrays), and has members for [performing common array operations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#examples).

*Katxupa* is here just to extend the standard library by adding more utility functions to the Array type. Besides [Array standard functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), the library provides the following functions:

## Global Functions

### listOf

Creates an immutable list from the provided elements.

```typescript
const immutableList = listOf(1, 2, 3);
// immutableList is [1, 2, 3]
```

### mutableListOf

Creates a mutable list from the provided elements.

```typescript
const mutableList = mutableListOf(1, 2, 3);
// mutableList is [1, 2, 3]
```

### emptyList

Creates an empty list. It returns an empty array, which represents the list.

```typescript
const emptyArray = emptyList();
console.log(emptyArray); // []
```

## Class Functions

### getOrElse

Gets the element at the specified index or provides a default value if the index is out of bounds.

```typescript
const collection = mutableListOf(1, 2, 3, 4, 5);
const element = collection.getOrElse(2, () => 10);
// element is 3
```

### getOrEmpty

Gets an optional containing the element at the specified index.

```typescript
const collection = mutableListOf(1, 2, 3, 4, 5);
const optionalElement = collection.getOrEmpty(2);
// optionalElement contains the value Optional.of(3)
```

### associateWith

Associates each element with a key-value pair based on the provided selectors.

```typescript
const elements = [{ id: 1, value: 'a' }, { id: 2, value: 'b' }];
const keyValuePairs = elements.associateWith(
  (element) => element.id,
  (element) => element.value
);
```

### sortBy

Sorts the array using the provided comparator function.

```typescript
const users = [
  { name: 'John', age: 30 },
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 35 },
];
collection.sortBy((a, b) => a.age - b.age);
// users is now sorted by age: 
// [{ name: 'Alice', age: 25 }, { name: 'John', age: 30 }, { name: 'Bob', age: 35 }]
```

### plus

Concatenates the array with another array.

```typescript
const collection = mutableListOf(1, 2, 3);
const otherArray = [4, 5, 6];
const result = collection.plus(otherArray);
// result is [1, 2, 3, 4, 5, 6]
```

### minus

Removes elements from the collection that are present in another array.

```typescript
const collection = mutableListOf(1, 2, 3, 4, 5);
const elementsToRemove = [3, 5];
const result = collection.minus(elementsToRemove);
// result is [1, 2, 4]
```

### minusAssign

Appends elements from another array to the collection (mutates the collection).

```typescript
const collection = mutableListOf(1, 2, 3, 4, 5);
const elementsToRemove = [3, 5];
collection.minusAssign(elementsToRemove);
// collection is now [1, 2, 4]
```

### plusAssign

Appends elements from another array to the collection (mutates the collection).

```typescript
const collection = mutableListOf(1, 2, 3);
const additionalElements = [4, 5, 6];
collection.plusAssign(additionalElements);
// collection is now [1, 2, 3, 4, 5, 6]
```

### count

Returns the number of elements in the collection.

```typescript
const count = mutableListOf(1, 2, 3, 4, 5).count();
// count is 5
```

### removeAll

Removes elements from the collection based on a predicate or a collection of elements.

```typescript
const collection = mutableListOf(1, 2, 3, 4, 5);
const elementsToRemove = [3, 5];
const result = collection.removeAll(elementsToRemove);
// result is [1, 2, 4]
```

### retainAll

Retains only the elements in the collection that are present in another array.

```typescript
const collection = mutableListOf(1, 2, 3, 4, 5);
const elementsToRetain = [3, 5];
const result = collection.retainAll(elementsToRetain);
// result is [3, 5]
```

### first

Returns the first element in the collection.

```typescript
const collection = mutableListOf(1, 2, 3);
const firstElement = collection.first();
// firstElement is 1
```

### last

Returns the last element in the array.

```typescript
const collection = mutableListOf(1, 2, 3);
const lastElement = collection.last();
// lastElement is 3
```

### shuffle

Shuffles the elements in the array randomly.

```typescript
const collection = mutableListOf(1, 2, 3, 4, 5);
collection.shuffle();
// collection is now shuffled randomly, e.g., [3, 1, 5, 2, 4]
```


---

# 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://katxupa.gitbook.io/katxupa/get-a-taste-of-katxupa/dip-dive/collections/array.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.