fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Floating-Point Representation, Overflow, and Underflow

Install and import#

bash
npm install fintech-algorithms
ts
import { floatingPointRepresentationOverflowAndUnderflow } from "fintech-algorithms/foundations/statistical-computing-and-reproducibility/floating-point-representation-overflow-and-underflow";

Signature#

floatingPointRepresentationOverflowAndUnderflow(input)

Inspects one double-precision number: whether it is finite, how large one representable step at its magnitude is, and whether squaring it would stay inside a stated magnitude ceiling.

Parameters#

NameTypeNotes
inputD00InputReads floatingValue, the number under inspection, and maxSafeMagnitude, the largest magnitude the caller is willing to reach. A non-empty values list of finite numbers must also be present; it is validated but not used here.

Returns#

D00Output

isFinite reports whether floatingValue is a finite number, nextUp is the next representable double above it, ulp is the spacing between adjacent doubles at its magnitude, and overflowGuard is true when the magnitude is at most the square root of maxSafeMagnitude. overflowGuard bounds only the overflow side of a squaring step: a value small enough to pass the guard can still square to zero, so underflow needs its own check.

Errors#

  • When values is absent, empty, or holds a non-finite number — throws RangeError

Complexity: time O(n), space O(n).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

input
{
  "values": [1, 2, 3, 4, 5],
  "floatingValue": 0.1,
  "maxSafeMagnitude": 1.7976931348623157e+308,
  "window": 3,
  "rawValues": [1, null, 2, "bad", 3],
  "invalidPolicy": "drop-and-report",
  "seed": 42,
  "sampleCount": 5,
  "leftVector": [
    {
      "index": "A",
      "value": 1
    },
    {
      "index": "B",
      "value": 2
    }
  ],
  "rightVector": [
    {
      "index": "B",
      "value": 20
    },
    {
      "index": "C",
      "value": 30
    }
  ],
  "train": [10, 12, 14, 16],
  "test": [18, 20],
  "actual": [1, 2.0000001, 3],
  "expected": [1, 2, 3]
}

Showing 14 of 18 fields.

Call#

floatingPointRepresentationOverflowAndUnderflow(input)

Returns#

object with 4 fields: isFinite, ulp, nextUp, overflowGuard

{
  "isFinite": true,
  "ulp": 1.3877787807814457e-17,
  "nextUp": 0.10000000000000002,
  "overflowGuard": true
}

Diagrams#

Floating-Point Representation, Overflow, and Underflow — article hero
Floating-Point Representation, Overflow, and Underflow — calculation ledger
Floating-Point Representation, Overflow, and Underflow — concept anatomy
Floating-Point Representation, Overflow, and Underflow — failure boundary
Floating-Point Representation, Overflow, and Underflow — method map
Floating-Point Representation, Overflow, and Underflow — scenario contrast

Calculation flow#

Reasoning flow — D00-F12-A01 
flowchart LR
    A["Synthetic input + metadata"] --> B{"Contract valid?"}
    B -->|No| C["Reject or route with reason"]
    B -->|Yes| D["Apply Floating-Point Representation, Overflow, and Underflow"]
    D --> E["Formula: ulp(x) = spacing between adjacent doubles at |x|; nextUp(x) = next double above x"]
    E --> F["Verified fixture output"]
    F --> G{"Interpretation within boundary?"}
    G -->|Yes| H["Report value + convention + audit"]
    G -->|No| I["Add companion view or narrower claim"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

The rest of the Statistical Computing and Reproducibility family#