Array

The Array object, as with arrays in other programming languages, enables storing a collection of multiple items under a single variable name, and has members for performing common array operations.

Katxupa is here just to extend the standard library by adding more utility functions to the Array type. Besides Array standard functions, the library provides the following functions:

Global Functions

listOf

Creates an immutable list from the provided elements.

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

mutableListOf

Creates a mutable list from the provided elements.

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.

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.

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.

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.

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.

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.

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.

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).

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).

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.

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.

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.

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.

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

last

Returns the last element in the array.

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

shuffle

Shuffles the elements in the array randomly.

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