From: Lady Date: Sun, 25 Jun 2023 05:25:22 +0000 (-0700) Subject: Apply various minor formatting changes X-Git-Tag: 0.4.0~5 X-Git-Url: https://git.ladys.computer/Pisces/commitdiff_plain/58d78d7c0602b17a9599e28232cc8a2ff1d8fc65 Apply various minor formatting changes --- diff --git a/collection.js b/collection.js index 7319b73..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,7 +32,7 @@ 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. * @@ -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 = ($) => { @@ -214,7 +220,7 @@ export const isArraylikeObject = ($) => { * - 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 $)) { @@ -264,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. @@ -280,49 +286,57 @@ 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 @@ -355,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); diff --git a/function.js b/function.js index 72b3b0d..5f397a9 100644 --- a/function.js +++ b/function.js @@ -14,8 +14,8 @@ export const { * 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, @@ -24,7 +24,7 @@ export const { * 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, } = (() => { @@ -75,23 +75,25 @@ 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 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. @@ -112,13 +114,17 @@ export const isCallable = ($) => typeof $ === "function"; 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; } }; diff --git a/numeric.js b/numeric.js index 02ca876..5a3d6ea 100644 --- a/numeric.js +++ b/numeric.js @@ -21,49 +21,49 @@ export const { /** * 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. */ @@ -72,7 +72,7 @@ export const { /** * 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. */ @@ -81,7 +81,7 @@ export const { /** * 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. */ @@ -90,7 +90,7 @@ export const { /** * 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. */ @@ -99,7 +99,7 @@ export const { /** * 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. */ @@ -108,7 +108,7 @@ export const { /** * 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. */ @@ -117,7 +117,7 @@ export const { /** * 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. */ @@ -126,7 +126,7 @@ export const { /** * 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. */ @@ -135,7 +135,7 @@ export const { /** * 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. */ @@ -144,7 +144,7 @@ export const { /** * 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. */ @@ -153,7 +153,7 @@ export const { /** * 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. */ @@ -162,7 +162,7 @@ export const { /** * 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. */ @@ -171,7 +171,7 @@ export const { /** * 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. */ @@ -181,7 +181,7 @@ export const { * 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. */ @@ -190,7 +190,7 @@ export const { /** * 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. */ @@ -199,7 +199,7 @@ export const { /** * 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. */ @@ -208,7 +208,7 @@ export const { /** * 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. */ @@ -217,7 +217,7 @@ export const { /** * 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. */ @@ -226,14 +226,14 @@ export const { /** * 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. */ @@ -242,7 +242,7 @@ export const { /** * 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. */ @@ -251,7 +251,7 @@ export const { /** * 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. */ @@ -260,7 +260,7 @@ export const { /** * 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. */ @@ -269,7 +269,7 @@ export const { /** * 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. */ @@ -278,7 +278,7 @@ export const { /** * 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. */ @@ -287,14 +287,14 @@ export const { /** * 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; @@ -303,84 +303,84 @@ export const { /** * 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; @@ -394,7 +394,7 @@ export const NEGATIVE_ZERO = -0; /** * 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($); @@ -415,17 +415,17 @@ export const { /** * 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, @@ -433,7 +433,7 @@ export const { * 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, @@ -457,7 +457,7 @@ export const { * 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. * @@ -506,7 +506,7 @@ export const max = (...$s) => { * 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. * @@ -558,17 +558,17 @@ export const min = (...$s) => { * 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($); @@ -587,7 +587,7 @@ export const sgn = ($) => { * * ※ 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; @@ -724,7 +724,7 @@ export const toIntegralNumberOrInfinity = ($) => { * * ※ 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 } = (() => { @@ -749,7 +749,7 @@ export const { * 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. @@ -760,7 +760,7 @@ export const { * 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. diff --git a/object.js b/object.js index 71b81db..7b1ef7c 100644 --- a/object.js +++ b/object.js @@ -28,12 +28,12 @@ import { ITERATOR, SPECIES, toPrimitive, type } from "./value.js"; * 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. */ @@ -96,7 +96,7 @@ export const { PropertyDescriptor } = (() => { * 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) { @@ -395,7 +395,7 @@ export const { * 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, @@ -419,7 +419,7 @@ export const { * 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, @@ -428,7 +428,7 @@ export const { * 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, @@ -437,7 +437,7 @@ export const { * 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, @@ -445,7 +445,7 @@ export const { * 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, @@ -455,7 +455,7 @@ export const { * * ☡ This includes both enumerable and non·enumerable properties. * - * ※ This is an alias for Object.getOwnPropertyNames. + * ※ This is an alias for `Object.getOwnPropertyNames`. */ getOwnPropertyNames: getOwnPropertyStrings, @@ -465,14 +465,14 @@ export const { * * ☡ 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, @@ -480,28 +480,28 @@ export const { * 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, @@ -509,7 +509,7 @@ export const { * 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, @@ -517,7 +517,7 @@ export const { * 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, @@ -525,7 +525,7 @@ export const { * 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, @@ -533,14 +533,14 @@ export const { * 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, @@ -548,7 +548,7 @@ export const { * 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, @@ -556,7 +556,7 @@ export const { * 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, @@ -564,7 +564,7 @@ export const { * 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, @@ -572,7 +572,7 @@ export const { * 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; @@ -582,7 +582,7 @@ export const { * 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. * @@ -593,7 +593,7 @@ export const { /** * 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, @@ -602,7 +602,7 @@ export const { * 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, @@ -611,7 +611,7 @@ export const { * 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. @@ -622,8 +622,8 @@ export const { * 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. */ @@ -677,12 +677,12 @@ export const { * 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. */ @@ -709,7 +709,7 @@ export const { // 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( diff --git a/string.js b/string.js index 219fe48..e697a1f 100644 --- a/string.js +++ b/string.js @@ -17,22 +17,27 @@ import { } 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 = @@ -57,7 +62,7 @@ export const { #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 @@ -71,9 +76,9 @@ export const { * 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 @@ -88,7 +93,7 @@ export const { // 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). @@ -142,13 +147,13 @@ export const { } } - /** 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 @@ -179,47 +184,53 @@ export const { } /** - * 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. */ @@ -264,7 +275,7 @@ export const { const { toLowerCase: stringToLowercase, toUpperCase: stringToUppercase, - } = String.prototype; + } = stringPrototype; return { asciiLowercase: ($) => stringReplaceAll( @@ -310,7 +321,7 @@ export const { */ scalarValueString, } = (() => { - const { [ITERATOR]: arrayIterator } = Array.prototype; + const { [ITERATOR]: arrayIterator } = arrayPrototype; const arrayIteratorPrototype = Object.getPrototypeOf( [][ITERATOR](), ); @@ -318,7 +329,7 @@ export const { const iteratorPrototype = Object.getPrototypeOf( arrayIteratorPrototype, ); - const { [ITERATOR]: stringIterator } = String.prototype; + const { [ITERATOR]: stringIterator } = stringPrototype; const stringIteratorPrototype = Object.getPrototypeOf( ""[ITERATOR](), ); @@ -456,16 +467,16 @@ export const { /** * 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); @@ -477,33 +488,33 @@ export const getCharacter = ($, 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, ); /** @@ -514,7 +525,7 @@ export const getLastSubstringIndex = makeCallable( * 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; @@ -525,21 +536,21 @@ export const { * 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; @@ -570,110 +581,110 @@ export const splitOnCommas = ($) => /** * 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, ); /** @@ -682,7 +693,7 @@ export const stringStartsWith = makeCallable( * ☡ 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 @@ -702,17 +713,14 @@ export const stripAndCollapseASCIIWhitespace = ($) => * 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. diff --git a/value.js b/value.js index 782c857..3f0c6fa 100644 --- a/value.js +++ b/value.js @@ -54,10 +54,10 @@ export const UNDEFINED = undefined; 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. @@ -70,7 +70,7 @@ export const { * * 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. */ @@ -123,7 +123,7 @@ export const { 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.