@lvlte/ulp 1.1.1 → 1.2.1

package/dist/cjs/index.d.ts

@@ -20,7 +20,25 @@ export declare const ulp: typeof eps;
  * Exponent of a normalized floating-point number x.
  *
  * @param x The input number
- * @returns The largest integer `y` such that `2^y ≤ |x|`, or `NaN` if x is not
- * a finite number / if x is ±0.
+ * @returns The largest integer `y` such that `2^y ≤ |x|`. If `x` is not a
+ * finite number or equals ±0, returns `NaN`.
  */
 export declare function exponent(x: number): number;
+/**
+ * Return the smallest representable floating-point number that comes after `x`
+ * on the float64 number line (towards +∞).
+ *
+ * @param x The input number
+ * @returns The smallest floating-point number `y` such that `y > x`. If `x` is
+ * `±Infinity` or `NaN`, returns `x`.
+ */
+export declare function nextFloat(x: number): number;
+/**
+ * Return the largest representable floating-point number that comes before `x`
+ * on the float64 number line (towards -∞).
+ *
+ * @param x The input number
+ * @returns The largest floating-point number `y` such that `y < x`. If `x` is
+ * `±Infinity` or `NaN`, returns `x`.
+ */
+export declare function prevFloat(x: number): number;

package/dist/cjs/index.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ulp = exports.FLOAT64_MIN = void 0;
 exports.eps = eps;
 exports.exponent = exponent;
