X-Git-Url: https://git.ladys.computer/Pisces/blobdiff_plain/f1283dfa8f4f1482dac6325fbcb66f8778af1002..83f6aae0d1b8181dc2b0c6ccdba9f2fe2fdba3e6:/collection.js?ds=inline diff --git a/collection.js b/collection.js index 20b6fef..3cfe938 100644 --- a/collection.js +++ b/collection.js @@ -1,7 +1,7 @@ // ♓🌟 Piscēs ∷ collection.js // ==================================================================== // -// Copyright © 2020–2022 Lady [@ Lady’s Computer]. +// Copyright © 2020–2023 Lady [@ Lady’s Computer]. // // This Source Code Form is subject to the terms of the Mozilla Public // License, v. 2.0. If a copy of the MPL was not distributed with this @@ -18,6 +18,8 @@ import { } from "./numeric.js"; import { sameValue, type } from "./value.js"; +const { prototype: arrayPrototype } = Array; + export const { /** Returns an array of the provided values. */ of: array, @@ -30,12 +32,12 @@ export const { } = Array; /** - * Returns -0 if the provided argument is "-0"; returns a number + * Returns −0 if the provided argument is "-0"; returns a number * representing the index if the provided argument is a canonical * numeric index string; otherwise, returns undefined. * * There is no clamping of the numeric index, but note that numbers - * above 2^53 − 1 are not safe nor valid integer indices. + * above 2^53 − 1 are not safe nor valid integer indices. */ export const canonicalNumericIndexString = ($) => { if (typeof $ !== "string") { @@ -49,34 +51,35 @@ export const canonicalNumericIndexString = ($) => { }; /** - * Returns the result of catenating the provided arraylikes, returning - * a new collection according to the algorithm of Array::concat. + * Returns the result of catenating the provided arraylikes into a new + * collection according to the algorithm of `Array::concat`. */ -export const catenate = makeCallable(Array.prototype.concat); +export const catenate = makeCallable(arrayPrototype.concat); /** * Copies the items in the provided object to a new location according - * to the algorithm of Array::copyWithin. + * to the algorithm of `Array::copyWithin`. */ -export const copyWithin = makeCallable(Array.prototype.copyWithin); +export const copyWithin = makeCallable(arrayPrototype.copyWithin); /** - * Fills the provided object with the provided value using the - * algorithm of Array::fill. + * Fills the provided object with the provided value according to the + * algorithm of `Array::fill`. */ -export const fill = makeCallable(Array.prototype.fill); +export const fill = makeCallable(arrayPrototype.fill); /** * Returns the result of filtering the provided object with the - * provided callback, using the algorithm of Array::filter. + * provided callback, according to the algorithm of `Array::filter`. */ -export const filter = makeCallable(Array.prototype.filter); +export const filter = makeCallable(arrayPrototype.filter); /** * Returns the first index in the provided object whose value satisfies - * the provided callback using the algorithm of Array::findIndex. + * the provided callback according to the algorithm of + * `Array::findIndex`. */ -export const findIndex = makeCallable(Array.prototype.findIndex); +export const findIndex = makeCallable(arrayPrototype.findIndex); /** * Returns the first indexed entry in the provided object whose value @@ -106,74 +109,77 @@ export const findIndexedEntry = ( /** * Returns the first indexed value in the provided object which - * satisfies the provided callback, using the algorithm of Array::find. + * satisfies the provided callback, according to the algorithm of + * `Array::find`. */ -export const findItem = makeCallable(Array.prototype.find); +export const findItem = makeCallable(arrayPrototype.find); /** * Returns the result of flatmapping the provided value with the - * provided callback using the algorithm of Array::flatMap. + * provided callback according to the algorithm of `Array::flatMap`. */ -export const flatmap = makeCallable(Array.prototype.flatMap); +export const flatmap = makeCallable(arrayPrototype.flatMap); /** - * Returns the result of flattening the provided object using the - * algorithm of Array::flat. + * Returns the result of flattening the provided object according to + * the algorithm of `Array::flat`. */ -export const flatten = makeCallable(Array.prototype.flat); +export const flatten = makeCallable(arrayPrototype.flat); /** * Returns the first index of the provided object with a value * equivalent to the provided value according to the algorithm of - * Array::indexOf. + * `Array::indexOf`. */ -export const getFirstIndex = makeCallable(Array.prototype.indexOf); +export const getFirstIndex = makeCallable(arrayPrototype.indexOf); /** - * Returns the item on the provided object at the provided index using - * the algorithm of Array::at. + * Returns the item on the provided object at the provided index + * according to the algorithm of `Array::at`. */ -export const getItem = makeCallable(Array.prototype.at); +export const getItem = makeCallable(arrayPrototype.at); /** * Returns the last index of the provided object with a value * equivalent to the provided value according to the algorithm of - * Array::lastIndexOf. + * `Array::lastIndexOf`. */ -export const getLastIndex = makeCallable(Array.prototype.lastIndexOf); +export const getLastIndex = makeCallable(arrayPrototype.lastIndexOf); /** * Returns whether every indexed value in the provided object satisfies - * the provided function, using the algorithm of Array::every. + * the provided function, according to the algorithm of `Array::every`. */ -export const hasEvery = makeCallable(Array.prototype.every); +export const hasEvery = makeCallable(arrayPrototype.every); /** * Returns whether the provided object has an indexed value which - * satisfies the provided function, using the algorithm of Array::some. + * satisfies the provided function, according to the algorithm of + * `Array::some`. */ -export const hasSome = makeCallable(Array.prototype.some); +export const hasSome = makeCallable(arrayPrototype.some); /** * Returns whether the provided object has an indexed value equivalent - * to the provided value according to the algorithm of Array::includes. + * to the provided value according to the algorithm of + * `Array::includes`. * - * > ☡ This algorithm treats missing values as `undefined` rather than - * > skipping them. + * ※ This algorithm treats missing values as `undefined` rather than + * skipping them. */ -export const includes = makeCallable(Array.prototype.includes); +export const includes = makeCallable(arrayPrototype.includes); /** * Returns an iterator over the indexed entries in the provided value - * according to the algorithm of Array::entries. + * according to the algorithm of `Array::entries`. */ -export const indexedEntries = makeCallable(Array.prototype.entries); +export const indexedEntries = makeCallable(arrayPrototype.entries); /** * Returns an iterator over the indices in the provided value according - * to the algorithm of Array::keys. + * to the algorithm of `Array::keys`. */ -export const indices = makeCallable(Array.prototype.keys); +export const indices = makeCallable(arrayPrototype.keys); /** Returns whether the provided value is an array index string. */ export const isArrayIndexString = ($) => { @@ -188,19 +194,33 @@ export const isArrayIndexString = ($) => { } }; +/** Returns whether the provided value is arraylike. */ +export const isArraylikeObject = ($) => { + if (type($) !== "object") { + return false; + } else { + try { + lengthOfArraylike($); // throws if not arraylike + return true; + } catch { + return false; + } + } +}; + /** * Returns whether the provided object is a collection. * * The definition of “collection” used by Piscēs is similar to * Ecmascript’s definition of an arraylike object, but it differs in - * a few ways :— + * a few ways :— * * - It requires the provided value to be a proper object. * * - It requires the `length` property to be an integer index. * * - It requires the object to be concat‐spreadable, meaning it must - * either be an array or have `[Symbol.isConcatSpreadable]` be true. + * either be an array or have `.[Symbol.isConcatSpreadable]` be true. */ export const isCollection = ($) => { if (!(type($) === "object" && "length" in $)) { @@ -250,9 +270,9 @@ export const isIntegerIndexString = ($) => { /** * Returns an iterator over the items in the provided value according - * to the algorithm of Array::values. + * to the algorithm of `Array::values`. */ -export const items = makeCallable(Array.prototype.values); +export const items = makeCallable(arrayPrototype.values); /** * Returns the length of the provided arraylike object. @@ -262,53 +282,61 @@ export const items = makeCallable(Array.prototype.values); * This can produce larger lengths than can actually be stored in * arrays, because no such restrictions exist on arraylike methods. */ -export const lengthOfArrayLike = ({ length }) => toLength(length); +export const lengthOfArraylike = ({ length }) => toLength(length); /** * Returns the result of mapping the provided value with the provided - * callback using the algorithm of Array::map. + * callback according to the algorithm of `Array::map`. */ -export const map = makeCallable(Array.prototype.map); +export const map = makeCallable(arrayPrototype.map); -/** Pops from the provided value using the algorithm of Array::pop. */ -export const pop = makeCallable(Array.prototype.pop); +/** + * Pops from the provided value according to the algorithm of + * `Array::pop`. + */ +export const pop = makeCallable(arrayPrototype.pop); /** - * Pushes onto the provided value using the algorithm of Array::push. + * Pushes onto the provided value according to the algorithm of + * `Array::push`. */ -export const push = makeCallable(Array.prototype.push); +export const push = makeCallable(arrayPrototype.push); /** * Returns the result of reducing the provided value with the provided - * callback, using the algorithm of Array::reduce. + * callback, according to the algorithm of `Array::reduce`. */ -export const reduce = makeCallable(Array.prototype.reduce); +export const reduce = makeCallable(arrayPrototype.reduce); /** - * Reverses the provided value using the algorithm of Array::reverse. + * Reverses the provided value according to the algorithm of + * `Array::reverse`. */ -export const reverse = makeCallable(Array.prototype.reverse); +export const reverse = makeCallable(arrayPrototype.reverse); -/** Shifts the provided value using the algorithm of Array::shift. */ -export const shift = makeCallable(Array.prototype.shift); +/** + * Shifts the provided value according to the algorithm of + * `Array::shift`. + */ +export const shift = makeCallable(arrayPrototype.shift); /** - * Returns a slice of the provided value using the algorithm of - * Array::slice. + * Returns a slice of the provided value according to the algorithm of + * `Array::slice`. */ -export const slice = makeCallable(Array.prototype.slice); +export const slice = makeCallable(arrayPrototype.slice); /** - * Sorts the provided value in‐place using the algorithm of - * Array::sort. + * Sorts the provided value in‐place according to the algorithm of + * `Array::sort`. */ -export const sort = makeCallable(Array.prototype.sort); +export const sort = makeCallable(arrayPrototype.sort); /** - * Splices into and out of the provided value using the algorithm of - * Array::splice. + * Splices into and out of the provided value according to the + * algorithm of `Array::splice`. */ -export const splice = makeCallable(Array.prototype.splice); +export const splice = makeCallable(arrayPrototype.splice); /** * Returns the result of converting the provided value to an array @@ -341,6 +369,7 @@ export const toLength = ($) => { }; /** - * Unshifts the provided value using the algorithm of Array::unshift. + * Unshifts the provided value according to the algorithm of + * `Array::unshift`. */ -export const unshift = makeCallable(Array.prototype.unshift); +export const unshift = makeCallable(arrayPrototype.unshift);