@helpers4/number 2.0.2 → 2.0.3

package/README.md

@@ -14,9 +14,14 @@ A set of helpers for working with URLs.
 <!-- AUTOMATIC-METHODS -->
 - clamp
 - correctFloat
+- extractNumber
 - formatCompact
 - formatSize
 - inRange
+- isEven
+- isNegative
+- isOdd
+- isPositive
 - lerp
 - mean
 - random

package/lib/index.d.ts

@@ -37,6 +37,61 @@ declare function clamp(value: number, min: number, max: number): number;
  */
 declare function correctFloat(value: number, precision?: number): number;
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Options for {@link extractNumber}.
+ */
+interface ExtractNumberOptions {
+    /**
+     * How to interpret a `-` immediately before the matched digits.
+     * - `'auto'`: treated as a minus sign unless it is glued to a preceding letter/digit
+     *   (e.g. `'-111'` and `'xxx -111'` → negative, but `'xxx-111'` → separator, positive).
+     * - `'strict'`: always treated as a minus sign.
+     * - `'ignore'`: never treated as a minus sign (always a separator).
+     * @default 'auto'
+     */
+    sign?: 'auto' | 'strict' | 'ignore';
+    /**
+     * How to interpret a trailing scientific-notation suffix (`e`/`E` + digits, e.g. `1.5e-10`).
+     * - `'auto'`: treated as an exponent unless it is glued to a following letter/digit
+     *   (e.g. `'1e5'` and `'1e5 mol'` → exponential, but `'1e5kg'` → mantissa only).
+     * - `'strict'`: always treated as an exponent.
+     * - `'ignore'`: never treated as an exponent (mantissa only).
+     * @default 'auto'
+     */
+    exponent?: 'auto' | 'strict' | 'ignore';
+}
+/**
+ * Extracts the first number embedded anywhere in a string, or passes through a `number`.
+ *
+ * Unlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of
+ * the string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)
+ * is ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are
+ * disambiguated with {@link ExtractNumberOptions.sign} and {@link ExtractNumberOptions.exponent}.
+ *
+ * Returns `undefined` if no number can be found.
+ *
+ * @param value - The value to extract a number from
+ * @param options - Options controlling sign and exponent disambiguation
+ * @returns The extracted number, or `undefined` if none was found
+ * @example
+ * extractNumber('16.5px')        // => 16.5
+ * extractNumber('Wafer 10')      // => 10
+ * extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)
+ * extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)
+ * extractNumber('-111')          // => -111  ('-' at the start of the string → sign)
+ * extractNumber('1e5 mol')       // => 100000
+ * extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)
+ * extractNumber('no number')     // => undefined
+ * extractNumber(42)              // => 42
+ * @since 2.0.3
+ */
+declare function extractNumber(value: unknown, options?: ExtractNumberOptions): number | undefined;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -119,6 +174,98 @@ interface InRangeOptions {
  */
 declare function inRange(value: number, min: number, max: number, options?: InRangeOptions): boolean;
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Checks if a value is an even integer.
+ *
+ * Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.
+ *
+ * @param value - The value to check
+ * @returns `true` if value is an integer divisible by 2
+ * @example
+ * isEven(2)    // => true
+ * isEven(0)    // => true
+ * isEven(-4)   // => true
+ * isEven(3)    // => false
+ * isEven(1.5)  // => false  (not an integer)
+ * isEven('2')  // => false
+ * @since 2.0.3
+ */
+declare function isEven(value: unknown): value is number;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Checks if a value is a number less than 0.
+ *
+ * Returns `false` for `NaN`, `0`, positive numbers, and non-number types.
+ *
+ * @param value - The value to check
+ * @returns True if value is a negative number
+ * @example
+ * isNegative(-1)        // => true
+ * isNegative(-0.5)      // => true
+ * isNegative(-Infinity) // => true
+ * isNegative(0)         // => false
+ * isNegative(1)         // => false
+ * isNegative(NaN)       // => false
+ * @since 2.0.0
+ */
+declare function isNegative(value: unknown): value is number;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Checks if a value is an odd integer.
+ *
+ * Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.
+ *
+ * @param value - The value to check
+ * @returns `true` if value is an integer not divisible by 2
+ * @example
+ * isOdd(3)    // => true
+ * isOdd(1)    // => true
+ * isOdd(-7)   // => true
+ * isOdd(2)    // => false
+ * isOdd(1.5)  // => false  (not an integer)
+ * isOdd('3')  // => false
+ * @since 2.0.3
+ */
+declare function isOdd(value: unknown): value is number;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Checks if a value is a number greater than 0.
+ *
+ * Returns `false` for `NaN`, `0`, negative numbers, and non-number types.
+ *
+ * @param value - The value to check
+ * @returns True if value is a positive number
+ * @example
+ * isPositive(42)       // => true
+ * isPositive(0.1)      // => true
+ * isPositive(Infinity) // => true
+ * isPositive(0)        // => false
+ * isPositive(-1)       // => false
+ * isPositive(NaN)      // => false
+ * @since 2.0.0
+ */
+declare function isPositive(value: unknown): value is number;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -217,5 +364,5 @@ declare function roundTo(value: number, decimals: number): number;
  */
 declare function sum(array: readonly number[]): number;
 
-export { clamp, correctFloat, formatCompact, formatSize, inRange, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
-export type { InRangeOptions };
+export { clamp, correctFloat, extractNumber, formatCompact, formatSize, inRange, isEven, isNegative, isOdd, isPositive, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
+export type { ExtractNumberOptions, InRangeOptions };

package/lib/index.js

@@ -46,6 +46,58 @@ function correctFloat(value, precision = 14) {
 	return Object.is(value, -0) && result === 0 ? -0 : result;
 }
 //#endregion
+//#region helpers/number/extractNumber.ts
+var NUMBER_TOKEN = /(-)?(\d+(?:\.\d+)?)([eE][+-]?\d+)?/g;
+function isWordChar(char) {
+	return char !== void 0 && /[\p{L}\p{N}_]/u.test(char);
+}
+/**
+* Extracts the first number embedded anywhere in a string, or passes through a `number`.
+*
+* Unlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of
+* the string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)
+* is ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are
+* disambiguated with {@link ExtractNumberOptions.sign} and {@link ExtractNumberOptions.exponent}.
+*
+* Returns `undefined` if no number can be found.
+*
+* @param value - The value to extract a number from
+* @param options - Options controlling sign and exponent disambiguation
+* @returns The extracted number, or `undefined` if none was found
+* @example
+* extractNumber('16.5px')        // => 16.5
+* extractNumber('Wafer 10')      // => 10
+* extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)
+* extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)
+* extractNumber('-111')          // => -111  ('-' at the start of the string → sign)
+* extractNumber('1e5 mol')       // => 100000
+* extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)
+* extractNumber('no number')     // => undefined
+* extractNumber(42)              // => 42
+* @since 2.0.3
+*/
+function extractNumber(value, options = {}) {
+	const { sign = "auto", exponent = "auto" } = options;
+	if (typeof value === "number") return Number.isNaN(value) ? void 0 : value;
+	if (typeof value !== "string") return;
+	NUMBER_TOKEN.lastIndex = 0;
+	let match;
+	while ((match = NUMBER_TOKEN.exec(value)) !== null) {
+		const [full, signChar, mantissa, exponentPart] = match;
+		const start = match.index;
+		if (signChar) {
+			const before = value[start - 1];
+			if (!(sign === "strict" ? true : sign === "ignore" ? false : !isWordChar(before))) {
+				NUMBER_TOKEN.lastIndex = start + 1;
+				continue;
+			}
+		}
+		const keepExponent = exponentPart ? exponent === "strict" ? true : exponent === "ignore" ? false : !isWordChar(value[start + full.length]) : false;
+		const numericText = (signChar ?? "") + mantissa + (keepExponent ? exponentPart : "");
+		return Number(numericText);
+	}
+}
+//#endregion
 //#region helpers/number/formatCompact.ts
 /**
 * This file is part of helpers4.
@@ -134,6 +186,110 @@ function inRange(value, min, max, options = {}) {
 	return (inclusive === "both" || inclusive === "min" ? value >= min : value > min) && (inclusive === "both" || inclusive === "max" ? value <= max : value < max);
 }
 //#endregion
+//#region helpers/number/isEven.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Checks if a value is an even integer.
+*
+* Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.
+*
+* @param value - The value to check
+* @returns `true` if value is an integer divisible by 2
+* @example
+* isEven(2)    // => true
+* isEven(0)    // => true
+* isEven(-4)   // => true
+* isEven(3)    // => false
+* isEven(1.5)  // => false  (not an integer)
+* isEven('2')  // => false
+* @since 2.0.3
+*/
+function isEven(value) {
+	return typeof value === "number" && Number.isInteger(value) && value % 2 === 0;
+}
+//#endregion
+//#region helpers/number/isNegative.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Checks if a value is a number less than 0.
+*
+* Returns `false` for `NaN`, `0`, positive numbers, and non-number types.
+*
+* @param value - The value to check
+* @returns True if value is a negative number
+* @example
+* isNegative(-1)        // => true
+* isNegative(-0.5)      // => true
+* isNegative(-Infinity) // => true
+* isNegative(0)         // => false
+* isNegative(1)         // => false
+* isNegative(NaN)       // => false
+* @since 2.0.0
+*/
+function isNegative(value) {
+	return typeof value === "number" && value < 0;
+}
+//#endregion
+//#region helpers/number/isOdd.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Checks if a value is an odd integer.
+*
+* Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.
+*
+* @param value - The value to check
+* @returns `true` if value is an integer not divisible by 2
+* @example
+* isOdd(3)    // => true
+* isOdd(1)    // => true
+* isOdd(-7)   // => true
+* isOdd(2)    // => false
+* isOdd(1.5)  // => false  (not an integer)
+* isOdd('3')  // => false
+* @since 2.0.3
+*/
+function isOdd(value) {
+	return typeof value === "number" && Number.isInteger(value) && value % 2 !== 0;
+}
+//#endregion
+//#region helpers/number/isPositive.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Checks if a value is a number greater than 0.
+*
+* Returns `false` for `NaN`, `0`, negative numbers, and non-number types.
+*
+* @param value - The value to check
+* @returns True if value is a positive number
+* @example
+* isPositive(42)       // => true
+* isPositive(0.1)      // => true
+* isPositive(Infinity) // => true
+* isPositive(0)        // => false
+* isPositive(-1)       // => false
+* isPositive(NaN)      // => false
+* @since 2.0.0
+*/
+function isPositive(value) {
+	return typeof value === "number" && value > 0;
+}
+//#endregion
 //#region helpers/number/lerp.ts
 /**
 * This file is part of helpers4.
@@ -254,6 +410,6 @@ function sum(array) {
 	return array.reduce((acc, n) => acc + n, 0);
 }
 //#endregion
-export { clamp, correctFloat, formatCompact, formatSize, inRange, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
+export { clamp, correctFloat, extractNumber, formatCompact, formatSize, inRange, isEven, isNegative, isOdd, isPositive, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
 
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/number/clamp.ts","../../../helpers/number/correctFloat.ts","../../../helpers/number/formatCompact.ts","../../../helpers/number/formatSize.ts","../../../helpers/number/inRange.ts","../../../helpers/number/lerp.ts","../../../helpers/number/mean.ts","../../../helpers/number/random.ts","../../../helpers/number/roundTo.ts","../../../helpers/number/sum.ts"],"sourcesContent":["/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Clamps a number between min and max values\n * @param value - The value to clamp\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Clamped value\n * @since 1.9.0\n */\nexport function clamp(value: number, min: number, max: number): number {\n  return Math.min(Math.max(value, min), max);\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Corrects floating-point arithmetic errors by rounding to a given number\n * of significant digits. Useful after calculations that accumulate binary\n * floating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).\n *\n * The default precision of 14 significant digits eliminates typical\n * rounding noise for values in the range used by most applications.\n * Note: for values whose integer part already consumes 14 or more digits\n * (i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal\n * digits and will silently truncate them. Increase `precision` if you\n * need to correct drift in very large numbers.\n *\n * @param value - The floating-point value to correct\n * @param precision - Integer number of significant digits (default: 14)\n * @returns The corrected value\n * @since 2.0.2\n */\nexport function correctFloat(value: number, precision: number = 14): number {\n  if (!Number.isFinite(value)) {\n    throw new RangeError(`correctFloat: value must be a finite number, got ${value}`);\n  }\n  if (!Number.isInteger(precision) || precision < 1 || precision > 100) {\n    throw new RangeError(`correctFloat: precision must be an integer between 1 and 100, got ${precision}`);\n  }\n  const result = parseFloat(value.toPrecision(precision));\n  // toPrecision(-0) produces \"0.000…\" (no minus sign per spec) — restore the sign bit.\n  return Object.is(value, -0) && result === 0 ? -0 : result;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Formats a number using compact notation (e.g. `1_500_000 → \"1.5M\"`).\n *\n * Thin wrapper over `Intl.NumberFormat` with `notation: 'compact'`. Companion\n * of `formatSize` in the same `format*` family.\n *\n * @param value - The number to format.\n * @param locale - BCP 47 locale tag. Defaults to the runtime locale.\n * @returns A compact string representation of the number.\n * @example\n * formatCompact(1_500_000);        // '1.5M'  (en-US locale)\n * formatCompact(1_000);            // '1K'\n * formatCompact(999);              // '999'\n * formatCompact(1_500_000, 'fr'); // '1,5 M'\n * @since 2.0.0\n */\nexport function formatCompact(value: number, locale?: string): string {\n  return new Intl.NumberFormat(locale, { notation: 'compact' }).format(value);\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/** Size units in ascending order. */\nconst UNITS = ['B', 'KB', 'MB', 'GB', 'TB'] as const;\n\n/**\n * Format a byte count into a human-readable string with the appropriate unit.\n *\n * Each unit is 1024 of the previous (binary prefix). The result is formatted\n * with one decimal place.\n *\n * @param bytes - A non-negative integer representing a byte count.\n * @returns A human-readable string such as `'0.0B'`, `'1.5KB'`, `'3.2MB'`.\n * @example\n * formatSize(0)               // '0.0B'\n * formatSize(512)             // '512.0B'\n * formatSize(1024)            // '1.0KB'\n * formatSize(1536)            // '1.5KB'\n * formatSize(1_048_576)       // '1.0MB'\n * formatSize(1_073_741_824)   // '1.0GB'\n * @since 2.0.0\n */\nexport function formatSize(bytes: number): string {\n  let size = bytes;\n  let unitIndex = 0;\n\n  while (size >= 1024 && unitIndex < UNITS.length - 1) {\n    size /= 1024;\n    unitIndex++;\n  }\n\n  return `${size.toFixed(1)}${UNITS[unitIndex]}`;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Options for {@link inRange}.\n */\nexport interface InRangeOptions {\n  /**\n   * Which boundary (or boundaries) are included in the range.\n   * - `'both'` (default): `min <= value <= max`\n   * - `'min'`: `min <= value < max`\n   * - `'max'`: `min < value <= max`\n   * - `'none'`: `min < value < max`\n   */\n  inclusive?: 'both' | 'min' | 'max' | 'none';\n}\n\n/**\n * Checks whether a number falls within `[min, max]` (both inclusive by default).\n *\n * @param value - The number to test\n * @param min - Lower bound\n * @param max - Upper bound\n * @param options - Boundary inclusion mode (default: `'both'`)\n * @returns `true` if `value` is within the specified range\n * @example\n * inRange(5, 1, 10)          // => true\n * inRange(1, 1, 10)          // => true  (min inclusive)\n * inRange(1, 1, 10, { inclusive: 'none' })  // => false\n * inRange(10, 1, 10, { inclusive: 'max' })  // => true\n * @since 2.0.0\n */\nexport function inRange(value: number, min: number, max: number, options: InRangeOptions = {}): boolean {\n  const { inclusive = 'both' } = options;\n  const minOk = inclusive === 'both' || inclusive === 'min' ? value >= min : value > min;\n  const maxOk = inclusive === 'both' || inclusive === 'max' ? value <= max : value < max;\n  return minOk && maxOk;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Linearly interpolates between `start` and `end` by the factor `t`.\n *\n * - `t = 0` returns `start`.\n * - `t = 1` returns `end`.\n * - Values of `t` outside `[0, 1]` extrapolate beyond the range.\n *\n * @param start - The start value.\n * @param end - The end value.\n * @param t - The interpolation factor.\n * @returns The interpolated value.\n * @example\n * lerp(0, 100, 0);    // 0\n * lerp(0, 100, 1);    // 100\n * lerp(0, 100, 0.5);  // 50\n * lerp(0, 100, 0.25); // 25\n * @since 2.0.0\n */\nexport function lerp(start: number, end: number, t: number): number {\n  if (t === 0) return start;\n  if (t === 1) return end;\n  if (Object.is(start, end)) return start;\n  return start + (end - start) * t;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Calculates the arithmetic mean (average) of an array of numbers.\n * Returns `NaN` for an empty array.\n *\n * Pairs with {@link sum} for aggregate operations.\n *\n * @param array - The array of numbers to average\n * @returns The arithmetic mean, or `NaN` if the array is empty\n * @example\n * mean([1, 2, 3, 4])  // => 2.5\n * mean([10])          // => 10\n * mean([])            // => NaN\n * @since 2.0.0\n */\nexport function mean(array: readonly number[]): number {\n  if (array.length === 0) return NaN;\n  return array.reduce((acc, n) => acc + n, 0) / array.length;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Generates a random number between min and max (inclusive)\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Random number between min and max\n * @since 1.9.0\n */\nexport function randomBetween(min: number, max: number): number {\n  return Math.random() * (max - min) + min;\n}\n\n/**\n * Generates a random integer between min and max (inclusive)\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Random integer between min and max\n * @since 1.9.0\n */\nexport function randomIntBetween(min: number, max: number): number {\n  return Math.floor(Math.random() * (max - min + 1)) + min;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Rounds a number to specified decimal places\n * @param value - The number to round\n * @param decimals - Number of decimal places\n * @returns Rounded number\n * @since 1.9.0\n */\nexport function roundTo(value: number, decimals: number): number {\n  const multiplier = Math.pow(10, decimals);\n  return Math.round(value * multiplier) / multiplier;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Calculates the sum of an array of numbers.\n * @param array - The array of numbers to sum\n * @returns The sum of all values\n * @example\n * sum([1, 2, 3, 4])\n * // => 10\n * @since 2.0.0\n */\nexport function sum(array: readonly number[]): number {\n  return array.reduce((acc, n) => acc + n, 0);\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,SAAgB,MAAM,OAAe,KAAa,KAAqB;CACrE,OAAO,KAAK,IAAI,KAAK,IAAI,OAAO,GAAG,GAAG,GAAG;AAC3C;;;;;;;;;;;;;;;;;;;;;;;;;ACOA,SAAgB,aAAa,OAAe,YAAoB,IAAY;CAC1E,IAAI,CAAC,OAAO,SAAS,KAAK,GACxB,MAAM,IAAI,WAAW,oDAAoD,OAAO;CAElF,IAAI,CAAC,OAAO,UAAU,SAAS,KAAK,YAAY,KAAK,YAAY,KAC/D,MAAM,IAAI,WAAW,qEAAqE,WAAW;CAEvG,MAAM,SAAS,WAAW,MAAM,YAAY,SAAS,CAAC;CAEtD,OAAO,OAAO,GAAG,OAAO,EAAE,KAAK,WAAW,IAAI,KAAK;AACrD;;;;;;;;;;;;;;;;;;;;;;;;ACXA,SAAgB,cAAc,OAAe,QAAyB;CACpE,OAAO,IAAI,KAAK,aAAa,QAAQ,EAAE,UAAU,UAAU,CAAC,EAAE,OAAO,KAAK;AAC5E;;;;;;;;;ACjBA,IAAM,QAAQ;CAAC;CAAK;CAAM;CAAM;CAAM;AAAI;;;;;;;;;;;;;;;;;;AAmB1C,SAAgB,WAAW,OAAuB;CAChD,IAAI,OAAO;CACX,IAAI,YAAY;CAEhB,OAAO,QAAQ,QAAQ,YAAY,MAAM,SAAS,GAAG;EACnD,QAAQ;EACR;CACF;CAEA,OAAO,GAAG,KAAK,QAAQ,CAAC,IAAI,MAAM;AACpC;;;;;;;;;;;;;;;;;;ACDA,SAAgB,QAAQ,OAAe,KAAa,KAAa,UAA0B,CAAC,GAAY;CACtG,MAAM,EAAE,YAAY,WAAW;CAG/B,QAFc,cAAc,UAAU,cAAc,QAAQ,SAAS,MAAM,QAAQ,SACrE,cAAc,UAAU,cAAc,QAAQ,SAAS,MAAM,QAAQ;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;AChBA,SAAgB,KAAK,OAAe,KAAa,GAAmB;CAClE,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,OAAO,GAAG,OAAO,GAAG,GAAG,OAAO;CAClC,OAAO,SAAS,MAAM,SAAS;AACjC;;;;;;;;;;;;;;;;;;;;;;ACTA,SAAgB,KAAK,OAAkC;CACrD,IAAI,MAAM,WAAW,GAAG,OAAO;CAC/B,OAAO,MAAM,QAAQ,KAAK,MAAM,MAAM,GAAG,CAAC,IAAI,MAAM;AACtD;;;;;;;;;;;;;;;ACVA,SAAgB,cAAc,KAAa,KAAqB;CAC9D,OAAO,KAAK,OAAO,KAAK,MAAM,OAAO;AACvC;;;;;;;;AASA,SAAgB,iBAAiB,KAAa,KAAqB;CACjE,OAAO,KAAK,MAAM,KAAK,OAAO,KAAK,MAAM,MAAM,EAAE,IAAI;AACvD;;;;;;;;;;;;;;;ACbA,SAAgB,QAAQ,OAAe,UAA0B;CAC/D,MAAM,aAAa,KAAK,IAAI,IAAI,QAAQ;CACxC,OAAO,KAAK,MAAM,QAAQ,UAAU,IAAI;AAC1C;;;;;;;;;;;;;;;;;ACDA,SAAgB,IAAI,OAAkC;CACpD,OAAO,MAAM,QAAQ,KAAK,MAAM,MAAM,GAAG,CAAC;AAC5C"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/number/clamp.ts","../../../helpers/number/correctFloat.ts","../../../helpers/number/extractNumber.ts","../../../helpers/number/formatCompact.ts","../../../helpers/number/formatSize.ts","../../../helpers/number/inRange.ts","../../../helpers/number/isEven.ts","../../../helpers/number/isNegative.ts","../../../helpers/number/isOdd.ts","../../../helpers/number/isPositive.ts","../../../helpers/number/lerp.ts","../../../helpers/number/mean.ts","../../../helpers/number/random.ts","../../../helpers/number/roundTo.ts","../../../helpers/number/sum.ts"],"sourcesContent":["/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Clamps a number between min and max values\n * @param value - The value to clamp\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Clamped value\n * @since 1.9.0\n */\nexport function clamp(value: number, min: number, max: number): number {\n  return Math.min(Math.max(value, min), max);\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Corrects floating-point arithmetic errors by rounding to a given number\n * of significant digits. Useful after calculations that accumulate binary\n * floating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).\n *\n * The default precision of 14 significant digits eliminates typical\n * rounding noise for values in the range used by most applications.\n * Note: for values whose integer part already consumes 14 or more digits\n * (i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal\n * digits and will silently truncate them. Increase `precision` if you\n * need to correct drift in very large numbers.\n *\n * @param value - The floating-point value to correct\n * @param precision - Integer number of significant digits (default: 14)\n * @returns The corrected value\n * @since 2.0.2\n */\nexport function correctFloat(value: number, precision: number = 14): number {\n  if (!Number.isFinite(value)) {\n    throw new RangeError(`correctFloat: value must be a finite number, got ${value}`);\n  }\n  if (!Number.isInteger(precision) || precision < 1 || precision > 100) {\n    throw new RangeError(`correctFloat: precision must be an integer between 1 and 100, got ${precision}`);\n  }\n  const result = parseFloat(value.toPrecision(precision));\n  // toPrecision(-0) produces \"0.000…\" (no minus sign per spec) — restore the sign bit.\n  return Object.is(value, -0) && result === 0 ? -0 : result;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Options for {@link extractNumber}.\n */\nexport interface ExtractNumberOptions {\n  /**\n   * How to interpret a `-` immediately before the matched digits.\n   * - `'auto'`: treated as a minus sign unless it is glued to a preceding letter/digit\n   *   (e.g. `'-111'` and `'xxx -111'` → negative, but `'xxx-111'` → separator, positive).\n   * - `'strict'`: always treated as a minus sign.\n   * - `'ignore'`: never treated as a minus sign (always a separator).\n   * @default 'auto'\n   */\n  sign?: 'auto' | 'strict' | 'ignore';\n\n  /**\n   * How to interpret a trailing scientific-notation suffix (`e`/`E` + digits, e.g. `1.5e-10`).\n   * - `'auto'`: treated as an exponent unless it is glued to a following letter/digit\n   *   (e.g. `'1e5'` and `'1e5 mol'` → exponential, but `'1e5kg'` → mantissa only).\n   * - `'strict'`: always treated as an exponent.\n   * - `'ignore'`: never treated as an exponent (mantissa only).\n   * @default 'auto'\n   */\n  exponent?: 'auto' | 'strict' | 'ignore';\n}\n\nconst NUMBER_TOKEN = /(-)?(\\d+(?:\\.\\d+)?)([eE][+-]?\\d+)?/g;\n\nfunction isWordChar(char: string | undefined): boolean {\n  return char !== undefined && /[\\p{L}\\p{N}_]/u.test(char);\n}\n\n/**\n * Extracts the first number embedded anywhere in a string, or passes through a `number`.\n *\n * Unlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of\n * the string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)\n * is ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are\n * disambiguated with {@link ExtractNumberOptions.sign} and {@link ExtractNumberOptions.exponent}.\n *\n * Returns `undefined` if no number can be found.\n *\n * @param value - The value to extract a number from\n * @param options - Options controlling sign and exponent disambiguation\n * @returns The extracted number, or `undefined` if none was found\n * @example\n * extractNumber('16.5px')        // => 16.5\n * extractNumber('Wafer 10')      // => 10\n * extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\n * extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\n * extractNumber('-111')          // => -111  ('-' at the start of the string → sign)\n * extractNumber('1e5 mol')       // => 100000\n * extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\n * extractNumber('no number')     // => undefined\n * extractNumber(42)              // => 42\n * @since 2.0.3\n */\nexport function extractNumber(value: unknown, options: ExtractNumberOptions = {}): number | undefined {\n  const { sign = 'auto', exponent = 'auto' } = options;\n\n  if (typeof value === 'number') {\n    return Number.isNaN(value) ? undefined : value;\n  }\n\n  if (typeof value !== 'string') {\n    return undefined;\n  }\n\n  NUMBER_TOKEN.lastIndex = 0;\n  let match: RegExpExecArray | null;\n\n  while ((match = NUMBER_TOKEN.exec(value)) !== null) {\n    const [full, signChar, mantissa, exponentPart] = match;\n    const start = match.index;\n\n    if (signChar) {\n      const before = value[start - 1];\n      const keepSign = sign === 'strict' ? true : sign === 'ignore' ? false : !isWordChar(before);\n\n      if (!keepSign) {\n        // Re-scan from right after the '-' so the digits are matched as a fresh, unsigned number.\n        NUMBER_TOKEN.lastIndex = start + 1;\n        continue;\n      }\n    }\n\n    const keepExponent = exponentPart\n      ? exponent === 'strict'\n        ? true\n        : exponent === 'ignore'\n          ? false\n          : !isWordChar(value[start + full.length])\n      : false;\n\n    const numericText = (signChar ?? '') + mantissa + (keepExponent ? exponentPart : '');\n    return Number(numericText);\n  }\n\n  return undefined;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Formats a number using compact notation (e.g. `1_500_000 → \"1.5M\"`).\n *\n * Thin wrapper over `Intl.NumberFormat` with `notation: 'compact'`. Companion\n * of `formatSize` in the same `format*` family.\n *\n * @param value - The number to format.\n * @param locale - BCP 47 locale tag. Defaults to the runtime locale.\n * @returns A compact string representation of the number.\n * @example\n * formatCompact(1_500_000);        // '1.5M'  (en-US locale)\n * formatCompact(1_000);            // '1K'\n * formatCompact(999);              // '999'\n * formatCompact(1_500_000, 'fr'); // '1,5 M'\n * @since 2.0.0\n */\nexport function formatCompact(value: number, locale?: string): string {\n  return new Intl.NumberFormat(locale, { notation: 'compact' }).format(value);\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/** Size units in ascending order. */\nconst UNITS = ['B', 'KB', 'MB', 'GB', 'TB'] as const;\n\n/**\n * Format a byte count into a human-readable string with the appropriate unit.\n *\n * Each unit is 1024 of the previous (binary prefix). The result is formatted\n * with one decimal place.\n *\n * @param bytes - A non-negative integer representing a byte count.\n * @returns A human-readable string such as `'0.0B'`, `'1.5KB'`, `'3.2MB'`.\n * @example\n * formatSize(0)               // '0.0B'\n * formatSize(512)             // '512.0B'\n * formatSize(1024)            // '1.0KB'\n * formatSize(1536)            // '1.5KB'\n * formatSize(1_048_576)       // '1.0MB'\n * formatSize(1_073_741_824)   // '1.0GB'\n * @since 2.0.0\n */\nexport function formatSize(bytes: number): string {\n  let size = bytes;\n  let unitIndex = 0;\n\n  while (size >= 1024 && unitIndex < UNITS.length - 1) {\n    size /= 1024;\n    unitIndex++;\n  }\n\n  return `${size.toFixed(1)}${UNITS[unitIndex]}`;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Options for {@link inRange}.\n */\nexport interface InRangeOptions {\n  /**\n   * Which boundary (or boundaries) are included in the range.\n   * - `'both'` (default): `min <= value <= max`\n   * - `'min'`: `min <= value < max`\n   * - `'max'`: `min < value <= max`\n   * - `'none'`: `min < value < max`\n   */\n  inclusive?: 'both' | 'min' | 'max' | 'none';\n}\n\n/**\n * Checks whether a number falls within `[min, max]` (both inclusive by default).\n *\n * @param value - The number to test\n * @param min - Lower bound\n * @param max - Upper bound\n * @param options - Boundary inclusion mode (default: `'both'`)\n * @returns `true` if `value` is within the specified range\n * @example\n * inRange(5, 1, 10)          // => true\n * inRange(1, 1, 10)          // => true  (min inclusive)\n * inRange(1, 1, 10, { inclusive: 'none' })  // => false\n * inRange(10, 1, 10, { inclusive: 'max' })  // => true\n * @since 2.0.0\n */\nexport function inRange(value: number, min: number, max: number, options: InRangeOptions = {}): boolean {\n  const { inclusive = 'both' } = options;\n  const minOk = inclusive === 'both' || inclusive === 'min' ? value >= min : value > min;\n  const maxOk = inclusive === 'both' || inclusive === 'max' ? value <= max : value < max;\n  return minOk && maxOk;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if a value is an even integer.\n *\n * Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.\n *\n * @param value - The value to check\n * @returns `true` if value is an integer divisible by 2\n * @example\n * isEven(2)    // => true\n * isEven(0)    // => true\n * isEven(-4)   // => true\n * isEven(3)    // => false\n * isEven(1.5)  // => false  (not an integer)\n * isEven('2')  // => false\n * @since 2.0.3\n */\nexport function isEven(value: unknown): value is number {\n  return typeof value === 'number' && Number.isInteger(value) && value % 2 === 0;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if a value is a number less than 0.\n *\n * Returns `false` for `NaN`, `0`, positive numbers, and non-number types.\n *\n * @param value - The value to check\n * @returns True if value is a negative number\n * @example\n * isNegative(-1)        // => true\n * isNegative(-0.5)      // => true\n * isNegative(-Infinity) // => true\n * isNegative(0)         // => false\n * isNegative(1)         // => false\n * isNegative(NaN)       // => false\n * @since 2.0.0\n */\nexport function isNegative(value: unknown): value is number {\n  return typeof value === 'number' && value < 0;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if a value is an odd integer.\n *\n * Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.\n *\n * @param value - The value to check\n * @returns `true` if value is an integer not divisible by 2\n * @example\n * isOdd(3)    // => true\n * isOdd(1)    // => true\n * isOdd(-7)   // => true\n * isOdd(2)    // => false\n * isOdd(1.5)  // => false  (not an integer)\n * isOdd('3')  // => false\n * @since 2.0.3\n */\nexport function isOdd(value: unknown): value is number {\n  return typeof value === 'number' && Number.isInteger(value) && value % 2 !== 0;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if a value is a number greater than 0.\n *\n * Returns `false` for `NaN`, `0`, negative numbers, and non-number types.\n *\n * @param value - The value to check\n * @returns True if value is a positive number\n * @example\n * isPositive(42)       // => true\n * isPositive(0.1)      // => true\n * isPositive(Infinity) // => true\n * isPositive(0)        // => false\n * isPositive(-1)       // => false\n * isPositive(NaN)      // => false\n * @since 2.0.0\n */\nexport function isPositive(value: unknown): value is number {\n  return typeof value === 'number' && value > 0;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Linearly interpolates between `start` and `end` by the factor `t`.\n *\n * - `t = 0` returns `start`.\n * - `t = 1` returns `end`.\n * - Values of `t` outside `[0, 1]` extrapolate beyond the range.\n *\n * @param start - The start value.\n * @param end - The end value.\n * @param t - The interpolation factor.\n * @returns The interpolated value.\n * @example\n * lerp(0, 100, 0);    // 0\n * lerp(0, 100, 1);    // 100\n * lerp(0, 100, 0.5);  // 50\n * lerp(0, 100, 0.25); // 25\n * @since 2.0.0\n */\nexport function lerp(start: number, end: number, t: number): number {\n  if (t === 0) return start;\n  if (t === 1) return end;\n  if (Object.is(start, end)) return start;\n  return start + (end - start) * t;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Calculates the arithmetic mean (average) of an array of numbers.\n * Returns `NaN` for an empty array.\n *\n * Pairs with {@link sum} for aggregate operations.\n *\n * @param array - The array of numbers to average\n * @returns The arithmetic mean, or `NaN` if the array is empty\n * @example\n * mean([1, 2, 3, 4])  // => 2.5\n * mean([10])          // => 10\n * mean([])            // => NaN\n * @since 2.0.0\n */\nexport function mean(array: readonly number[]): number {\n  if (array.length === 0) return NaN;\n  return array.reduce((acc, n) => acc + n, 0) / array.length;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Generates a random number between min and max (inclusive)\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Random number between min and max\n * @since 1.9.0\n */\nexport function randomBetween(min: number, max: number): number {\n  return Math.random() * (max - min) + min;\n}\n\n/**\n * Generates a random integer between min and max (inclusive)\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Random integer between min and max\n * @since 1.9.0\n */\nexport function randomIntBetween(min: number, max: number): number {\n  return Math.floor(Math.random() * (max - min + 1)) + min;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Rounds a number to specified decimal places\n * @param value - The number to round\n * @param decimals - Number of decimal places\n * @returns Rounded number\n * @since 1.9.0\n */\nexport function roundTo(value: number, decimals: number): number {\n  const multiplier = Math.pow(10, decimals);\n  return Math.round(value * multiplier) / multiplier;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Calculates the sum of an array of numbers.\n * @param array - The array of numbers to sum\n * @returns The sum of all values\n * @example\n * sum([1, 2, 3, 4])\n * // => 10\n * @since 2.0.0\n */\nexport function sum(array: readonly number[]): number {\n  return array.reduce((acc, n) => acc + n, 0);\n}\n"],"mappings":"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"}

package/llms.txt

@@ -1,7 +1,7 @@
 # @helpers4/number
 
 > Tree-shakable TypeScript utility functions for the `number` domain.
-> Package: `@helpers4/number` — Version: 2.0.2
+> Package: `@helpers4/number` — Version: 2.0.3
 > License: LGPL-3.0-or-later
 
 ## Installation
@@ -15,7 +15,7 @@ pnpm add @helpers4/number
 ## Usage
 
 ```typescript
-import { clamp, correctFloat, formatCompact, ... } from '@helpers4/number';
+import { clamp, correctFloat, extractNumber, ... } from '@helpers4/number';
 ```
 
 ## Functions
@@ -24,9 +24,14 @@ import { clamp, correctFloat, formatCompact, ... } from '@helpers4/number';
 |---|---|
 | `clamp` | Clamps a number between min and max values |
 | `correctFloat` | Corrects floating-point arithmetic errors by rounding to a given number of significant digits. Usefu |
+| `extractNumber` | Extracts the first number embedded anywhere in a string, or passes through a `number`.  Unlike a pla |
 | `formatCompact` | Formats a number using compact notation (e.g. `1_500_000 → "1.5M"`).  Thin wrapper over `Intl.Number |
 | `formatSize` | Format a byte count into a human-readable string with the appropriate unit.  Each unit is 1024 of th |
 | `inRange` | Checks whether a number falls within `[min, max]` (both inclusive by default). |
+| `isEven` | Checks if a value is an even integer.  Returns `false` for non-numbers, non-integers, `NaN`, `Infini |
+| `isNegative` | Checks if a value is a number less than 0.  Returns `false` for `NaN`, `0`, positive numbers, and no |
+| `isOdd` | Checks if a value is an odd integer.  Returns `false` for non-numbers, non-integers, `NaN`, `Infinit |
+| `isPositive` | Checks if a value is a number greater than 0.  Returns `false` for `NaN`, `0`, negative numbers, and |
 | `lerp` | Linearly interpolates between `start` and `end` by the factor `t`.  - `t = 0` returns `start`. - `t  |
 | `mean` | Calculates the arithmetic mean (average) of an array of numbers. Returns `NaN` for an empty array.   |
 | `randomBetween` | Generates a random number between min and max (inclusive) |
@@ -118,6 +123,50 @@ correctFloat(1.23456789, 6)  // => 1.23457
 
 ---
 
+### `extractNumber`
+
+Extracts the first number embedded anywhere in a string, or passes through a `number`.
+
+Unlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of
+the string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)
+is ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are
+disambiguated with ExtractNumberOptions.sign and ExtractNumberOptions.exponent.
+
+Returns `undefined` if no number can be found.
+
+```typescript
+import { extractNumber } from '@helpers4/number';
+
+extractNumber(value: unknown, options: ExtractNumberOptions): number | undefined
+```
+
+**Parameters:**
+
+- `value: unknown` — The value to extract a number from
+- `options: ExtractNumberOptions` (default: `{}`) — Options controlling sign and exponent disambiguation
+
+**Returns:** `number | undefined` — The extracted number, or `undefined` if none was found
+
+**Examples:**
+
+*extractNumber*
+
+```typescript
+```ts
+extractNumber('16.5px')        // => 16.5
+extractNumber('Wafer 10')      // => 10
+extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)
+extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)
+extractNumber('-111')          // => -111  ('-' at the start of the string → sign)
+extractNumber('1e5 mol')       // => 100000
+extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)
+extractNumber('no number')     // => undefined
+extractNumber(42)              // => 42
+```
+```
+
+---
+
 ### `formatCompact`
 
 Formats a number using compact notation (e.g. `1_500_000 → "1.5M"`).
@@ -239,6 +288,163 @@ inRange(10, 1, 10, { inclusive: 'none' }) // => false
 
 ---
 
+### `isEven`
+
+Checks if a value is an even integer.
+
+Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.
+
+```typescript
+import { isEven } from '@helpers4/number';
+
+isEven(value: unknown): value is number
+```
+
+**Parameters:**
+
+- `value: unknown` — The value to check
+
+**Returns:** `value is number` — `true` if value is an integer divisible by 2
+
+**Examples:**
+
+*Check if a number is even*
+
+Returns true for integers divisible by 2, false otherwise.
+
+```typescript
+isEven(4)   // => true
+isEven(0)   // => true
+isEven(3)   // => false
+isEven(1.5) // => false  (not an integer)
+```
+
+*Filter even numbers from an array*
+
+Use as a predicate in .filter() to extract even integers.
+
+```typescript
+const nums = [1, 2, 3, 4, 5, 6];
+nums.filter(isEven)
+// => [2, 4, 6]
+```
+
+---
+
+### `isNegative`
+
+Checks if a value is a number less than 0.
+
+Returns `false` for `NaN`, `0`, positive numbers, and non-number types.
+
+```typescript
+import { isNegative } from '@helpers4/number';
+
+isNegative(value: unknown): value is number
+```
+
+**Parameters:**
+
+- `value: unknown` — The value to check
+
+**Returns:** `value is number` — True if value is a negative number
+
+**Examples:**
+
+*isNegative*
+
+```typescript
+```ts
+isNegative(-1)        // => true
+isNegative(-0.5)      // => true
+isNegative(-Infinity) // => true
+isNegative(0)         // => false
+isNegative(1)         // => false
+isNegative(NaN)       // => false
+```
+```
+
+---
+
+### `isOdd`
+
+Checks if a value is an odd integer.
+
+Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.
+
+```typescript
+import { isOdd } from '@helpers4/number';
+
+isOdd(value: unknown): value is number
+```
+
+**Parameters:**
+
+- `value: unknown` — The value to check
+
+**Returns:** `value is number` — `true` if value is an integer not divisible by 2
+
+**Examples:**
+
+*Check if a number is odd*
+
+Returns true for integers not divisible by 2, false otherwise.
+
+```typescript
+isOdd(3)   // => true
+isOdd(1)   // => true
+isOdd(2)   // => false
+isOdd(0)   // => false
+isOdd(1.5) // => false  (not an integer)
+```
+
+*Filter odd numbers from an array*
+
+Use as a predicate in .filter() to extract odd integers.
+
+```typescript
+const nums = [1, 2, 3, 4, 5, 6];
+nums.filter(isOdd)
+// => [1, 3, 5]
+```
+
+---
+
+### `isPositive`
+
+Checks if a value is a number greater than 0.
+
+Returns `false` for `NaN`, `0`, negative numbers, and non-number types.
+
+```typescript
+import { isPositive } from '@helpers4/number';
+
+isPositive(value: unknown): value is number
+```
+
+**Parameters:**
+
+- `value: unknown` — The value to check
+
+**Returns:** `value is number` — True if value is a positive number
+
+**Examples:**
+
+*isPositive*
+
+```typescript
+```ts
+isPositive(42)       // => true
+isPositive(0.1)      // => true
+isPositive(Infinity) // => true
+isPositive(0)        // => false
+isPositive(-1)       // => false
+isPositive(NaN)      // => false
+```
+```
+
+---
+
 ### `lerp`
 
 Linearly interpolates between `start` and `end` by the factor `t`.

package/meta/api.json

@@ -1,6 +1,6 @@
 {
   "category": "number",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "functions": [
     {
       "name": "clamp",
@@ -85,6 +85,43 @@
       ],
       "sourceFile": "correctFloat.ts"
     },
+    {
+      "name": "extractNumber",
+      "kind": "function",
+      "description": "Extracts the first number embedded anywhere in a string, or passes through a `number`.\n\nUnlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of\nthe string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)\nis ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are\ndisambiguated with ExtractNumberOptions.sign and ExtractNumberOptions.exponent.\n\nReturns `undefined` if no number can be found.",
+      "since": "2.0.3",
+      "signatures": [
+        {
+          "signature": "extractNumber(value: unknown, options: ExtractNumberOptions): number | undefined",
+          "description": "Extracts the first number embedded anywhere in a string, or passes through a `number`.\n\nUnlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of\nthe string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)\nis ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are\ndisambiguated with ExtractNumberOptions.sign and ExtractNumberOptions.exponent.\n\nReturns `undefined` if no number can be found.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to extract a number from"
+            },
+            {
+              "name": "options",
+              "type": "ExtractNumberOptions",
+              "description": "Options controlling sign and exponent disambiguation",
+              "defaultValue": "{}"
+            }
+          ],
+          "returns": {
+            "type": "number | undefined",
+            "description": "The extracted number, or `undefined` if none was found"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "extractNumber",
+          "description": "",
+          "code": "```ts\nextractNumber('16.5px')        // => 16.5\nextractNumber('Wafer 10')      // => 10\nextractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\nextractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\nextractNumber('-111')          // => -111  ('-' at the start of the string → sign)\nextractNumber('1e5 mol')       // => 100000\nextractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\nextractNumber('no number')     // => undefined\nextractNumber(42)              // => 42\n```"
+        }
+      ],
+      "sourceFile": "extractNumber.ts"
+    },
     {
       "name": "formatCompact",
       "kind": "function",
@@ -208,14 +245,141 @@
           "code": "inRange(5, 1, 10, { inclusive: 'none' })  // => true\ninRange(1, 1, 10, { inclusive: 'none' })  // => false\ninRange(10, 1, 10, { inclusive: 'none' }) // => false"
         }
       ],