+exports.nextFloat = nextFloat;
+exports.prevFloat = prevFloat;
 exports.FLOAT64_MIN = Math.pow(2, -1022);
 function eps(x = 1) {
     if (Number.isFinite(x)) {
@@ -25,3 +27,24 @@ function _exponent(x) {
     const s = x.toString(2);
     return x < 1 ? -(s.split('1', 1)[0].length - 1) : s.split('.', 1)[0].length - 1;
 }
+function nextFloat(x) {
+    switch (x) {
+        case -Infinity:
+            return -Number.MAX_VALUE;
+        case Infinity:
+        case Number.MAX_VALUE:
+            return Infinity;
+        case -Number.MIN_VALUE:
+            return -0;
+        default:
+            if (!Number.isFinite(x)) {
+                return NaN;
+            }
+    }
+    const e = eps(x);
+    const y = x + e / 2;
+    return y > x ? y : x + e;
+}
+function prevFloat(x) {
+    return typeof x === 'number' ? -nextFloat(-x) : NaN;
+}

package/dist/index.d.ts

@@ -20,7 +20,25 @@ export declare const ulp: typeof eps;
  * Exponent of a normalized floating-point number x.
  *
  * @param x The input number
- * @returns The largest integer `y` such that `2^y ≤ |x|`, or `NaN` if x is not
- * a finite number / if x is ±0.
+ * @returns The largest integer `y` such that `2^y ≤ |x|`. If `x` is not a
+ * finite number or equals ±0, returns `NaN`.
  */
 export declare function exponent(x: number): number;
+/**
+ * Return the smallest representable floating-point number that comes after `x`
+ * on the float64 number line (towards +∞).
+ *
+ * @param x The input number
+ * @returns The smallest floating-point number `y` such that `y > x`. If `x` is
+ * `±Infinity` or `NaN`, returns `x`.
+ */
+export declare function nextFloat(x: number): number;
+/**
+ * Return the largest representable floating-point number that comes before `x`
+ * on the float64 number line (towards -∞).
+ *
+ * @param x The input number
+ * @returns The largest floating-point number `y` such that `y < x`. If `x` is
+ * `±Infinity` or `NaN`, returns `x`.
+ */
+export declare function prevFloat(x: number): number;

package/dist/index.js

@@ -20,3 +20,24 @@ function _exponent(x) {
     const s = x.toString(2);
     return x < 1 ? -(s.split('1', 1)[0].length - 1) : s.split('.', 1)[0].length - 1;
 }
+export function nextFloat(x) {
+    switch (x) {
+        case -Infinity:
+            return -Number.MAX_VALUE;
+        case Infinity:
+        case Number.MAX_VALUE:
+            return Infinity;
+        case -Number.MIN_VALUE:
+            return -0;
+        default:
+            if (!Number.isFinite(x)) {
+                return NaN;
+            }
+    }
+    const e = eps(x);
+    const y = x + e / 2;
+    return y > x ? y : x + e;
+}
+export function prevFloat(x) {
+    return typeof x === 'number' ? -nextFloat(-x) : NaN;
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@lvlte/ulp",
-  "version": "1.1.1",
-  "description": "Compute the unit in last place of a given IEEE-754 64-bit number",
+  "version": "1.2.1",
+  "description": "Compute the ULP of a given number / Get the closest representable number that comes before/after it on the float64 number line",
   "license": "MIT",
   "author": "Eric Lavault <lvlte.code@gmail.com>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lvlte/ulp"
+    "url": "git+https://github.com/lvlte/ulp.git"
   },
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -38,17 +38,18 @@
   "keywords": [
     "number",
     "epsilon",
-    "function",
     "precision",
     "eps",
     "ulp",
+    "nextFloat",
+    "prevFloat",
+    "next",
+    "previous",
     "float",
     "float64",
     "IEEE-754",
     "rounding",
     "tolerance",
-    "compare",
-    "equal",
     "ULP"
   ],
   "devDependencies": {

package/readme.md

@@ -1,7 +1,10 @@
 # ulp (epsilon function)
 
-> Compute the [unit of least precision](https://en.wikipedia.org/wiki/Unit_in_the_last_place)
-of a given IEEE-754 64-bit number.
+> Compute the [ULP](https://en.wikipedia.org/wiki/Unit_in_the_last_place)
+of a given IEEE-754 64-bit number: `eps(x)` (alias: `ulp(x)`).<br>
+> Get the closest representable number that comes before/after it on the float64
+number line: `nextFloat(x)`, `prevFloat(x)`.
+
 
 ## Install
 
@@ -11,30 +14,51 @@ npm install @lvlte/ulp
 
 ## Usage
 
+### Import
+
 ```js
 // ESM
-import { eps } from '@lvlte/ulp';
+import { eps, nextFloat, prevFloat } from '@lvlte/ulp';
 ```
 ```js
 // CJS
-const { eps } = require('@lvlte/ulp');
+const { eps, nextFloat, prevFloat } = require('@lvlte/ulp');
 ```
+
+### eps(x) / ulp(x) (alias)
+```js
+console.log( eps() );                               // 2.220446049250313e-16
+console.log( eps() === eps(1) );                    // true
+console.log( eps() === Number.EPSILON );            // true
+
+console.log( eps(Number.MAX_SAFE_INTEGER) );        // 1
+console.log( eps(Number.MAX_SAFE_INTEGER + 1) );    // 2
+
+console.log( eps(0) );                              // 5e-324
+console.log( eps(0) === Number.MIN_VALUE );         // true
+
+console.log( eps(Infinity) );                       // NaN
+```
+
+### nextFloat(x) / prevFloat(x)
 ```js
-console.log(eps());                             // 2.220446049250313e-16
-console.log(eps() === eps(1));                  // true
-console.log(eps() === Number.EPSILON);          // true
+console.log( nextFloat(0) );                        // 5e-324
+console.log( nextFloat(0) === Number.MIN_VALUE );   // true
 
-console.log(eps(Number.MAX_SAFE_INTEGER));      // 1
-console.log(eps(Number.MAX_SAFE_INTEGER + 1));  // 2
+console.log( nextFloat(1) );                        // 1.0000000000000002
+console.log( nextFloat(1) === 1 + eps(1) );         // true
 
-console.log(eps(0));                            // 5e-324
-console.log(eps(0) === Number.MIN_VALUE);       // true
+console.log( nextFloat(Number.MAX_SAFE_INTEGER) );  // 9007199254740992
+console.log( nextFloat(9007199254740992) );         // 9007199254740994
+console.log( nextFloat(Number.MAX_VALUE) );         // Infinity
 
-console.log(eps(Infinity));                     // NaN
+console.log( prevFloat(0) );                        // -5e-324
+console.log( prevFloat(1) );                        // 0.9999999999999999
+console.log( prevFloat(9007199254740992) );         // 9007199254740991
+console.log( prevFloat(Infinity) );                 // 1.7976931348623157e+308
 ```
 
 ## Use case
 
-- Check whether two floating point numbers can be considered equal.
-- Approximate a floating point number x as a rational number.
-- Get the next/previous float on the float64 number line.
+- Use the proper tolerance to check whether two floating-point numbers should be considered equal.
+- Use the proper tolerance to approximate a floating-point number as a rational number.