Lady’s Gitweb - Pisces/blob - value.js

   1 // ♓🌟 Piscēs ∷ value.js
   2 // ====================================================================
   3 //
   4 // Copyright © 2022‐2023 Lady [@ Lady’s Computer].
   5 //
   6 // This Source Code Form is subject to the terms of the Mozilla Public
   7 // License, v. 2.0. If a copy of the MPL was not distributed with this
   8 // file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
   9
  10 export const {
  11   /** The welknown `@@asyncIterator` symbol. */
  12   asyncIterator: ASYNC_ITERATOR,
  13
  14   /** The welknown `@@hasInstance` symbol. */
  15   hasInstance: HAS_INSTANCE,
  16
  17   /** The welknown `@@isConcatSpreadable` symbol. */
  18   isConcatSpreadable: IS_CONCAT_SPREADABLE,
  19
  20   /** The welknown `@@iterator` symbol. */
  21   iterator: ITERATOR,
  22
  23   /** The welknown `@@match` symbol. */
  24   match: MATCH,
  25
  26   /** The welknown `@@matchAll` symbol. */
  27   matchAll: MATCH_ALL,
  28
  29   /** The welknown `@@replace` symbol. */
  30   replace: REPLACE,
  31
  32   /** The welknown `@@species` symbol. */
  33   species: SPECIES,
  34
  35   /** The welknown `@@split` symbol. */
  36   split: SPLIT,
  37
  38   /** The welknown `@@toPrimitive` symbol. */
  39   toPrimitive: TO_PRIMITIVE,
  40
  41   /** The welknown `@@toStringTag` symbol. */
  42   toStringTag: TO_STRING_TAG,
  43
  44   /** The welknown `@@unscopables` symbol. */
  45   unscopables: UNSCOPABLES,
  46 } = Symbol;
  47
  48 export const {
  49   /**
  50    * ln(10).
  51    *
  52    * ※ This is an alias for `Math.LN10`.
  53    */
  54   LN10,
  55
  56   /**
  57    * ln(2).
  58    *
  59    * ※ This is an alias for `Math.LN2`.
  60    */
  61   LN2,
  62
  63   /**
  64    * log10(ℇ).
  65    *
  66    * ※ This is an alias for `Math.LOG10E`.
  67    */
  68   LOG10E: LOG10ℇ,
  69
  70   /**
  71    * log2(ℇ).
  72    *
  73    * ※ This is an alias for `Math.LOG2E`.
  74    */
  75   LOG2E: LOG2ℇ,
  76
  77   /**
  78    * sqrt(½).
  79    *
  80    * ※ This is an alias for `Math.SQRT1_2`.
  81    */
  82   SQRT1_2: RECIPROCAL_SQRT2,
  83
  84   /**
  85    * sqrt(2).
  86    *
  87    * ※ This is an alias for `Math.SQRT2`.
  88    */
  89   SQRT2,
  90
  91   /**
  92    * The mathematical constant π.
  93    *
  94    * ※ This is an alias for `Math.PI`.
  95    */
  96   PI: Π,
  97
  98   /**
  99    * The Euler number.
 100    *
 101    * ※ This is an alias for `Math.E`.
 102    */
 103   E: ℇ,
 104 } = Math;
 105
 106 export const {
 107   /**
 108    * The largest number value less than infinity.
 109    *
 110    * ※ This is an alias for `Number.MAX_VALUE`.
 111    */
 112   MAX_VALUE: MAXIMUM_NUMBER,
 113
 114   /**
 115    * 2**53 - 1.
 116    *
 117    * ※ This is an alias for `Number.MAX_SAFE_INTEGER`.
 118    */
 119   MAX_SAFE_INTEGER: MAXIMUM_SAFE_INTEGRAL_NUMBER,
 120
 121   /**
 122    * The smallest number value greater than negative infinity.
 123    *
 124    * ※ This is an alias for `Number.MIN_VALUE`.
 125    */
 126   MIN_VALUE: MINIMUM_NUMBER,
 127
 128   /**
 129    * -(2**53 - 1).
 130    *
 131    * ※ This is an alias for `Number.MIN_SAFE_INTEGER`.
 132    */
 133   MIN_SAFE_INTEGER: MINIMUM_SAFE_INTEGRAL_NUMBER,
 134
 135   /**
 136    * Negative infinity.
 137    *
 138    * ※ This is an alias for `Number.NEGATIVE_INFINITY`.
 139    */
 140   NEGATIVE_INFINITY,
 141
 142   /**
 143    * Nan.
 144    *
 145    * ※ This is an alias for `Number.NaN`.
 146    */
 147   NaN: NAN,
 148
 149   /**
 150    * Positive infinity.
 151    *
 152    * ※ This is an alias for `Number.POSITIVE_INFINITY`.
 153    */
 154   POSITIVE_INFINITY,
 155
 156   /**
 157    * The difference between 1 and the smallest number greater than 1.
 158    *
 159    * ※ This is an alias for `Number.EPSILON`.
 160    */
 161   EPSILON: Ε,
 162 } = Number;
 163
 164 /** Negative zero. */
 165 export const NEGATIVE_ZERO = -0;
 166
 167 /** The null primitive. */
 168 export const NULL = null;
 169
 170 /** Positive zero. */
 171 export const POSITIVE_ZERO = 0;
 172
 173 /** The undefined primitive. */
 174 export const UNDEFINED = undefined;
 175
 176 export const {
 177   /**
 178    * Returns the primitive value of the provided object per its
 179    * `.toString` and `.valueOf` methods.
 180    *
 181    * If the provided hint is "string", then `.toString` takes
 182    * precedence; otherwise, `.valueOf` does.
 183    *
 184    * Throws an error if both of these methods are not callable or do
 185    * not return a primitive.
 186    */
 187   ordinaryToPrimitive,
 188
 189   /**
 190    * Returns the provided value converted to a primitive, or throws if
 191    * no such conversion is possible.
 192    *
 193    * The provided preferred type, if specified, should be "string",
 194    * "number", or "default". If the provided input has a
 195    * `.[Symbol.toPrimitive]` method, this function will throw rather
 196    * than calling that method with a preferred type other than one of
 197    * the above.
 198    */
 199   toPrimitive,
 200 } = (() => {
 201   const { apply: call } = Reflect;
 202
 203   return {
 204     ordinaryToPrimitive: (O, hint) => {
 205       const methodNames = hint == "string"
 206         ? ["toString", "valueOf"]
 207         : ["valueOf", "toString"];
 208       for (let index = 0; index < methodNames.length; ++index) {
 209         const method = O[methodNames[index]];
 210         if (typeof method === "function") {
 211           // Method is callable.
 212           const result = call(method, O, []);
 213           if (type(result) !== "object") {
 214             // Method returns a primitive.
 215             return result;
 216           } else {
 217             // Method returns an object.
 218             continue;
 219           }
 220         } else {
 221           // Method is not callable.
 222           continue;
 223         }
 224       }
 225       throw new TypeError(
 226         "Piscēs: Unable to convert object to primitive",
 227       );
 228     },
 229     toPrimitive: ($, preferredType = "default") => {
 230       const hint = `${preferredType}`;
 231       if (
 232         "default" !== hint && "string" !== hint &&
 233         "number" !== hint
 234       ) {
 235         // An invalid preferred type was specified.
 236         throw new TypeError(
 237           `Piscēs: Invalid preferred type: ${preferredType}.`,
 238         );
 239       } else if (type($) === "object") {
 240         // The provided value is an object.
 241         const exoticToPrim = $[TO_PRIMITIVE] ?? undefined;
 242         if (exoticToPrim !== undefined) {
 243           // The provided value has an exotic primitive conversion
 244           // method.
 245           if (typeof exoticToPrim !== "function") {
 246             // The method is not callable.
 247             throw new TypeError(
 248               "Piscēs: `.[Symbol.toPrimitive]` was neither nullish nor callable.",
 249             );
 250           } else {
 251             // The method is callable.
 252             return call(exoticToPrim, $, [hint]);
 253           }
 254         } else {
 255           // Use the ordinary primitive conversion function.
 256           return ordinaryToPrimitive($, hint);
 257         }
 258       } else {
 259         // The provided value is already a primitive.
 260         return $;
 261       }
 262     },
 263   };
 264 })();
 265
 266 export const {
 267   /**
 268    * Returns whether the provided values are the same value.
 269    *
 270    * ※ This differs from `===` in the cases of nan and zero.
 271    */
 272   sameValue,
 273
 274   /**
 275    * Returns whether the provided values are either the same value or
 276    * both zero (either positive or negative).
 277    *
 278    * ※ This differs from `===` in the case of nan.
 279    */
 280   sameValueZero,
 281
 282   /**
 283    * Returns the result of converting the provided value to an index,
 284    * or throws an error if it is out of range.
 285    */
 286   toIndex,
 287
 288   /**
 289    * Returns the result of converting the provided value to a length.
 290    */
 291   toLength,
 292 } = (() => {
 293   const { floor, max, min } = Math;
 294   const { isNaN: isNan } = Number;
 295   const { is } = Object;
 296   return {
 297     sameValue: (a, b) => is(a, b),
 298     sameValueZero: ($1, $2) => {
 299       const type1 = type($1);
 300       const type2 = type($2);
 301       if (type1 !== type2) {
 302         // The provided values are not of the same type.
 303         return false;
 304       } else if (type1 === "number") {
 305         // The provided values are numbers; check if they are nan and
 306         // use strict equality otherwise.
 307         return isNan($1) && isNan($2) || $1 === $2;
 308       } else {
 309         // The provided values are not numbers; use strict equality.
 310         return $1 === $2;
 311       }
 312     },
 313     toIndex: ($) => {
 314       const integer = floor($);
 315       if (isNan(integer) || integer == 0) {
 316         // The value is zero·like.
 317         return 0;
 318       } else {
 319         // The value is not zero·like.
 320         const clamped = toLength(integer);
 321         if (clamped !== integer) {
 322           // Clamping the value changes it.
 323           throw new RangeError(`Piscēs: Index out of range: ${$}.`);
 324         } else {
 325           // The value is within appropriate bounds.
 326           return integer;
 327         }
 328       }
 329     },
 330     toLength: ($) => {
 331       const len = floor($);
 332       return isNan(len) || len == 0
 333         ? 0
 334         : max(min(len, MAXIMUM_SAFE_INTEGRAL_NUMBER), 0);
 335     },
 336   };
 337 })();
 338
 339 /**
 340  * Returns a lowercase string identifying the type of the provided
 341  * value.
 342  *
 343  * This differs from the value of the `typeof` operator only in the
 344  * cases of objects and null.
 345  */
 346 export const type = ($) => {
 347   if ($ === null) {
 348     // The provided value is null.
 349     return "null";
 350   } else {
 351     // The provided value is not null.
 352     const type·of = typeof $;
 353     return type·of === "function" ? "object" : type·of;
 354   }
 355 };