-      "sourceFile": "inRange.ts",
-      "relatedTypes": [
+      "sourceFile": "inRange.ts"
+    },
+    {
+      "name": "isEven",
+      "kind": "function",
+      "description": "Checks if a value is an even integer.\n\nReturns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.",
+      "since": "2.0.3",
+      "signatures": [
+        {
+          "signature": "isEven(value: unknown): value is number",
+          "description": "Checks if a value is an even integer.\n\nReturns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to check"
+            }
+          ],
+          "returns": {
+            "type": "value is number",
+            "description": "`true` if value is an integer divisible by 2"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Check if a number is even",
+          "description": "Returns true for integers divisible by 2, false otherwise.",
+          "code": "isEven(4)   // => true\nisEven(0)   // => true\nisEven(3)   // => false\nisEven(1.5) // => false  (not an integer)"
+        },
+        {
+          "title": "Filter even numbers from an array",
+          "description": "Use as a predicate in .filter() to extract even integers.",
+          "code": "const nums = [1, 2, 3, 4, 5, 6];\nnums.filter(isEven)\n// => [2, 4, 6]"
+        }
+      ],
+      "sourceFile": "isEven.ts"
+    },
+    {
+      "name": "isNegative",
+      "kind": "function",
+      "description": "Checks if a value is a number less than 0.\n\nReturns `false` for `NaN`, `0`, positive numbers, and non-number types.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "isNegative(value: unknown): value is number",
+          "description": "Checks if a value is a number less than 0.\n\nReturns `false` for `NaN`, `0`, positive numbers, and non-number types.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to check"
+            }
+          ],
+          "returns": {
+            "type": "value is number",
+            "description": "True if value is a negative number"
+          }
+        }
+      ],
+      "examples": [
         {
-          "name": "InRangeOptions",
-          "description": "Options for inRange.",
-          "typeDefinition": "interface InRangeOptions {\n  inclusive?: \"min\" | \"max\" | \"both\" | \"none\";\n}"
+          "title": "isNegative",
+          "description": "",
+          "code": "```ts\nisNegative(-1)        // => true\nisNegative(-0.5)      // => true\nisNegative(-Infinity) // => true\nisNegative(0)         // => false\nisNegative(1)         // => false\nisNegative(NaN)       // => false\n```"
         }
-      ]
+      ],
+      "sourceFile": "isNegative.ts"
+    },
+    {
+      "name": "isOdd",
+      "kind": "function",
+      "description": "Checks if a value is an odd integer.\n\nReturns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.",
+      "since": "2.0.3",
+      "signatures": [
+        {
+          "signature": "isOdd(value: unknown): value is number",
+          "description": "Checks if a value is an odd integer.\n\nReturns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to check"
+            }
+          ],
+          "returns": {
+            "type": "value is number",
+            "description": "`true` if value is an integer not divisible by 2"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Check if a number is odd",
+          "description": "Returns true for integers not divisible by 2, false otherwise.",
+          "code": "isOdd(3)   // => true\nisOdd(1)   // => true\nisOdd(2)   // => false\nisOdd(0)   // => false\nisOdd(1.5) // => false  (not an integer)"
+        },
+        {
+          "title": "Filter odd numbers from an array",
+          "description": "Use as a predicate in .filter() to extract odd integers.",
+          "code": "const nums = [1, 2, 3, 4, 5, 6];\nnums.filter(isOdd)\n// => [1, 3, 5]"
+        }
+      ],
+      "sourceFile": "isOdd.ts"
+    },
+    {
+      "name": "isPositive",
+      "kind": "function",
+      "description": "Checks if a value is a number greater than 0.\n\nReturns `false` for `NaN`, `0`, negative numbers, and non-number types.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "isPositive(value: unknown): value is number",
+          "description": "Checks if a value is a number greater than 0.\n\nReturns `false` for `NaN`, `0`, negative numbers, and non-number types.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to check"
+            }
+          ],
+          "returns": {
+            "type": "value is number",
+            "description": "True if value is a positive number"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "isPositive",
+          "description": "",
+          "code": "```ts\nisPositive(42)       // => true\nisPositive(0.1)      // => true\nisPositive(Infinity) // => true\nisPositive(0)        // => false\nisPositive(-1)       // => false\nisPositive(NaN)      // => false\n```"
+        }
+      ],
+      "sourceFile": "isPositive.ts"
     },
     {
       "name": "lerp",

package/meta/examples.json

@@ -26,6 +26,16 @@
         }
       ]
     },
