Skip to content
@ac-kit

Fraction

Defined in: packages/math-numbers/src/num/fraction.ts:65

A rational number expressed as the exact fraction p / q with p, q ∈ ℤ, `q

0`.

The contract shell over Rational. Every operation delegates to the free functions in rational.ts; no arithmetic happens in this class. What it adds is the tower’s uniform interface, the declared AlgebraicStructure, the evidence records and the promotion tag — none of which a bare pair of bigints can carry.

The bigint pair is also the storage, so arithmetic allocates no Integer. numerator and denominator wrap on access, which is rare and explicit.

const a = Fraction.from(1n, 3n);
const b = Fraction.from(1n, 6n);
a.add(b).reduce().format(); // "1/2"
Fraction.from(4n, 9n).sqrt().format(); // "2/3"

Extends

Section titled “Extends”
  • OrderedBase<Fraction>

Implements

Section titled “Implements”

Properties

Section titled “Properties”

field

Section titled “field”

readonly static field: Field<Fraction> = Fraction.orderedField

Defined in: packages/math-numbers/src/num/fraction.ts:111

Field evidence, an alias of orderedField without the order.

NEG_ONE

Section titled “NEG_ONE”

readonly static NEG_ONE: Fraction

Defined in: packages/math-numbers/src/num/fraction.ts:82

The fraction −1/1.

ONE

Section titled “ONE”

readonly static ONE: Fraction

Defined in: packages/math-numbers/src/num/fraction.ts:79

The fraction 1/1.

orderedField

Section titled “orderedField”

readonly static orderedField: OrderedField<Fraction>

Defined in: packages/math-numbers/src/num/fraction.ts:95

Evidence that Fraction forms an ordered field, for generic algorithms that take their structure as an argument rather than requiring it of the type. Verified against checkOrderedFieldLaws.

STRUCTURE

Section titled “STRUCTURE”

readonly static STRUCTURE: AlgebraicStructure = ORDERED_FIELD

Defined in: packages/math-numbers/src/num/fraction.ts:88

ℚ is an ordered field — exactly, since every operation is closed.

TAG

Section titled “TAG”

readonly static TAG: typeof TAG

Defined in: packages/math-numbers/src/num/fraction.ts:85

Unique type tag used by the factory and promotion tables.

ZERO

Section titled “ZERO”

readonly static ZERO: Fraction

Defined in: packages/math-numbers/src/num/fraction.ts:76

The fraction 0/1.

Accessors

Section titled “Accessors”

decimalPrecision

Section titled “decimalPrecision”

Get Signature

Section titled “Get Signature”

get decimalPrecision(): number

Defined in: packages/math-numbers/src/num/fraction.ts:235

Significant digits of the decimal expansion, or Infinity when it does not terminate.

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)


***


### denominator


#### Get Signature


> **get** **denominator**(): [`Integer`](Integer.md)


Defined in: packages/math-numbers/src/num/fraction.ts:150


The denominator — always strictly positive.


##### Returns


[`Integer`](Integer.md)


***


### fractionalPrecision


#### Get Signature


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


Defined in: packages/math-numbers/src/num/fraction.ts:247


Decimal places in the exact expansion, or `Infinity` when it repeats.


##### 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)


***


### integralPrecision


#### Get Signature


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


Defined in: packages/math-numbers/src/num/fraction.ts:240


Decimal digits in the integer part of `|this|`.


##### 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)


***


### isReduced


#### Get Signature


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


Defined in: packages/math-numbers/src/num/fraction.ts:155


`true` when the fraction is known to be in lowest terms.


##### Returns


`boolean`


***


### numerator


#### Get Signature


> **get** **numerator**(): [`Integer`](Integer.md)


Defined in: packages/math-numbers/src/num/fraction.ts:145


The numerator (may be negative).


##### Returns


[`Integer`](Integer.md)


## Methods


### \[toPrimitive\]()


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


Defined in: packages/math-numbers/src/num/fraction.ts:225


Coerces this value to a JS primitive: - `'number'` → same as `valueOf()` -
`'string'` → same as `toString()` - `'default'` → same as `valueOf()`


#### Parameters


##### hint


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


#### Returns


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


#### Implementation of


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


***


### abs()


> **abs**(): `Fraction`


Defined in: packages/math-numbers/src/num/fraction.ts:317


`|a/b|`.


#### Returns


`Fraction`


***


### add()


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


Defined in: packages/math-numbers/src/num/fraction.ts:266


`(a/b) + (c/d)`.


#### Parameters


##### other


`Fraction`


#### Returns


`Fraction`


***


### clamp()


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


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


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


#### Parameters


##### lower


`Fraction`


##### upper


`Fraction`


#### Returns


`Fraction`


#### Inherited from


`OrderedBase.clamp`


***


### cmp()


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


Defined in: packages/math-numbers/src/num/fraction.ts:308


Three-way comparison.


#### Parameters


##### other


`Fraction`


#### Returns


`Sign`


#### Overrides


`OrderedBase.cmp`


***


### div()


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


Defined in: packages/math-numbers/src/num/fraction.ts:299


`(a/b) ÷ (c/d)`.


#### Parameters


##### other


`Fraction`


#### Returns


`Fraction`


#### Throws


When `other` is zero.


***


### eq()


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


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


#### Parameters


##### other


