Private constructorStatic cloneWARNING:EXPERIMENTAL Deep clone an array, and return the result.
Shortcut of xjs_Object.cloneDeep, but for arrays. Warning: passing in a sparse array can yield unexpected results.
the array to clone
an exact copy of the given array
T - the type of elements in arr
Static containsTest whether an array is a subarray of another array.
This method acts like
String#includes,
testing whether
the elements in the smaller array appear consecutively and in the same order as in the larger array.
In other words, if {@link xjs_Array.is}(larger.slice(a,b), smaller) (for some integers a and b),
then this method returns true.
Warning: passing in sparse arrays can yield unexpected results.
Elements are compared via the provided predicate. If no predicate is provided, this method uses the default predicate xjs_Object.sameValueZero.
'twofoursix'.includes('wofo')===true
xjs.Array.contains([2,'w','o',4,'o','u','r',6,'i','x'], ['w','o',4,'o'])===true
xjs.Array.contains([2,'w','o',4,'o','u','r',6,'i','x'], ['o','u'])===true
xjs.Array.contains([2,'w','o',4,'o','u','r',6,'i','x'], [6,'o','u','r'])===false // not in the same order
xjs.Array.contains([2,'w','o',4,'o','u','r',6,'i','x'], [2,4,6])===false // not consecutive
xjs.Array.contains([2,4,6], [2,4,6,8]) // throws a RangeError: first array is smaller than second
is smaller a subarray of larger?
T - the type of elements in larger and smaller
if the second array is larger than the first
use xjs_Array.isConsecutiveSuperarrayOf instead.
Static densifyRemove the ‘holes’ in an array.
(Make a sparse array dense, or keep a dense array dense). This method is Pure — it does not modify the given argument.
A sparse array is an array whose length is greater than the number of elements its contains.
For example, new Array(4) is a sparse array: it has a length of 4 but no elements.
Sparse arrays are said to have a ‘hole’ where there is an index but no element.
A dense array is an array whose length is equal to its number of elements.
Note that accessor notation is not sufficient to detect sparseness: calling new Array(4)[0]
will return undefined, even though undefined is not an element in the array.
For example, const arr = ['a', 'b', , 'd'] is a sparse array because arr[2] has not been defined.
Evaluating arr[2] will yield undefined, even though it has not been explicitly declared so.
an array to make dense
a copy of the given array, but with no ‘holes’;
the returned array might have a smaller length than the argument
T - the type of elements in arr
Static fillFill the ‘holes’ in an array with a given value.
This method is Pure — it does not modify the given argument.
Similar to xjs_Array.densify, but instead of removing the holes of a sparse array (thus decreasing the length), this method fills the holes with a given value, thus maintaining the original array’s length.
Warning: This method has an important side-effect:
It treats entries of undefined as ‘holes’, even if they were intentionally declared.
Therefore this method is not well-suited for arrays with intentional entries of undefined.
Suggestion: replace all intentional entries of undefined with null.
a copy of the given array, but with all holes and undefineds filled;
the returned array will have the same length as the argument
T - the type of elements in arr
Static filterAsynchronous Array#filter.
the array to filter
function to test each element of the array
object to use as this when executing predicate
a new array with the elements that pass the test; if no elements pass, an empty array is returned
T - the type of elements in the array
Static findAsynchronous Array#find.
the array to search
function to test each element of the array
object to use as this when executing predicate
the item found, or null if none is found
T - the type of elements in the array
Static forPerform a callback function on an array, aggregating any errors caught.
Instead of throwing on the first error and stopping iteration, as Array#forEach would do, this method continues performing the callback on the rest of the array until all items are done. If only one error was caught, then that error is simply rethrown. However, if more errors were caught, they are collected into a single AggregateError, which is then thrown. If no errors are caught, this method returns void.
the array of items
the function to call on each item
xjs.Array.forEachAggregated<number>([1, 2, 3, 4], (n) => {
if (n % 2 === 0) {
throw new Error(`${ n } is even.`);
};
});
// Expected thrown error:
AggregateError {
errors: [
Error { message: "2 is even." },
Error { message: "4 is even." },
]
}
T the type of items in the array
if two or more iterations throws an error
if one iteration throws an error
Static forExecutes a callback on each item of an array until that callback returns.
If any iteration throws, the error is stored, and execution proceeds to the next iteration. If any iteration returns, this method returns void and the errors are discarded. If all iterations throw, the stored errors are collected into a single AggregateError, which is then thrown. (If there is only one error stored then it is simply rethrown.)
The “dual” of Array#forEach — this method returns as soon as a callback call is successful; otherwise throws.
Similar to Promise.any, but synchronous.
the array of items
the function to call on each item
let update = 0;
xjs.Array.forEither<number>([1, 2, 3, 4], (n) => {
update = n;
if (n % 2 === 0) {
throw new Error(`${ n } is even.`);
}
});
// Expected result:
assert.strictEqual(update, 1);
T the type of items in the array
if two or more iterations throws an error
if one iteration throws an error
Static freezeDeep freeze an array, and return the result.
Shortcut of xjs_Object.freezeDeep, but for arrays. Warning: passing in a sparse array can yield unexpected results. Note: This function is impure, modifying the given argument.
the array to freeze
the given array, with everything frozen
use interface readonly T[] instead
Static getGet a value of an array, given an index.
Same as arr[index], but more robust.
the array to search
the index of the returned value
the value in arr found at index
if the given index is NaN
if the index is out of bounds (or if the returned value is undefined)
Static isTest whether two arrays have “the same” elements.
Note: Use this method only if providing a predicate.
If testing for “same-value-zero” equality (the default predicate), use
Node.js’s built-in assert.deepStrictEqual() instead.
Shortcut of xjs_Object.is, but for arrays. Warning: passing in sparse arrays can yield unexpected results.
Are corresponding elements the same, i.e. replaceable?
T - the type of elements in a and b
Static isxjs_Array.isSubarrayOf, but the elements of a must appear consecutively in b.
Is a a consecutive subarray of b?
T - the type of elements in a
U - the type of elements in b
Static isxjs_Array.isConsecutiveSubarrayOf but with the parameters switched.
exactly xjs_Array.isConsecutiveSubarrayOf(b, a, predicate)
T - the type of elements in a
U - the type of elements in b
Static isReturn whether a is a subarray of b.
If and only if a is a subarray of b, all of the following must be true:
a cannot be larger than ba must appear somewhere in b,
where comparison is determined by the predicate parametera that are in b must appear in the same order in which they appear in aNote that if a is an empty array [], or if a and b are “the same” (as determined by predicate),
this method returns true.
Is a a subarray of b?
T - the type of elements in a
U - the type of elements in b
Static isxjs_Array.isSubarrayOf, but with the parameters switched.
exactly xjs_Array.isSubarrayOf(b, a, predicate)
T - the type of elements in a
U - the type of elements in b
Static mapMap an array using a callback, aggregating any errors caught.
Instead of throwing on the first error and stopping iteration, as Array#map would do, this method continues performing the callback on the rest of the array until all items are done. If only one error was caught, then that error is simply rethrown. However, if more errors were caught, they are collected into a single AggregateError, which is then thrown. If no errors are caught, this method returns the usual map.
the array of mapped items
xjs.Array.mapAggregated<number>([1, 2, 3, 4], (n) => {
if (n % 2 === 1) {
throw new Error(`${ n } is odd.`);
} else {
return n / 2;
};
});
// Expected thrown error:
AggregateError {
errors: [
Error { message: "1 is odd." },
Error { message: "3 is odd." },
]
}
xjs.Array.mapAggregated<number>([2, 4, 6], (n) => {
if (n % 2 === 1) {
throw new Error(`${ n } is odd.`);
} else {
return n / 2;
};
});
// Expected return value:
[1, 2, 3]
T the type of items in the array
U the type of items returned by the mapping callback
if two or more iterations throws an error
if one iteration throws an error
Static peekStatic removeMake a copy of an array, and then remove duplicate entries.
"Duplicate entries" are entries that considered "the same" by the provided predicate, or if none is given, xjs_Object.sameValueZero. Only duplicate entries are removed; the order of non-duplicates is preserved.
an array to use
Optional predicate: ((x, y) => boolean)check the “sameness” of elements in the array
a new array, with duplicates removed
T - the type of elements in arr
use [...new Set(arr)] instead
Additional static members for the native Array class.
Does not extend the native Array class.