+    {
+      "name": "extractNumber",
+      "examples": [
+        {
+          "title": "extractNumber",
+          "description": "",
+          "code": "```ts\nextractNumber('16.5px')        // => 16.5\nextractNumber('Wafer 10')      // => 10\nextractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\nextractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\nextractNumber('-111')          // => -111  ('-' at the start of the string → sign)\nextractNumber('1e5 mol')       // => 100000\nextractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\nextractNumber('no number')     // => undefined\nextractNumber(42)              // => 42\n```"
+        }
+      ]
+    },
     {
       "name": "formatCompact",
       "examples": [
@@ -66,6 +76,56 @@
         }
       ]
     },
+    {
+      "name": "isEven",
+      "examples": [
+        {
+          "title": "Check if a number is even",
+          "description": "Returns true for integers divisible by 2, false otherwise.",
+          "code": "isEven(4)   // => true\nisEven(0)   // => true\nisEven(3)   // => false\nisEven(1.5) // => false  (not an integer)"
+        },
+        {
+          "title": "Filter even numbers from an array",
+          "description": "Use as a predicate in .filter() to extract even integers.",
+          "code": "const nums = [1, 2, 3, 4, 5, 6];\nnums.filter(isEven)\n// => [2, 4, 6]"
+        }
+      ]
+    },
+    {
+      "name": "isNegative",
+      "examples": [
+        {
+          "title": "isNegative",
+          "description": "",
+          "code": "```ts\nisNegative(-1)        // => true\nisNegative(-0.5)      // => true\nisNegative(-Infinity) // => true\nisNegative(0)         // => false\nisNegative(1)         // => false\nisNegative(NaN)       // => false\n```"
+        }
+      ]
+    },
+    {
+      "name": "isOdd",
+      "examples": [
+        {
+          "title": "Check if a number is odd",
+          "description": "Returns true for integers not divisible by 2, false otherwise.",
+          "code": "isOdd(3)   // => true\nisOdd(1)   // => true\nisOdd(2)   // => false\nisOdd(0)   // => false\nisOdd(1.5) // => false  (not an integer)"
+        },
+        {
+          "title": "Filter odd numbers from an array",
+          "description": "Use as a predicate in .filter() to extract odd integers.",
+          "code": "const nums = [1, 2, 3, 4, 5, 6];\nnums.filter(isOdd)\n// => [1, 3, 5]"
+        }
+      ]
+    },
+    {
+      "name": "isPositive",
+      "examples": [
+        {
+          "title": "isPositive",
+          "description": "",
+          "code": "```ts\nisPositive(42)       // => true\nisPositive(0.1)      // => true\nisPositive(Infinity) // => true\nisPositive(0)        // => false\nisPositive(-1)       // => false\nisPositive(NaN)      // => false\n```"
+        }
+      ]
+    },
     {
       "name": "lerp",
       "examples": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/number",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for number.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -29,9 +29,14 @@
     "number",
     "clamp",
     "correctFloat",
+    "extractNumber",
     "formatCompact",
     "formatSize",
     "inRange",
+    "isEven",
+    "isNegative",
+    "isOdd",
+    "isPositive",
     "lerp",
     "mean",
     "random",