Skip to content
@ac-kit

BinaryFp

Defined in: packages/math-numbers/src/num/binary-fp.ts:87

IEEE 754 binary floating-point number, fully configured at construction by an IeeeFormat descriptor.

Backing store: The primary backing is the IeeeBinaryUnpacked discriminated union (unpacked sign, biased exponent, bigint significand). The packed Uint32Array IEEE 754 bit pattern is computed lazily on first access and cached for bitAt(), valueOf(), and related read operations.

Arithmetic goes through whichever SoftFloatKernel is installed. The default is the portable JS one; createWasmSoftFloatKernel swaps in the compiled Rust module. Installation is synchronous, so an accelerated build and a portable one have the same API — there is no await in front of arithmetic and no second public type to choose between.

Role in the type hierarchy:

  • BinaryFp64 is backed by the native JS number (binary64 hardware).
  • BinaryFp16 and BinaryFp32 are backed by a number, rounding the result of each operation back to their declared precision.
  • BinaryFp128 (and future wide formats) are backed by an instance of this class, configured with the appropriate Ieee754Parameters.

Note on valueOf(): it returns a JS number, so for a format wider than binary64 the result is a binary64 approximation (≤ ~15 significant decimal digits). The string forms are not: toString, toFixed, toExponential and toPrecision all go through the exact decimal expansion, so reach for one of those when the extra precision is the point.

References:

Extends

Section titled “Extends”
  • BinaryFpBase<BinaryFp>

Implements

Section titled “Implements”

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”

new BinaryFp(format, value): BinaryFp

Defined in: packages/math-numbers/src/num/binary-fp.ts:115

Creates a new BinaryFp value for the given IEEE 754 format.

Parameters

Section titled “Parameters”
format
Section titled “format”

IeeeFormat

Format descriptor (use one of the IEEE_FORMAT_BINARY* constants).

value
Section titled “value”

string | number | IeeeBinary

Initial value as a JS number, parseable string, or an already-decoded IeeeBinary (internal use by _wrapSf).

Returns

Section titled “Returns”

BinaryFp

Overrides

Section titled “Overrides”

BinaryFpBase<BinaryFp>.constructor

Properties

Section titled “Properties”

ieeeFormat

Section titled “ieeeFormat”

readonly ieeeFormat: IeeeFormat

Defined in: packages/math-numbers/src/num/binary-fp.ts:96

IEEE 754 format descriptor

STRUCTURE

Section titled “STRUCTURE”

readonly static STRUCTURE: AlgebraicStructure = APPROXIMATE_ORDERED_FIELD

Defined in: packages/math-numbers/src/num/_binary-fp-base.ts:41

Binary floating point is not a field: every operation rounds, so associativity and distributivity fail.

Inherited from

Section titled “Inherited from”

BinaryFpBase.STRUCTURE

TAG

Section titled “TAG”

readonly static TAG: typeof TAG

Defined in: packages/math-numbers/src/num/binary-fp.ts:105

Unique type tag used by the converter registry.

Accessors

Section titled “Accessors”

bitWidth

Section titled “bitWidth”

Get Signature

Section titled “Get Signature”

get bitWidth(): number

Defined in: packages/math-numbers/src/num/binary-fp.ts:91

Total width of the representation, in bits.

Returns
Section titled “Returns”

number

Total width of the representation, in bits.

Implementation of

Section titled “Implementation of”

IFixedPrecision.bitWidth

Overrides

Section titled “Overrides”

BinaryFpBase.bitWidth

decimalPrecision

Section titled “decimalPrecision”

Get Signature

Section titled “Get Signature”

get decimalPrecision(): number

Defined in: packages/math-numbers/src/num/binary-fp.ts:206

Number of significant decimal digits in the binary64 approximation.

Returns
Section titled “Returns”

number

Total number of significant decimal digits needed to exactly represent this value.

Returns Number.POSITIVE_INFINITY for values with non-terminating decimal expansions (e.g. Fraction(1, 3), √2).

Example

