@helpers4/number 2.0.2 → 2.0.4

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.4
 > 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,15 +24,18 @@ 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) |
 | `randomIntBetween` | Generates a random integer between min and max (inclusive) |
 | `roundTo` | Rounds a number to specified decimal places |
-| `sum` | Calculates the sum of an array of numbers. |
 
 ---
 
@@ -83,6 +86,10 @@ Note: for values whose integer part already consumes 14 or more digits
 digits and will silently truncate them. Increase `precision` if you
 need to correct drift in very large numbers.
 
+Note: IEEE-754 doubles carry at most ~17 significant decimal digits.
+Precision values above 17 pad with digits that reflect the underlying
+binary representation rather than correcting drift.
+
 ```typescript
 import { correctFloat } from '@helpers4/number';
 
@@ -92,7 +99,9 @@ correctFloat(value: number, precision: number): number
 **Parameters:**
 
 - `value: number` — The floating-point value to correct
-- `precision: number` (default: `14`) — Integer number of significant digits (default: 14)
+- `precision: number` (default: `14`) — Integer number of significant digits between 1 and 100
+  (default: 14). Values above 17 are valid but expose binary noise beyond
+  IEEE-754's meaningful range.
 
 **Returns:** `number` — The corrected value
 
@@ -118,6 +127,53 @@ 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('.5rem')         // => 0.5   (leading-dot decimal)
+extractNumber('-.5')           // => -0.5  (leading-dot with sign)
+extractNumber('Wafer 10')      // => 10
+extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)
+extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)
+extractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)
+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,80 +295,204 @@ inRange(10, 1, 10, { inclusive: 'none' }) // => false
 
 ---
 
-### `lerp`
+### `isEven`
 
-Linearly interpolates between `start` and `end` by the factor `t`.
+Checks if a value is an even integer.
 
-- `t = 0` returns `start`.
-- `t = 1` returns `end`.
-- Values of `t` outside `[0, 1]` extrapolate beyond the range.
+Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.
 
 ```typescript
-import { lerp } from '@helpers4/number';
+import { isEven } from '@helpers4/number';
 
-lerp(start: number, end: number, t: number): number
+isEven(value: unknown): value is number
 ```
 
 **Parameters:**
 
-- `start: number` — The start value.
-- `end: number` — The end value.
-- `t: number` — The interpolation factor.
+- `value: unknown` — The value to check
 
-**Returns:** `number` — The interpolated value.
+**Returns:** `value is number` — `true` if value is an integer divisible by 2
 
 **Examples:**
 
-*Interpolate between two values*
+*Check if a number is even*
 
-Returns the value between start and end at position t (0 = start, 1 = end).
+Returns true for integers divisible by 2, false otherwise.
 
 ```typescript
-lerp(0, 100, 0)    // => 0
-lerp(0, 100, 0.5)  // => 50
-lerp(0, 100, 1)    // => 100
+isEven(4)   // => true
+isEven(0)   // => true
+isEven(3)   // => false
+isEven(1.5) // => false  (not an integer)
 ```
 
-*Animate a colour channel*
+*Filter even numbers from an array*
 
-t outside [0, 1] extrapolates beyond the range.
+Use as a predicate in .filter() to extract even integers.
 
 ```typescript
-lerp(0, 255, 0.5) // => 127.5
-lerp(0, 10, 2)    // => 20  (extrapolation)
+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]
 ```
 
 ---
 
-### `mean`
+### `isPositive`
 
-Calculates the arithmetic mean (average) of an array of numbers.
-Returns `NaN` for an empty array.
+Checks if a value is a number greater than 0.
 
-Pairs with sum for aggregate operations.
+Returns `false` for `NaN`, `0`, negative numbers, and non-number types.
 
 ```typescript
-import { mean } from '@helpers4/number';
+import { isPositive } from '@helpers4/number';
 
-mean(array: readonly number[]): number
+isPositive(value: unknown): value is number
 ```
 
 **Parameters:**
 
-- `array: readonly number[]` — The array of numbers to average
+- `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`.
+
+- `t = 0` returns `start`.
+- `t = 1` returns `end`.
+- Values of `t` outside `[0, 1]` extrapolate beyond the range.
+
+```typescript
+import { lerp } from '@helpers4/number';
+
+lerp(start: number, end: number, t: number): number
+```
+
+**Parameters:**
+
+- `start: number` — The start value.
+- `end: number` — The end value.
+- `t: number` — The interpolation factor.
 
-**Returns:** `number` — The arithmetic mean, or `NaN` if the array is empty
+**Returns:** `number` — The interpolated value.
 
 **Examples:**
 
-*Average a list of numbers*
+*Interpolate between two values*
+
+Returns the value between start and end at position t (0 = start, 1 = end).
+
+```typescript
+lerp(0, 100, 0)    // => 0
+lerp(0, 100, 0.5)  // => 50
+lerp(0, 100, 1)    // => 100
+```
+
+*Animate a colour channel*
 
-Returns the arithmetic mean of the array; NaN for empty arrays.
+t outside [0, 1] extrapolates beyond the range.
 
 ```typescript
-mean([1, 2, 3, 4])  // => 2.5
-mean([10, 20, 30])  // => 20
-mean([])            // => NaN
+lerp(0, 255, 0.5) // => 127.5
+lerp(0, 10, 2)    // => 20  (extrapolation)
 ```
 
 ---
@@ -413,41 +593,3 @@ roundTo(3.7, 0)
 ```
 
 ---
-
-### `sum`
-
-Calculates the sum of an array of numbers.
-
-```typescript
-import { sum } from '@helpers4/number';
-
-sum(array: readonly number[]): number
-```
-
-**Parameters:**
-
-- `array: readonly number[]` — The array of numbers to sum
-
-**Returns:** `number` — The sum of all values
-
-**Examples:**
-
-*Sum numbers*
-
-Calculates the sum of an array of numbers.
-
-```typescript
-sum([1, 2, 3, 4])
-// => 10
-```
-
-*Sum with negative numbers*
-
-Handles negative numbers correctly.
-
-```typescript
-sum([10, -3, 5, -2])
-// => 10
-```
-
----