`Fraction`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.eq`


***


### format()


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


Defined in: packages/math-numbers/src/num/fraction.ts:181


The decimal value, localized. `Intl` has no ratio notation, so this is the
decimal expansion rather than [toString](#tostring)'s `p/q` — rounded to whatever
`options` asks for, which for a non-terminating fraction is the only thing
it could be.


#### Parameters


##### locales?


`LocalesArgument`


##### options?


`NumberFormatOptions`


#### Returns


`string`


#### Implementation of


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


***


### gt()


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


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


#### Parameters


##### other


`Fraction`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.gt`


***


### gte()


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


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


#### Parameters


##### other


`Fraction`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.gte`


***


### identity()


> **identity**(): `Fraction`


Defined in: packages/math-numbers/src/num/fraction.ts:261


The multiplicative identity `1/1`.


#### Returns


`Fraction`


***


### inv()


> **inv**(): `Fraction`


Defined in: packages/math-numbers/src/num/fraction.ts:290


The reciprocal `b/a`.


#### Returns


`Fraction`


#### Throws


When called on zero.


***


### lt()


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


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


#### Parameters


##### other


`Fraction`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.lt`


***


### lte()


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


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


#### Parameters


##### other


`Fraction`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.lte`


***


### max()


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


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


The larger of the two operands under the total order.


#### Parameters


##### other


`Fraction`


#### Returns


`Fraction`


#### Inherited from


`OrderedBase.max`


***


### min()


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


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


The smaller of the two operands under the total order.


#### Parameters


##### other


`Fraction`


#### Returns


`Fraction`


#### Inherited from


`OrderedBase.min`


***


### mul()


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


Defined in: packages/math-numbers/src/num/fraction.ts:256


`(a/b) × (c/d)`.


#### Parameters


##### other


`Fraction`


#### Returns


`Fraction`


***


### neg()


> **neg**(): `Fraction`


Defined in: packages/math-numbers/src/num/fraction.ts:276


`−(a/b)`.


#### Returns


`Fraction`


***


### reduce()


> **reduce**(): `Fraction`


Defined in: packages/math-numbers/src/num/fraction.ts:160


An equivalent fraction in lowest terms.


#### Returns


`Fraction`


***


### sign()


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


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


`-1` for negative, `0` for zero, `1` for positive.


#### Returns


`Sign`


***


### sqrt()


> **sqrt**(): `Fraction`


Defined in: packages/math-numbers/src/num/fraction.ts:335


The exact square root, when numerator and denominator are both perfect
squares.


#### Returns


`Fraction`


#### Throws


When this fraction is negative, or the root is
  irrational.


***


### sub()


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


Defined in: packages/math-numbers/src/num/fraction.ts:281


`(a/b) − (c/d)`.


#### Parameters


##### other


`Fraction`


#### Returns


`Fraction`


***


### toExponential()


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


Defined in: packages/math-numbers/src/num/fraction.ts:197


Exponential notation, with as many places as asked for.


#### Parameters


##### fractionDigits?


`number`


#### Returns


`string`


#### Implementation of


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


***


### toFixed()


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


Defined in: packages/math-numbers/src/num/fraction.ts:192


Fixed-point notation with `fractionDigits` places. A repeating expansion is
rounded there, since it has nowhere else to stop.


#### Parameters


##### fractionDigits?


`number` = `0`


#### Returns


`string`


#### Implementation of


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


***


### toFraction()


> **toFraction**(): `Fraction`


Defined in: packages/math-numbers/src/num/fraction.ts:352


Returns this fraction — it is already in ℚ exact form.


#### Returns


`Fraction`


***


### toPrecision()


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


Defined in: packages/math-numbers/src/num/fraction.ts:205


`precision` significant digits, in whichever notation reads better.


#### Parameters


##### precision


`number`


#### Returns


`string`


#### Implementation of


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


***


### toRational()


> **toRational**(): [`Rational`](../type-aliases/Rational.md)


Defined in: packages/math-numbers/src/num/fraction.ts:136


The underlying pair, for callers working at the arithmetic layer.


#### Returns


[`Rational`](../type-aliases/Rational.md)


***


### toString()


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


Defined in: packages/math-numbers/src/num/fraction.ts:171


`p/q`, or just `p` when the denominator is one — exact in any radix.


#### Parameters


##### radix?


`number`


#### Returns


`string`


#### Implementation of


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


***


### valueOf()


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


Defined in: packages/math-numbers/src/num/fraction.ts:221


The nearest binary64 approximation.


#### Returns


`number`


#### Implementation of


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


***


### zero()


> **zero**(): `Fraction`


Defined in: packages/math-numbers/src/num/fraction.ts:271


The additive identity `0/1`.


#### Returns


`Fraction`


***


### from()


> `static` **from**(`numerator`, `denominator?`): `Fraction`


Defined in: packages/math-numbers/src/num/fraction.ts:121


Creates a `Fraction` from a numerator and denominator, accepting `Integer`,
`bigint` or an integral `number` for each.


#### Parameters


##### numerator


`number` \| `bigint` \| [`Integer`](Integer.md)


##### denominator?


`number` \| `bigint` \| [`Integer`](Integer.md)


#### Returns


`Fraction`


#### Throws


When the denominator is zero.


***


### fromRational()


> `static` **fromRational**(`value`): `Fraction`


Defined in: packages/math-numbers/src/num/fraction.ts:131


Wraps an already-normalised [Rational](../type-aliases/Rational.md).


#### Parameters


##### value


[`Rational`](../type-aliases/Rational.md)


#### Returns


`Fraction`