Section titled “Example”
  Integer.from(12345n).decimalPrecision; // → 5
  Decimal.from("3.14").decimalPrecision; // → 3
  Fraction.from(1n, 3n).decimalPrecision; // → Infinity
  ```;


#### Implementation of


[`INum`](../interfaces/INum.md).[`decimalPrecision`](../interfaces/INum.md#decimalprecision)


#### Overrides


`BinaryFpBase.decimalPrecision`


***


### formatInfo


#### Get Signature


> **get** **formatInfo**(): [`FixedPrecisionInfo`](../type-aliases/FixedPrecisionInfo.md)\<`BinaryFp`\>


Defined in: packages/math-numbers/src/num/binary-fp.ts:342


Fixed-precision format descriptor for this value's IEEE 754 format.


The limit values are computed from the format parameters: - `minPositive`:
smallest positive normal (`2^emin`) - `maxPositive`: largest finite (`(2 −
2^(1−p)) × 2^emax`)


##### Returns


[`FixedPrecisionInfo`](../type-aliases/FixedPrecisionInfo.md)\<`BinaryFp`\>


#### Overrides


`BinaryFpBase.formatInfo`


***


### fractionalPrecision


#### Get Signature


> **get** **fractionalPrecision**(): `number`


Defined in: packages/math-numbers/src/num/binary-fp.ts:224


Number of decimal digits in the fractional part.


##### Returns


`number`


Number of decimal digits in the fractional part of `|value|`. `0` for exact
integers. Returns `Number.POSITIVE_INFINITY` for non-terminating decimal
expansions.


#### Example


```ts
  Integer.from(42n).fractionalPrecision; // → 0
  Decimal.from("3.14").fractionalPrecision; // → 2
  Fraction.from(1n, 3n).fractionalPrecision; // → Infinity
  ```;


#### Implementation of


[`INum`](../interfaces/INum.md).[`fractionalPrecision`](../interfaces/INum.md#fractionalprecision)


#### Overrides


`BinaryFpBase.fractionalPrecision`


***


### integralPrecision


#### Get Signature


> **get** **integralPrecision**(): `number`


Defined in: packages/math-numbers/src/num/binary-fp.ts:215


Number of decimal digits in the integer part of `|value|`.


##### Returns


`number`


Number of decimal digits in the integer (integral) part of `|value|`.
Always at least `1` (the digit `0` for values with `|value| < 1`).


#### Example


```ts
  Integer.from(123n).integralPrecision; // → 3
  Decimal.from("0.5").integralPrecision; // → 1  (the leading '0')
  Decimal.from("3.14").integralPrecision; // → 1
  ```;


#### Implementation of


[`INum`](../interfaces/INum.md).[`integralPrecision`](../interfaces/INum.md#integralprecision)


#### Overrides


`BinaryFpBase.integralPrecision`


***


### isFinite


#### Get Signature


> **get** **isFinite**(): `boolean`


Defined in: packages/math-numbers/src/num/binary-fp.ts:137


`true` if this value is finite (not NaN and not ±∞).


##### Returns


`boolean`


***


### isInfinite


#### Get Signature


> **get** **isInfinite**(): `boolean`


Defined in: packages/math-numbers/src/num/binary-fp.ts:142


`true` if this value is +∞ or −∞.


##### Returns


`boolean`


***


### isNaN


#### Get Signature


> **get** **isNaN**(): `boolean`


Defined in: packages/math-numbers/src/num/binary-fp.ts:132


`true` if this value is IEEE 754 NaN.


##### Returns


`boolean`


***


### precisionKind


#### Get Signature


> **get** **precisionKind**(): `"fixed"`


Defined in: packages/math-numbers/src/num/\_binary-fp-base.ts:30


##### Returns


`"fixed"`


#### Implementation of


[`IFixedPrecision`](../interfaces/IFixedPrecision.md).[`precisionKind`](../interfaces/IFixedPrecision.md#precisionkind)


#### Inherited from


`BinaryFpBase.precisionKind`


***


### radix


#### Get Signature


> **get** **radix**(): `2`


Defined in: packages/math-numbers/src/num/\_binary-fp-base.ts:33


##### Returns


`2`


#### Implementation of


[`IBinaryEncoded`](../interfaces/IBinaryEncoded.md).[`radix`](../interfaces/IBinaryEncoded.md#radix)


#### Inherited from


`BinaryFpBase.radix`


## Methods


### \[toPrimitive\]()


> **\[toPrimitive\]**(`hint`): `string` \| `number` \| `bigint`


Defined in: packages/math-numbers/src/num/binary-fp.ts:194


Coerces to a JS primitive.


#### Parameters


##### hint


`"string"` \| `"number"` \| `"default"`


#### Returns


`string` \| `number` \| `bigint`


#### Implementation of


[`INum`](../interfaces/INum.md).[`[toPrimitive]`](../interfaces/INum.md#toprimitive)


#### Overrides


`BinaryFpBase.[toPrimitive]`


***


### abs()


> **abs**(): `BinaryFp`


Defined in: packages/math-numbers/src/num/binary-fp.ts:314


Absolute value `|x|`.


#### Returns


`BinaryFp`


#### Overrides


`BinaryFpBase.abs`


***


### add()


> **add**(`other`): `BinaryFp`


Defined in: packages/math-numbers/src/num/binary-fp.ts:254


Returns `this + other`.


#### Parameters


##### other


`BinaryFp`


#### Returns


`BinaryFp`


#### Overrides


`BinaryFpBase.add`


***


### bitAt()


> **bitAt**(`position`): `0` \| `1`


Defined in: packages/math-numbers/src/num/binary-fp.ts:394


Returns the bit at `position` in the packed IEEE 754 bit pattern. Position
`0` is the LSB; position `k − 1` is the sign bit.


#### Parameters


##### position


`number`


#### Returns


`0` \| `1`


#### Throws


When `position` is outside `[0, k − 1]`.


#### Overrides


`BinaryFpBase.bitAt`


***


### clamp()


> **clamp**(`lower`, `upper`): `BinaryFp`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:69


Restricts the value to `[lower, upper]`.


#### Parameters


##### lower


`BinaryFp`


##### upper


`BinaryFp`


#### Returns


`BinaryFp`


#### Inherited from


`BinaryFpBase.clamp`


***


### cmp()


> **cmp**(`other`): `Sign`


Defined in: packages/math-numbers/src/num/binary-fp.ts:305


Three-way comparison.


#### Parameters


##### other


`BinaryFp`


#### Returns


`Sign`


#### Throws


When either value is NaN.


#### Overrides


`BinaryFpBase.cmp`


***


### div()


> **div**(`other`): `BinaryFp`


Defined in: packages/math-numbers/src/num/binary-fp.ts:289


Returns `this / other` (IEEE 754 semantics).


#### Parameters


##### other


`BinaryFp`


#### Returns


`BinaryFp`


#### Overrides


`BinaryFpBase.div`


***


### eq()


> **eq**(`other`): `boolean`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:45


#### Parameters


##### other


`BinaryFp`


#### Returns


`boolean`


#### Inherited from


`BinaryFpBase.eq`


***


### format()


> **format**(`locales?`, `options?`): `string`


Defined in: packages/math-numbers/src/num/binary-fp.ts:177


This value rendered for a human, by `Intl.NumberFormat`.


The parameters are `new Intl.NumberFormat(locales, options)`'s own,
unchanged — including the default, which is the ambient locale. Ask for
`"en-US"` with `useGrouping: false` when the output has to be
machine-readable.


#### Parameters


##### locales?


`LocalesArgument`


##### options?


`NumberFormatOptions`


#### Returns


`string`


#### Implementation of


[`INum`](../interfaces/INum.md).[`format`](../interfaces/INum.md#format)


#### Overrides


`BinaryFpBase.format`


***


### gt()


> **gt**(`other`): `boolean`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:57


#### Parameters


##### other


`BinaryFp`


#### Returns


`boolean`


#### Inherited from


`BinaryFpBase.gt`


***


### gte()


> **gte**(`other`): `boolean`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:73


#### Parameters


##### other


`BinaryFp`


#### Returns


`boolean`


#### Inherited from


`BinaryFpBase.gte`


***


### identity()


> **identity**(): `BinaryFp`


Defined in: packages/math-numbers/src/num/binary-fp.ts:245


Returns the multiplicative identity `1.0`.


#### Returns


`BinaryFp`


#### Overrides


`BinaryFpBase.identity`


***


### inv()


> **inv**(): `BinaryFp`


Defined in: packages/math-numbers/src/num/binary-fp.ts:284


Returns `1 / this` (IEEE 754 semantics; ±∞ for zero).


#### Returns


`BinaryFp`


#### Overrides


`BinaryFpBase.inv`


***


### lt()


> **lt**(`other`): `boolean`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:49


#### Parameters


##### other


`BinaryFp`


#### Returns


`boolean`


#### Inherited from


`BinaryFpBase.lt`


***


### lte()


> **lte**(`other`): `boolean`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:53


#### Parameters


##### other


`BinaryFp`


#### Returns


`boolean`


#### Inherited from


`BinaryFpBase.lte`


***


### max()


> **max**(`other`): `BinaryFp`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:65


The larger of the two operands under the total order.


#### Parameters


##### other


`BinaryFp`


#### Returns


`BinaryFp`


#### Inherited from


`BinaryFpBase.max`


***


### min()


> **min**(`other`): `BinaryFp`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:61


The smaller of the two operands under the total order.


#### Parameters


##### other


`BinaryFp`


#### Returns


`BinaryFp`


#### Inherited from


`BinaryFpBase.min`


***


### mul()


> **mul**(`other`): `BinaryFp`


Defined in: packages/math-numbers/src/num/binary-fp.ts:237


Returns `this × other`.


#### Parameters


##### other


`BinaryFp`


#### Returns


`BinaryFp`


#### Overrides


`BinaryFpBase.mul`


***


### neg()


> **neg**(): `BinaryFp`


Defined in: packages/math-numbers/src/num/binary-fp.ts:267


Returns `−this`.


#### Returns


`BinaryFp`


#### Overrides


`BinaryFpBase.neg`


***


### sign()


> **sign**(): `Sign`


Defined in: packages/math-numbers/src/num/binary-fp.ts:319


Returns −1 for negative, 0 for zero/NaN, +1 for positive.


#### Returns


`Sign`


#### Overrides


`BinaryFpBase.sign`


***


### sqrt()


> **sqrt**(): `BinaryFp`


Defined in: packages/math-numbers/src/num/binary-fp.ts:324


Principal square root `√x`. Returns NaN for negative inputs.


#### Returns


`BinaryFp`


#### Overrides


`BinaryFpBase.sqrt`


***


### sub()


> **sub**(`other`): `BinaryFp`


Defined in: packages/math-numbers/src/num/binary-fp.ts:272


Returns `this − other`.


#### Parameters


##### other


`BinaryFp`


#### Returns


`BinaryFp`


#### Overrides


`BinaryFpBase.sub`


***


### toExponential()


> **toExponential**(`fractionDigits?`): `string`


Defined in: packages/math-numbers/src/num/binary-fp.ts:162


Exponential notation: one digit before the point, `fractionDigits` after,
and an `e±` exponent. Omitting the count shows as many as the value has,
matching `Number.prototype.toExponential`.


#### Parameters


##### fractionDigits?


`number`


#### Returns


`string`


#### Implementation of


[`INum`](../interfaces/INum.md).[`toExponential`](../interfaces/INum.md#toexponential)


#### Overrides


`BinaryFpBase.toExponential`


***


### toFixed()


> **toFixed**(`fractionDigits?`): `string`


Defined in: packages/math-numbers/src/num/binary-fp.ts:158


Fixed-point notation with exactly `fractionDigits` places, padded with
zeros where the value has fewer — `Number.prototype.toFixed`, without its
cap of 100. A type that can hold more places can show them.


#### Parameters


##### fractionDigits?


`number` = `0`


#### Returns


`string`


#### Implementation of


[`INum`](../interfaces/INum.md).[`toFixed`](../interfaces/INum.md#tofixed)


#### Overrides


`BinaryFpBase.toFixed`


***


### toPrecision()


> **toPrecision**(`precision`): `string`


Defined in: packages/math-numbers/src/num/binary-fp.ts:166


`precision` significant digits, switching to exponential notation at the
same thresholds `Number.prototype.toPrecision` does.


#### Parameters


##### precision


`number`


#### Returns


`string`


#### Implementation of


[`INum`](../interfaces/INum.md).[`toPrecision`](../interfaces/INum.md#toprecision)


#### Overrides


`BinaryFpBase.toPrecision`


***


### toString()


> **toString**(`radix?`): `string`


Defined in: packages/math-numbers/src/num/binary-fp.ts:154


The shortest round-tripping numeral for a format the engine can hold, and
the exact expansion for one it cannot — see [ieeeBinaryToString](../functions/ieeeBinaryToString.md).


#### Parameters


##### radix?


`number`


#### Returns


`string`


#### Implementation of


[`INum`](../interfaces/INum.md).[`toString`](../interfaces/INum.md#tostring)


#### Overrides


`BinaryFpBase.toString`


***


### valueOf()


> **valueOf**(): `number`


Defined in: packages/math-numbers/src/num/binary-fp.ts:189


Returns the value as a JS `number` (binary64 approximation).


#### Returns


`number`


#### Implementation of


[`INum`](../interfaces/INum.md).[`valueOf`](../interfaces/INum.md#valueof)


#### Overrides


`BinaryFpBase.valueOf`


***


### zero()


> **zero**(): `BinaryFp`


Defined in: packages/math-numbers/src/num/binary-fp.ts:262


Returns the additive identity `0.0`.


#### Returns


`BinaryFp`


#### Overrides


`BinaryFpBase.zero`