// ♓🌟 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
} from "./numeric.js";
import { sameValue, type } from "./value.js";
+const { prototype: arrayPrototype } = Array;
+
export const {
/** Returns an array of the provided values. */
of: array,
} = 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.
*
};
/**
- * 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
/**
* 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 = ($) => {
* - 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 $)) {
/**
* 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.
/**
* 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
};
/**
- * 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);
* Creates a bound function from the provided function using the
* provided this value and arguments list.
*
- * ☡ As with call and construct, the arguments must be passed as an
- * array.
+ * ☡ As with `call` and `construct`, the arguments must be passed as
+ * an array.
*/
bind,
* first argument as the `this` value and the remaining arguments
* passed through.
*
- * ※ This is effectively an alias for Function.prototype.call.bind.
+ * ※ This is effectively an alias for `Function::call.bind`.
*/
makeCallable,
} = (() => {
};
})();
-/**
- * Calls the provided function with the provided this value and
- * arguments list.
- *
- * ☡ This is an alias for Reflect.apply—the arguments must be passed
- * as an array.
- */
-export const call = Reflect.apply;
+export const {
+ /**
+ * Calls the provided function with the provided this value and
+ * arguments list.
+ *
+ * ☡ This is an alias for `Reflect.apply`—the arguments must be
+ * passed as an arraylike.
+ */
+ apply: call,
-/**
- * Constructs the provided function with the provided arguments list
- * and new target.
- *
- * ☡ This is an alias for Reflect.construct—the arguments must be
- * passed as an array.
- */
-export const construct = Reflect.construct;
+ /**
+ * Constructs the provided function with the provided arguments list
+ * and new target.
+ *
+ * ☡ This is an alias for `Reflect.construct`—the arguments must be
+ * passed as an arraylike.
+ */
+ construct,
+} = Reflect;
/**
* Returns the provided value.
export const isConstructor = ($) => {
// The provided value is an object.
try {
+ // Try constructing a new object with the provided value as its
+ // `new.target`. This will throw if the provided value is not a
+ // constructor.
construct(
function () {},
[],
$,
- ); // will throw if $ is not a constructor
+ );
return true;
} catch {
+ // The provided value was not a constructor.
return false;
}
};
/**
* ln(10).
*
- * ※ This is an alias for Math.LN10.
+ * ※ This is an alias for `Math.LN10`.
*/
LN10,
/**
* ln(2).
*
- * ※ This is an alias for Math.LN2.
+ * ※ This is an alias for `Math.LN2`.
*/
LN2,
/**
* log10(ℇ).
*
- * ※ This is an alias for Math.LOG10E.
+ * ※ This is an alias for `Math.LOG10E`.
*/
LOG10E: LOG10ℇ,
/**
* log2(ℇ).
*
- * ※ This is an alias for Math.LOG2E.
+ * ※ This is an alias for `Math.LOG2E`.
*/
LOG2E: LOG2ℇ,
/**
- * sqrt(.5).
+ * sqrt(½).
*
- * ※ This is an alias for Math.SQRT1_2.
+ * ※ This is an alias for `Math.SQRT1_2`.
*/
SQRT1_2: RECIPROCAL_SQRT2,
/**
* sqrt(2).
*
- * ※ This is an alias for Math.SQRT2.
+ * ※ This is an alias for `Math.SQRT2`.
*/
SQRT2,
/**
* Returns the arccos of the provided value.
*
- * ※ This is an alias for Math.acos.
+ * ※ This is an alias for `Math.acos`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the arccosh of the provided value.
*
- * ※ This is an alias for Math.acosh.
+ * ※ This is an alias for `Math.acosh`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the arcsin of the provided value.
*
- * ※ This is an alias for Math.asin.
+ * ※ This is an alias for `Math.asin`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the arcsinh of the provided value.
*
- * ※ This is an alias for Math.asinh.
+ * ※ This is an alias for `Math.asinh`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the arctan of the provided value.
*
- * ※ This is an alias for Math.atan.
+ * ※ This is an alias for `Math.atan`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the arctanh of the provided value.
*
- * ※ This is an alias for Math.atanh.
+ * ※ This is an alias for `Math.atanh`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the cube root of the provided value.
*
- * ※ This is an alias for Math.cbrt.
+ * ※ This is an alias for `Math.cbrt`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the ceiling of the provided value.
*
- * ※ This is an alias for Math.ceil.
+ * ※ This is an alias for `Math.ceil`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the cos of the provided value.
*
- * ※ This is an alias for Math.cos.
+ * ※ This is an alias for `Math.cos`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the cosh of the provided value.
*
- * ※ This is an alias for Math.cosh.
+ * ※ This is an alias for `Math.cosh`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the Euler number raised to the provided value.
*
- * ※ This is an alias for Math.exp.
+ * ※ This is an alias for `Math.exp`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the Euler number raised to the provided value, minus one.
*
- * ※ This is an alias for Math.expm1.
+ * ※ This is an alias for `Math.expm1`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the floor of the provided value.
*
- * ※ This is an alias for Math.floor.
+ * ※ This is an alias for `Math.floor`.
*
* ☡ This function does not allow big·int arguments.
*/
* Returns the square root of the sum of the squares of the provided
* arguments.
*
- * ※ This is an alias for Math.hypot.
+ * ※ This is an alias for `Math.hypot`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the ln of the provided value.
*
- * ※ This is an alias for Math.log.
+ * ※ This is an alias for `Math.log`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the log10 of the provided value.
*
- * ※ This is an alias for Math.log10.
+ * ※ This is an alias for `Math.log10`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the ln of one plus the provided value.
*
- * ※ This is an alias for Math.log1p.
+ * ※ This is an alias for `Math.log1p`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the log2 of the provided value.
*
- * ※ This is an alias for Math.log2.
+ * ※ This is an alias for `Math.log2`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns a pseudo·random value in the range [0, 1).
*
- * ※ This is an alias for Math.random.
+ * ※ This is an alias for `Math.random`.
*/
random: rand,
/**
* Returns the round of the provided value.
*
- * ※ This is an alias for Math.round.
+ * ※ This is an alias for `Math.round`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the sinh of the provided value.
*
- * ※ This is an alias for Math.sinh.
+ * ※ This is an alias for `Math.sinh`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the square root of the provided value.
*
- * ※ This is an alias for Math.sqrt.
+ * ※ This is an alias for `Math.sqrt`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the tan of the provided value.
*
- * ※ This is an alias for Math.tan.
+ * ※ This is an alias for `Math.tan`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the tanh of the provided value.
*
- * ※ This is an alias for Math.tanh.
+ * ※ This is an alias for `Math.tanh`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* Returns the trunc of the provided value.
*
- * ※ This is an alias for Math.trunc.
+ * ※ This is an alias for `Math.trunc`.
*
* ☡ This function does not allow big·int arguments.
*/
/**
* The mathematical constant π.
*
- * ※ This is an alias for Math.PI.
+ * ※ This is an alias for `Math.PI`.
*/
PI: Π,
/**
* The Euler number.
*
- * ※ This is an alias for Math.E.
+ * ※ This is an alias for `Math.E`.
*/
E: ℇ,
} = Math;
/**
* The largest number value less than infinity.
*
- * ※ This is an alias for Number.MAX_VALUE.
+ * ※ This is an alias for `Number.MAX_VALUE`.
*/
MAX_VALUE: MAXIMUM_NUMBER,
/**
* 2**53 - 1.
*
- * ※ This is an alias for Number.MAX_SAFE_INTEGER.
+ * ※ This is an alias for `Number.MAX_SAFE_INTEGER`.
*/
MAX_SAFE_INTEGER: MAXIMUM_SAFE_INTEGRAL_NUMBER,
/**
* The smallest number value greater than negative infinity.
*
- * ※ This is an alias for Number.MIN_VALUE.
+ * ※ This is an alias for `Number.MIN_VALUE`.
*/
MIN_VALUE: MINIMUM_NUMBER,
/**
* -(2**53 - 1).
*
- * ※ This is an alias for Number.MIN_SAFE_INTEGER.
+ * ※ This is an alias for `Number.MIN_SAFE_INTEGER`.
*/
MIN_SAFE_INTEGER: MINIMUM_SAFE_INTEGRAL_NUMBER,
/**
* Negative infinity.
*
- * ※ This is an alias for Number.NEGATIVE_INFINITY.
+ * ※ This is an alias for `Number.NEGATIVE_INFINITY`.
*/
NEGATIVE_INFINITY,
/**
* Nan.
*
- * ※ This is an alias for Number.NaN.
+ * ※ This is an alias for `Number.NaN`.
*/
NaN: NAN,
/**
* Positive infinity.
*
- * ※ This is an alias for Number.POSITIVE_INFINITY.
+ * ※ This is an alias for `Number.POSITIVE_INFINITY`.
*/
POSITIVE_INFINITY,
/**
* The difference between 1 and the smallest number greater than 1.
*
- * ※ This is an alias for Number.EPSILON.
+ * ※ This is an alias for `Number.EPSILON`.
*/
EPSILON: Ε,
/**
* Returns whether the provided value is a finite number.
*
- * ※ This is an alias for Number.isFinite.
+ * ※ This is an alias for `Number.isFinite`.
*/
isFinite: isFiniteNumber,
/**
* Returns whether the provided value is an integral number.
*
- * ※ This is an alias for Number.isInteger.
+ * ※ This is an alias for `Number.isInteger`.
*/
isInteger: isIntegralNumber,
/**
* Returns whether the provided value is nan.
*
- * ※ This is an alias for Number.isNaN.
+ * ※ This is an alias for `Number.isNaN`.
*/
isNaN: isNan,
/**
* Returns whether the provided value is a safe integral number.
*
- * ※ This is an alias for Number.isSafeInteger.
+ * ※ This is an alias for `Number.isSafeInteger`.
*/
isSafeInteger: isSafeIntegralNumber,
} = Number;
/**
* Returns the magnitude (absolute value) of the provided value.
*
- * ※ Unlike Math.abs, this function can take big·int arguments.
+ * ※ Unlike `Math.abs`, this function can take big·int arguments.
*/
export const abs = ($) => {
const n = toNumeric($);
/**
* Returns the arctangent of the dividend of the provided values.
*
- * ※ Unlike Math.atan2, this function can take big·int arguments.
+ * ※ Unlike `Math.atan2`, this function can take big·int arguments.
* However, the result will always be a number.
*/
atan2,
/**
- * Returns the number of leading zeroes in the 32‐bit representation of
- * the provided value.
+ * Returns the number of leading zeroes in the 32‐bit representation
+ * of the provided value.
*
- * ※ Unlike Math.clz32, this function accepts either number or big·int
- * values.
+ * ※ Unlike `Math.clz32`, this function accepts either number or
+ * big·int values.
*/
clz32,
* Returns the 32‐bit float which best approximate the provided
* value.
*
- * ※ Unlike Math.fround, this function can take big·int arguments.
+ * ※ Unlike `Math.fround`, this function can take big·int arguments.
* However, the result will always be a number.
*/
toFloat32,
* Returns the highest value of the provided arguments, or negative
* infinity if no argument is provided.
*
- * ※ Unlike Math.max, this function accepts either number or big·int
+ * ※ Unlike `Math.max`, this function accepts either number or big·int
* values. All values must be of the same type, or this function will
* throw an error.
*
* Returns the lowest value of the provided arguments, or positive
* infinity if no argument is provided.
*
- * ※ Unlike Math.min, this function accepts either number or big·int
+ * ※ Unlike `Math.min`, this function accepts either number or big·int
* values. All values must be of the same type, or this function will
* throw an error.
*
* signed) zero.
*
* For big·ints, the return value of this function is 0n if the
- * provided value is 0n, -1n if the provided value is negative, and +1n
+ * provided value is 0n, −1n if the provided value is negative, and +1n
* otherwise.
*
- * For numbers, the return value is nan, -0, or +0 if the provided
- * value is nan, -0, or +0, respectively, and -1 if the provided value
+ * For numbers, the return value is nan, −0, or +0 if the provided
+ * value is nan, −0, or +0, respectively, and −1 if the provided value
* is negative and +1 if the provided value is positive otherwise. Note
- * that positive and negative infinity will return +1 and -1
+ * that positive and negative infinity will return +1 and −1
* respectively.
*
- * ※ Unlike Math.sign, this function accepts either number or big·int
- * values.
+ * ※ Unlike `Math.sign`, this function accepts either number or
+ * big·int values.
*/
export const sgn = ($) => {
const n = toNumeric($);
*
* ※ This method is safe to use with numbers.
*
- * ※ This is effectively an alias for BigInt.
+ * ※ This is effectively an alias for `BigInt`.
*/
export const { toBigInt } = (() => {
const makeBigInt = BigInt;
*
* ※ This function is safe to use with big·ints.
*
- * ※ This is effectively a nonconstructible version of the Number
+ * ※ This is effectively a nonconstructible version of the `Number`
* constructor.
*/
export const { toNumber } = (() => {
* Returns the result of converting the provided value to fit within
* the provided number of bits as a signed integer.
*
- * ※ Unlike BigInt.asIntN, this function accepts both big·int and
+ * ※ Unlike `BigInt.asIntN`, this function accepts both big·int and
* number values.
*
* ☡ The first argument, the number of bits, must be a number.
* Returns the result of converting the provided value to fit within
* the provided number of bits as an unsigned integer.
*
- * ※ Unlike BigInt.asUintN, this function accepts both big·int and
+ * ※ Unlike `BigInt.asUintN`, this function accepts both big·int and
* number values.
*
* ☡ The first argument, the number of bits, must be a number.
* Methods will be called with the resulting object as their this
* value.
*
- * LazyLoader objects have the same prototype as the passed methods
+ * `LazyLoader` objects have the same prototype as the passed methods
* object.
*/
export class LazyLoader extends null {
/**
- * Constructs a new LazyLoader object.
+ * Constructs a new `LazyLoader` object.
*
* ☡ This function throws if the provided value is not an object.
*/
* object.
*
* The resulting object is proxied to enforce types (for example,
- * its `enumerable` property, if defined, will always be a
+ * its `.enumerable` property, if defined, will always be a
* boolean).
*/
constructor(O) {
* descriptors on the enumerable own properties of the provided
* additional objects.
*
- * ※ This differs from Object.defineProperties in that it can take
+ * ※ This differs from `Object.defineProperties` in that it can take
* multiple source objects.
*/
defineOwnProperties,
* Defines an own property on the provided object on the provided
* property key using the provided property descriptor.
*
- * ※ This is an alias for Object.defineProperty.
+ * ※ This is an alias for `Object.defineProperty`.
*/
defineProperty: defineOwnProperty,
* properties as nonconfigurable and (if data properties)
* nonwritable, and returns the object.
*
- * ※ This is an alias for Object.freeze.
+ * ※ This is an alias for `Object.freeze`.
*/
freeze,
* provided property key on the provided object, or null if none
* exists.
*
- * ※ This is an alias for Object.getOwnPropertyDescriptor.
+ * ※ This is an alias for `Object.getOwnPropertyDescriptor`.
*/
getOwnPropertyDescriptor,
* Returns the property descriptors for the own properties on the
* provided object.
*
- * ※ This is an alias for Object.getOwnPropertyDescriptors.
+ * ※ This is an alias for `Object.getOwnPropertyDescriptors`.
*/
getOwnPropertyDescriptors,
*
* ☡ This includes both enumerable and non·enumerable properties.
*
- * ※ This is an alias for Object.getOwnPropertyNames.
+ * ※ This is an alias for `Object.getOwnPropertyNames`.
*/
getOwnPropertyNames: getOwnPropertyStrings,
*
* ☡ This includes both enumerable and non·enumerable properties.
*
- * ※ This is an alias for Object.getOwnPropertySymbols.
+ * ※ This is an alias for `Object.getOwnPropertySymbols`.
*/
getOwnPropertySymbols,
/**
* Returns the prototype of the provided object.
*
- * ※ This is an alias for Object.getPrototypeOf.
+ * ※ This is an alias for `Object.getPrototypeOf`.
*/
getPrototypeOf: getPrototype,
* Returns whether the provided object has an own property with the
* provided property key.
*
- * ※ This is an alias for Object.hasOwn.
+ * ※ This is an alias for `Object.hasOwn`.
*/
hasOwn: hasOwnProperty,
/**
* Returns whether the provided object is extensible.
*
- * ※ This is an alias for Object.isExtensible.
+ * ※ This is an alias for `Object.isExtensible`.
*/
isExtensible,
/**
* Returns whether the provided object is frozen.
*
- * ※ This is an alias for Object.isFrozen.
+ * ※ This is an alias for `Object.isFrozen`.
*/
isFrozen,
/**
* Returns whether the provided object is sealed.
*
- * ※ This is an alias for Object.isSealed.
+ * ※ This is an alias for `Object.isSealed`.
*/
isSealed,
* Returns an array of key~value pairs for the enumerable,
* string‐valued property keys on the provided object.
*
- * ※ This is an alias for Object.entries.
+ * ※ This is an alias for `Object.entries`.
*/
entries: namedEntries,
* Returns an array of the enumerable, string‐valued property keys on
* the provided object.
*
- * ※ This is an alias for Object.keys.
+ * ※ This is an alias for `Object.keys`.
*/
keys: namedKeys,
* Returns an array of property values for the enumerable,
* string‐valued property keys on the provided object.
*
- * ※ This is an alias for Object.values.
+ * ※ This is an alias for `Object.values`.
*/
values: namedValues,
* Returns a new object with the provided prototype and property
* descriptors.
*
- * ※ This is an alias for Object.create.
+ * ※ This is an alias for `Object.create`.
*/
create: objectCreate,
/**
* Returns a new object with the provided property keys and values.
*
- * ※ This is an alias for Object.fromEntries.
+ * ※ This is an alias for `Object.fromEntries`.
*/
fromEntries: objectFromEntries,
* Marks the provided object as non·extensible, and returns the
* object.
*
- * ※ This is an alias for Object.preventExtensions.
+ * ※ This is an alias for `Object.preventExtensions`.
*/
preventExtensions,
* Marks the provided object as non·extensible and marks all its
* properties as nonconfigurable, and returns the object.
*
- * ※ This is an alias for Object.seal.
+ * ※ This is an alias for `Object.seal`.
*/
seal,
* Sets the values of the enumerable own properties of the provided
* additional objects on the provided object.
*
- * ※ This is an alias for Object.assign.
+ * ※ This is an alias for `Object.assign`.
*/
assign: setPropertyValues,
* Sets the prototype of the provided object to the provided value
* and returns the object.
*
- * ※ This is an alias for Object.setPrototypeOf.
+ * ※ This is an alias for `Object.setPrototypeOf`.
*/
setPrototypeOf: setPrototype,
} = Object;
* Removes the provided property key from the provided object and
* returns the object.
*
- * ※ This function differs from Reflect.deleteProperty and the
+ * ※ This function differs from `Reflect.deleteProperty` and the
* `delete` operator in that it throws if the deletion is
* unsuccessful.
*
/**
* Returns an array of property keys on the provided object.
*
- * ※ This is effectively an alias for Reflect.ownKeys, except that
+ * ※ This is effectively an alias for `Reflect.ownKeys`, except that
* it does not require that the argument be an object.
*/
getOwnPropertyKeys,
* Returns the value of the provided property key on the provided
* object.
*
- * ※ This is effectively an alias for Reflect.get, except that it
+ * ※ This is effectively an alias for `Reflect.get`, except that it
* does not require that the argument be an object.
*/
getPropertyValue,
* Returns whether the provided property key exists on the provided
* object.
*
- * ※ This is effectively an alias for Reflect.has, except that it
+ * ※ This is effectively an alias for `Reflect.has`, except that it
* does not require that the argument be an object.
*
* ※ This includes properties present on the prototype chain.
* Sets the provided property key to the provided value on the
* provided object and returns the object.
*
- * ※ This function differs from Reflect.set in that it throws if the
- * setting is unsuccessful.
+ * ※ This function differs from `Reflect.set` in that it throws if
+ * the setting is unsuccessful.
*
* ☡ This function throws if the first argument is not an object.
*/
* property with the same getter *and* setter.
*
* The prototype for the resulting object will be taken from the
- * `prototype` property of the provided constructor, or the
- * `prototype` of the `constructor` of the provided object if the
+ * `.prototype` property of the provided constructor, or the
+ * `.prototype` of the `.constructor` of the provided object if the
* provided constructor is undefined. If the used constructor has a
- * nonnullish `Symbol.species`, that will be used instead. If the
+ * nonnullish `.[Symbol.species]`, that will be used instead. If the
* used constructor or species is nullish or does not have a
- * `prototype` property, the prototype is set to null.
+ * `.prototype` property, the prototype is set to null.
*
* ※ The prototype of the provided object itself is ignored.
*/
// O is not null or undefined.
//
// (If not provided, the constructor will be the value of
- // getting the `constructor` property of O.)
+ // getting the `.constructor` property of O.)
const species = constructor?.[SPECIES] ?? constructor;
return preventExtensions(
objectCreate(
} from "./object.js";
import { ITERATOR, TO_STRING_TAG } from "./value.js";
+const RE = RegExp;
+const { prototype: rePrototype } = RE;
+const { prototype: arrayPrototype } = Array;
+const { prototype: stringPrototype } = String;
+
+const { exec: reExec } = rePrototype;
+
export const {
/**
- * A RegExp·like object which only matches entire strings, and may
+ * A `RegExp`like object which only matches entire strings, and may
* have additional constraints specified.
*
* Matchers are callable objects and will return true if they are
* called with a string that they match, and false otherwise.
* Matchers will always return false if called with nonstrings,
- * although other methods like `exec` coerce their arguments and may
- * still return true.
+ * although other methods like `::exec` coerce their arguments and
+ * may still return true.
*/
Matcher,
} = (() => {
- const RE = RegExp;
- const { prototype: rePrototype } = RE;
- const { exec: reExec, toString: reToString } = rePrototype;
+ const { toString: reToString } = rePrototype;
const getDotAll =
Object.getOwnPropertyDescriptor(rePrototype, "dotAll").get;
const getFlags =
#regExp;
/**
- * Constructs a new Matcher from the provided source.
+ * Constructs a new `Matcher` from the provided source.
*
* If the provided source is a regular expression, then it must
* have the unicode flag set. Otherwise, it is interpreted as the
* A callable constraint on acceptable inputs may be provided as a
* third argument. If provided, it will be called with three
* arguments whenever a match appears successful: first, the string
- * being matched, second, the match result, and third, the Matcher
- * object itself. If the return value of this call is falsey, then
- * the match will be considered a failure.
+ * being matched, second, the match result, and third, the
+ * `Matcher` object itself. If the return value of this call is
+ * falsey, then the match will be considered a failure.
*
* ☡ If the provided source regular expression uses nongreedy
* quantifiers, it may not match the whole string even if a match
// The provided value is not a string.
return false;
} else {
- // The provided value is a string. Set the `lastIndex` of
+ // The provided value is a string. Set the `.lastIndex` of
// the regular expression to 0 and see if the first attempt
// at a match matches the whole string and passes the
// provided constraint (if present).
}
}
- /** Gets whether the dotAll flag is present on this Matcher. */
+ /** Gets whether the dot‐all flag is present on this `Matcher`. */
get dotAll() {
return call(getDotAll, this.#regExp, []);
}
/**
- * Executes this Matcher on the provided value and returns the
+ * Executes this `Matcher` on the provided value and returns the
* result if there is a match, or null otherwise.
*
* Matchers only match if they can match the entire value on the
}
/**
- * Gets the flags present on this Matcher.
+ * Gets the flags present on this `Matcher`.
*
- * ※ This needs to be defined because the internal RegExp object
+ * ※ This needs to be defined because the internal `RegExp` object
* may have flags which are not yet recognized by ♓🌟 Piscēs.
*/
get flags() {
return call(getFlags, this.#regExp, []);
}
- /** Gets whether the global flag is present on this Matcher. */
+ /** Gets whether the global flag is present on this `Matcher`. */
get global() {
return call(getGlobal, this.#regExp, []);
}
- /** Gets whether the hasIndices flag is present on this Matcher. */
+ /**
+ * Gets whether the has‐indices flag is present on this `Matcher`.
+ */
get hasIndices() {
return call(getHasIndices, this.#regExp, []);
}
- /** Gets whether the ignoreCase flag is present on this Matcher. */
+ /**
+ * Gets whether the ignore‐case flag is present on this `Matcher`.
+ */
get ignoreCase() {
return call(getIgnoreCase, this.#regExp, []);
}
- /** Gets whether the multiline flag is present on this Matcher. */
+ /**
+ * Gets whether the multiline flag is present on this `Matcher`.
+ */
get multiline() {
return call(getMultiline, this.#regExp, []);
}
- /** Gets the regular expression source for this Matcher. */
+ /** Gets the regular expression source for this `Matcher`. */
get source() {
return call(getSource, this.#regExp, []);
}
- /** Gets whether the sticky flag is present on this Matcher. */
+ /** Gets whether the sticky flag is present on this `Matcher`. */
get sticky() {
return call(getSticky, this.#regExp, []);
}
/**
- * Gets whether the unicode flag is present on this Matcher.
+ * Gets whether the unicode flag is present on this `Matcher`.
*
* ※ This will always be true.
*/
const {
toLowerCase: stringToLowercase,
toUpperCase: stringToUppercase,
- } = String.prototype;
+ } = stringPrototype;
return {
asciiLowercase: ($) =>
stringReplaceAll(
*/
scalarValueString,
} = (() => {
- const { [ITERATOR]: arrayIterator } = Array.prototype;
+ const { [ITERATOR]: arrayIterator } = arrayPrototype;
const arrayIteratorPrototype = Object.getPrototypeOf(
[][ITERATOR](),
);
const iteratorPrototype = Object.getPrototypeOf(
arrayIteratorPrototype,
);
- const { [ITERATOR]: stringIterator } = String.prototype;
+ const { [ITERATOR]: stringIterator } = stringPrototype;
const stringIteratorPrototype = Object.getPrototypeOf(
""[ITERATOR](),
);
/**
* Returns an iterator over the codepoints in the string representation
* of the provided value according to the algorithm of
- * String::[Symbol.iterator].
+ * `String::[Symbol.iterator]`.
*/
export const characters = makeCallable(
- String.prototype[ITERATOR],
+ stringPrototype[ITERATOR],
);
/**
* Returns the character at the provided position in the string
* representation of the provided value according to the algorithm of
- * String::codePointAt.
+ * `String::codePointAt`.
*/
export const getCharacter = ($, pos) => {
const codepoint = getCodepoint($, pos);
/**
* Returns the code unit at the provided position in the string
* representation of the provided value according to the algorithm of
- * String::charAt.
+ * `String::charAt`.
*/
-export const getCodeUnit = makeCallable(String.prototype.charCodeAt);
+export const getCodeUnit = makeCallable(stringPrototype.charCodeAt);
/**
* Returns the codepoint at the provided position in the string
* representation of the provided value according to the algorithm of
- * String::codePointAt.
+ * `String::codePointAt`.
*/
-export const getCodepoint = makeCallable(String.prototype.codePointAt);
+export const getCodepoint = makeCallable(stringPrototype.codePointAt);
/**
* Returns the index of the first occurrence of the search string in
* the string representation of the provided value according to the
- * algorithm of String::indexOf.
+ * algorithm of `String::indexOf`.
*/
export const getFirstSubstringIndex = makeCallable(
- String.prototype.indexOf,
+ stringPrototype.indexOf,
);
/**
* Returns the index of the last occurrence of the search string in the
* string representation of the provided value according to the
- * algorithm of String::lastIndexOf.
+ * algorithm of `String::lastIndexOf`.
*/
export const getLastSubstringIndex = makeCallable(
- String.prototype.lastIndexOf,
+ stringPrototype.lastIndexOf,
);
/**
* If a value is nullish, it will be stringified as the empty string.
*/
export const join = (() => {
- const { join: arrayJoin } = Array.prototype;
+ const { join: arrayJoin } = arrayPrototype;
const join = ($, separator = ",") =>
call(arrayJoin, [...$], [`${separator}`]);
return join;
* Returns a string created from the raw value of the tagged template
* literal.
*
- * ※ This is an alias for String.raw.
+ * ※ This is an alias for `String.raw`.
*/
raw: rawString,
/**
* Returns a string created from the provided code units.
*
- * ※ This is an alias for String.fromCharCode.
+ * ※ This is an alias for `String.fromCharCode`.
*/
fromCharCode: stringFromCodeUnits,
/**
* Returns a string created from the provided codepoints.
*
- * ※ This is an alias for String.fromCodePoint.
+ * ※ This is an alias for `String.fromCodePoint`.
*/
fromCodePoint: stringFromCodepoints,
} = String;
/**
* Returns the result of catenating the string representations of the
* provided values, returning a new string according to the algorithm
- * of String::concat.
+ * of `String::concat`.
*/
-export const stringCatenate = makeCallable(String.prototype.concat);
+export const stringCatenate = makeCallable(stringPrototype.concat);
/**
* Returns whether the string representation of the provided value ends
* with the provided search string according to the algorithm of
- * String::endsWith.
+ * `String::endsWith`.
*/
-export const stringEndsWith = makeCallable(String.prototype.endsWith);
+export const stringEndsWith = makeCallable(stringPrototype.endsWith);
/**
* Returns whether the string representation of the provided value
* contains the provided search string according to the algorithm of
- * String::includes.
+ * `String::includes`.
*/
-export const stringIncludes = makeCallable(String.prototype.includes);
+export const stringIncludes = makeCallable(stringPrototype.includes);
/**
* Returns the result of matching the string representation of the
* provided value with the provided matcher according to the algorithm
- * of String::match.
+ * of `String::match`.
*/
-export const stringMatch = makeCallable(String.prototype.match);
+export const stringMatch = makeCallable(stringPrototype.match);
/**
* Returns the result of matching the string representation of the
* provided value with the provided matcher according to the algorithm
- * of String::matchAll.
+ * of `String::matchAll`.
*/
-export const stringMatchAll = makeCallable(String.prototype.matchAll);
+export const stringMatchAll = makeCallable(stringPrototype.matchAll);
/**
* Returns the normalized form of the string representation of the
- * provided value according to the algorithm of String::matchAll.
+ * provided value according to the algorithm of `String::matchAll`.
*/
export const stringNormalize = makeCallable(
- String.prototype.normalize,
+ stringPrototype.normalize,
);
/**
* Returns the result of padding the end of the string representation
* of the provided value padded until it is the desired length
- * according to the algorithm of String::padEnd.
+ * according to the algorithm of `String::padEnd`.
*/
-export const stringPadEnd = makeCallable(String.prototype.padEnd);
+export const stringPadEnd = makeCallable(stringPrototype.padEnd);
/**
* Returns the result of padding the start of the string representation
* of the provided value padded until it is the desired length
- * according to the algorithm of String::padStart.
+ * according to the algorithm of `String::padStart`.
*/
-export const stringPadStart = makeCallable(String.prototype.padStart);
+export const stringPadStart = makeCallable(stringPrototype.padStart);
/**
* Returns the result of repeating the string representation of the
* provided value the provided number of times according to the
- * algorithm of String::repeat.
+ * algorithm of `String::repeat`.
*/
-export const stringRepeat = makeCallable(String.prototype.repeat);
+export const stringRepeat = makeCallable(stringPrototype.repeat);
/**
* Returns the result of replacing the string representation of the
* provided value with the provided replacement, using the provided
- * matcher and according to the algorithm of String::replace.
+ * matcher and according to the algorithm of `String::replace`.
*/
-export const stringReplace = makeCallable(String.prototype.replace);
+export const stringReplace = makeCallable(stringPrototype.replace);
/**
* Returns the result of replacing the string representation of the
* provided value with the provided replacement, using the provided
- * matcher and according to the algorithm of String::replaceAll.
+ * matcher and according to the algorithm of `String::replaceAll`.
*/
export const stringReplaceAll = makeCallable(
- String.prototype.replaceAll,
+ stringPrototype.replaceAll,
);
/**
* Returns the result of searching the string representation of the
* provided value using the provided matcher and according to the
- * algorithm of String::search.
+ * algorithm of `String::search`.
*/
-export const stringSearch = makeCallable(String.prototype.search);
+export const stringSearch = makeCallable(stringPrototype.search);
/**
* Returns a slice of the string representation of the provided value
- * according to the algorithm of String::slice.
+ * according to the algorithm of `String::slice`.
*/
-export const stringSlice = makeCallable(String.prototype.slice);
+export const stringSlice = makeCallable(stringPrototype.slice);
/**
* Returns the result of splitting of the string representation of the
* provided value on the provided separator according to the algorithm
- * of String::split.
+ * of `String::split`.
*/
-export const stringSplit = makeCallable(String.prototype.split);
+export const stringSplit = makeCallable(stringPrototype.split);
/**
* Returns whether the string representation of the provided value
* starts with the provided search string according to the algorithm of
- * String::startsWith.
+ * `String::startsWith`.
*/
export const stringStartsWith = makeCallable(
- String.prototype.startsWith,
+ stringPrototype.startsWith,
);
/**
* ☡ This function will throw if the provided object does not have a
* `[[StringData]]` internal slot.
*/
-export const stringValue = makeCallable(String.prototype.valueOf);
+export const stringValue = makeCallable(stringPrototype.valueOf);
/**
* Returns the result of stripping leading and trailing A·S·C·I·I
* Returns the result of stripping leading and trailing A·S·C·I·I
* whitespace from the string representation of the provided value.
*/
-export const stripLeadingAndTrailingASCIIWhitespace = (() => {
- const { exec: reExec } = RegExp.prototype;
- return ($) =>
- call(reExec, /^[\n\r\t\f ]*([^]*?)[\n\r\t\f ]*$/u, [$])[1];
-})();
+export const stripLeadingAndTrailingASCIIWhitespace = ($) =>
+ call(reExec, /^[\n\r\t\f ]*([^]*?)[\n\r\t\f ]*$/u, [$])[1];
/**
* Returns a substring of the string representation of the provided
- * value according to the algorithm of String::substring.
+ * value according to the algorithm of `String::substring`.
*/
-export const substring = makeCallable(String.prototype.substring);
+export const substring = makeCallable(stringPrototype.substring);
/**
* Returns the result of converting the provided value to a string.
export const {
/**
* Returns the primitive value of the provided object per its
- * `toString` and `valueOf` methods.
+ * `.toString` and `.valueOf` methods.
*
- * If the provided hint is "string", then `toString` takes
- * precedence; otherwise, `valueOf` does.
+ * If the provided hint is "string", then `.toString` takes
+ * precedence; otherwise, `.valueOf` does.
*
* Throws an error if both of these methods are not callable or do
* not return a primitive.
*
* The provided preferred type, if specified, should be "string",
* "number", or "default". If the provided input has a
- * `[Symbol.toPrimitive]` method, this function will throw rather
+ * `.[Symbol.toPrimitive]` method, this function will throw rather
* than calling that method with a preferred type other than one of
* the above.
*/
if (typeof exoticToPrim !== "function") {
// The method is not callable.
throw new TypeError(
- "Piscēs: `[Symbol.toPrimitive]` was neither nullish nor callable.",
+ "Piscēs: `.[Symbol.toPrimitive]` was neither nullish nor callable.",
);
} else {
// The method is callable.
Lady’s Gitweb / Pisces / commitdiff