> For the complete documentation index, see [llms.txt](https://katxupa.gitbook.io/katxupa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://katxupa.gitbook.io/katxupa/get-a-taste-of-katxupa/dip-dive/collections/array.md).

# 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]
```