Array Utils

ArrayUtil provides helpers for array manipulations. This utility class offers static methods to create, modify, and analyze arrays.

create

Creates a new array with the specified length, optionally filling it with the provided value.

static create<Type>(length:number, value?:Type):Type[]

const zeroArray = ArrayUtil.create(5, 0);
console.log(zeroArray);
// Output: [ 0, 0, 0, 0, 0 ]

const emptyArray = ArrayUtil.create(3);
console.log(emptyArray);
// Output: [ undefined, undefined, undefined ]

createSequence

Creates a numeric sequence as a new array, starting from the provided offset.

static createSequence(length:number, offset:number = 0):number[]

const reelsSpinOrder = ArrayUtil.createSequence(5);
console.log(reelsSpinOrder);
// Output: [ 0, 1, 2, 3, 5 ]

const offsetSequence = ArrayUtil.createSequence(3, 10);
console.log(offsetSequence);
// Output: [ 10, 11, 12 ]

wrapValue

Wraps a value in an array when it is not already an array, which simplifies APIs that accept either a single item or a collection.

static wrapValue<Type>(source:OneOrArray<Type>):Type[]

const wrappedNumber = ArrayUtil.wrapValue(42);
console.log(wrappedNumber);
// Output: [ 42 ]

const existingArray = [ 1, 2, 3 ];
const wrappedArray = ArrayUtil.wrapValue(existingArray);
console.log(wrappedArray);
// Output: [ 1, 2, 3 ]

console.log(existingArray === wrappedArray);
// Output: true

appendValue

Inserts a value into the array when it does not already exist.

static appendValue<Type>(source:Type[], value:Type):void

// Add a value to an array if it does not exist
const array = [ 1, 2, 3 ];
ArrayUtil.appendValue(array, 4);
console.log(array);
// Output: [ 1, 2, 3, 4 ]

// Attempt to add a duplicate value (array stays the same)
ArrayUtil.appendValue(array, 2);
console.log(array);
// Output: [ 1, 2, 3, 4 ]

insertValue

Inserts a value into the array at the specified position. When the value already exists it is moved to the new position, and the insertion is clamped to the array bounds.

static insertValue<Type>(source:Type[], value:Type, position:number):void

// Insert a value at a specific position in an array
const letters = [ 'a', 'c', 'd' ];
ArrayUtil.insertValue(letters, 'b', 1);
console.log(letters);
// Output: [ 'a', 'b', 'c', 'd' ]

// Move existing value to the new position
ArrayUtil.insertValue(letters, 'a', 4);
console.log(letters);
// Output: [ 'b', 'c', 'd', 'a' ]

appendWithPriority

Inserts a value into a priority-sorted array when it does not already exist, keeping higher priority values at the front.

static appendWithPriority<Type>(source:PriorityArray<Type>, value:Type, priority:number = 0):void

const priorityTasks:PriorityArray<string> = [];

ArrayUtil.appendWithPriority(priorityTasks, 'Low priority task', 1);
ArrayUtil.appendWithPriority(priorityTasks, 'Medium priority task', 5);
ArrayUtil.appendWithPriority(priorityTasks, 'High priority task', 10);

console.log(priorityTasks);
// Output: [
//   { priority: 10, value: 'High priority task' },
//   { priority: 5, value: 'Medium priority task' },
//   { priority: 1, value: 'Low priority task' }
// ]

appendWithComparator

Inserts a value into a sorted array by using the provided comparator to locate the correct position and avoid duplicates.

static appendWithComparator<Type>(source:Type[], value:Type, comparator:Comparator<Type>):void

const comparator = (a:number, b:number) => a - b;

const sortedNumbers = [ 1, 3, 5, 7 ];
ArrayUtil.appendWithComparator(sortedNumbers, 4, comparator);
console.log(sortedNumbers);
// Output: [ 1, 3, 4, 5, 7 ]

removeValue

Removes the first occurrence of the specified value from the array when it exists.

static removeValue<Type>(source:Type[], value:Type):void

const fruits = [ 'apple', 'banana', 'orange', 'grape', 'orange' ];
ArrayUtil.removeValue(fruits, 'orange');
console.log(fruits);
// Output: [ 'apple', 'banana', 'grape', 'orange' ]

ArrayUtil.removeValue(fruits, 'orange');
console.log(fruits);
// Output: [ 'apple', 'banana', 'grape' ]

ArrayUtil.removeValue(fruits, 'pear');
console.log(fruits);
// Output: [ 'apple', 'banana', 'grape' ]

removeWithPriority

Removes the first occurrence of a value from the priority-sorted array when it exists.

static removeWithPriority<Type>(source:PriorityArray<Type>, value:Type):void

const priorityQueue = [
    { priority: 10, value: 'High priority task' },
    { priority: 5, value: 'Medium priority task' },
    { priority: 1, value: 'Low priority task' }
];

ArrayUtil.removeWithPriority(priorityQueue, 'Medium priority task');
console.log(priorityQueue);
// Output: [
//   { priority: 10, value: 'High priority task' },
//   { priority: 1, value: 'Low priority task' }
// ]

cleanupValues

Creates a new array by removing all null or undefined values from the provided array.

static cleanupValues<Type>(source:Type[]):Type[]

const mixedArray = [ 1, null, 2, undefined, 3 ];
const cleanArray = ArrayUtil.cleanupValues(mixedArray);
console.log(cleanArray);
// Output: [ 1, 2, 3 ]

console.log(mixedArray === cleanArray);
// Output: false

swapValues

Swaps two values in the provided array by their indexes.

static swapValues<Type>(source:Type[], index_1:number, index_2:number):void

const letters = [ 'a', 'b', 'c', 'd' ];
ArrayUtil.swapValues(letters, 1, 3);
console.log(letters);
// Output: [ 'a', 'd', 'c', 'b' ]

isValuesEquals

Checks if two arrays contain the same values in the same order using strict equality.

static isValuesEquals<Type>(array_1:Type[], array_2:Type[]):boolean

const array1 = [ 1, 2, 3 ];
const array2 = [ 1, 2, 3 ];
const areEqual1 = ArrayUtil.isValuesEquals(array1, array2);
console.log(areEqual1);
// Output: true

const array3 = [ 1, 2, 3 ];
const array4 = [ 1, 3, 2 ];
const areEqual2 = ArrayUtil.isValuesEquals(array3, array4);
console.log(areEqual2);
// Output: false

shuffle

Randomly shuffles the elements of an array in place.

static shuffle<Type>(source:Type[]):void

const cards = [ 'A', '2', '3', '4', '5' ];
ArrayUtil.shuffle(cards);
console.log(cards);
// Output: A random cards order, e.g., [ '3', 'A', '5', '2', '4' ]