Arrays

The arrays helper is a small grab bag of utilities that Qite uses internally. They are framework-agnostic and safe to use in application code too.

Import this helper with:

import * as arrays from "/assets/vendor/qite/src/helpers/arrays.js";

Errors

arrays defines two error types and also exports them under arrays.errors

• arrays.errors.IndexOutOfBounds
• arrays.errors.BadArguments

You will mainly see BadArguments from helpers that validate inputs (for example swapItems()).

Normalize inputs

wrap(item) makes sure you always have an array:

arrays.wrap("a");        // ["a"]
arrays.wrap(["a", "b"]); // ["a", "b"]

This helper is used by other functions that accept either a single item or an array. You may have noticed a lot of functions in Qite accept are like that, which makes it very pleasant to work with them.

Mutating helpers

These functions modify the array you pass in:

addTo(arr, items) pushes one item or many items into arr

let xs = [1,2];
arrays.addTo(xs, 3);
arrays.addTo(xs, [4, 5]); // xs is now [1, 2, 3, 4, 5]

swapItems(arr, n, m) moves the item at index n to index m(and shifts everything in between). It throws if n >= m. If m is beyond the end of the array, the array is extended with undefined first.

let xs = ["a", "b", "c", "d"];
arrays.swapItems(xs, 1, 3); // xs is now ["a", "c", "d", "b"]

removeFrom()

removeFrom(arr, value, compare_func?) removes matching items in place. By default it uses strict equality ===

let xs = [1, 2, 3, 2];
arrays.removeFrom(xs, 2); // xs is now [1, 3]

When working with objects, strict equality usually does not help because different object references are not equal even if their contents match. In such cases you can provide a custom comparator. The comparator receives:

• i — the current array item
• v — the value you passed as the second argument

An item is removed when compare_func(i, v) returns true. Example:

let users = [
    { id: 1, name: "John" },
    { id: 5, name: "Anna" },
    { id: 7, name: "Megan" }
];

arrays.removeFrom(users, 1, (u,id) => u.id === id);

// users is now:
// [ { id: 5, name: "Anna" }, { id: 7, name: "Megan" } ]

Here we are saying: remove any user whose id matches the provided value.

Set-like helpers

uniq(arr, { remove_null=false }={}) returns a new array of unique values. If remove_null is true, it filters out null and undefined first.

arrays.uniq([1, 1, 2]); // => [1, 2]
arrays.uniq([null, 1, null, 2], { remove_null:true }); // => [1, 2]

intersection(arr1, arr2) returns values from arr1 that also exist in arr2

arrays.intersection(["a", "b"], ["b", "c"]); // => ["b"]

There's also haveIntersection(arr1, arr2) is a convenience boolean version.

Subtracting

subtractFrom(arr1, arr2, test_function?) returns a new array containing items from arr1 that are not in arr2

• Without test_function, it uses includes()(simple equality).
• With test_function(i, j), it treats items as matching when the function returns true.

arrays.subtractFrom([1, 2, 3, 4, 5], [2, 4]); // => [1, 3, 5]
arrays.subtractFrom(users, blocked, (u, b) => u.id === b.id);

Deep equality

equal(arr1, arr2, { null_equality=true }={}) compares arrays element-by-element. It also compares nested arrays recursively.

• If null_equality is true, null and undefined are treated as equal.
• If null_equality is false, any null /`undefined` mismatch fails.

arrays.equal([1, [2, 3]], [1, [2, 3]]); // => true
arrays.equal([null], [undefined]); // => true (default)
arrays.equal([null], [undefined], { null_equality: false }); // => false