Class

Rational

src/core/classes/rational/Rational.ts:34

Represents an exact rational value as a

`bigint`

numerator and denominator.

remarks

Core rational arithmetic is exact: decimal and scientific-notation input is converted to the exact fraction represented by the input text rather than stored as a floating-point approximation. The notable exception is non-integer Rational.pow, which uses

`decimal.js`

numerical exponentiation. The Rational.asDecimal flag records presentation intent only; it does not change the underlying rational representation. Values produced by Rational.create and the arithmetic methods are normally reduced and use a positive denominator. The public constructor is lower level: it stores its two

`bigint`

arguments exactly as supplied and does not reduce the fraction, normalize the denominator sign, or reject a zero denominator. Sign, comparison, and integer helpers assume the normal representation, so callers constructing values directly are responsible for maintaining those invariants.

`Rational`

instances are mutable because their representation fields are public and Rational.updateValue updates the instance in place. The ordinary arithmetic methods return new values and do not intentionally mutate their operands.

Members

abs(): RationalMethod

Returns the absolute value without modifying this rational.

Returns

Rational — A copied rational whose numerator is nonnegative.

allNegative(...args: Rational[]): booleanMethod

Tests whether every supplied rational is strictly negative.

Parameters

Name	Type	Description
`args`	`Rational[]`	Rational values to test.

Returns

boolean — `true` when each value has sign `-1`.

asDecimal: booleanProperty

Whether text output should preserve decimal presentation by default. This flag does not change the exact numerator/denominator representation. Most rational arithmetic propagates decimal intent when either operand has it set.

Rational(a: bigint, b: bigint): RationalConstructor

Creates a rational from raw numerator and denominator components.

remarks

This constructor performs no normalization or validation. Prefer Rational.create for user input and for values that must satisfy Nerdamer's normal reduced-fraction invariants.

Parameters

Name	Type	Description
`a`	`bigint`	Numerator to store.
`b`	`bigint`	Denominator to store.

Returns

Rational

copy(): RationalMethod

Creates a distinct copy of this rational.

Returns

Rational — A new object with the same numeric representation and presentation metadata.

create(value: string | bigint): RationalMethod

Creates a normalized rational from an integer, fraction, decimal, or scientific-notation value.

remarks

Fraction strings are reduced and a negative denominator is moved to the numerator. Decimal and scientific-notation strings are converted to the exact rational represented by their finite decimal text. Those forms also set Rational.asDecimal, so later text output normally remains decimal even though the stored arithmetic stays exact.

throws

DivisionByZeroError Thrown when a fraction string has a zero denominator.

Parameters

Name	Type	Description
`value`	`string \| bigint`	Integer `bigint` or numeric string to convert.

Returns

Rational — A new normalized `Rational`.

Examples

Rational.create('2/4').text();   // "1/2"
Rational.create('0.125').text(); // "0.125"
Rational.create('4e1').text();   // "40.0"

dataType: "RAT"Property

Marker used by Nerdamer's runtime type guards.

denominator: bigintProperty

Denominator of the exact rational representation.

div(num: Expression): ExpressionMethod

Divides using Nerdamer's rational or expression arithmetic overloads.

remarks

`Rational`

and string operands compute exact rational division and return a new

`Rational`

. Expression operands promote this rational to an Expression and preserve operand direction, returning

`this / expression`

throws

DivisionByZeroError Thrown when exact rational division requires inversion of zero.

Parameters

Name	Type	Description
`num`	`Expression`	Value participating in the division.

Returns

Expression — A rational result for rational/string input, or an `Expression` for expression input.

E: RationalProperty

Finite-precision rational approximation of Euler's number at the current configured precision. Recomputed when Rational.set changes the precision.

eq(num: Expression): booleanMethod

Compares this rational with another value for mathematical equality.

remarks

Rational/string comparisons are exact and use cross multiplication, so decimal-presentation metadata does not affect equality. Expression input delegates to Nerdamer's symbolic comparison semantics.

Parameters

Name	Type	Description
`num`	`Expression`	Value to compare with this rational.

Returns

boolean — `true` when the two values compare equal.

evenDenominator(): booleanMethod

Tests whether the stored denominator is even.

Returns

boolean — `true` when Rational.denominator is divisible by two.

evenNumerator(): booleanMethod

Tests whether the stored numerator is even.

Returns

boolean — `true` when Rational.numerator is divisible by two.

GCD(num: string | Rational): RationalMethod

Computes the rational greatest common divisor with another value.

Parameters

Name	Type	Description
`num`	`string \| Rational`	Rational or numeric string to combine with this value.

Returns

Rational — A new reduced rational GCD. Decimal presentation is preserved when either operand was marked for decimal output.

GCD(...args: Rational[]): RationalMethod

Computes the rational greatest common divisor across the supplied values.

remarks

The operation is folded pairwise and preserves decimal presentation intent when it is present on an operand.

Parameters

Name	Type	Description
`args`	`Rational[]`	Rational values whose common divisor should be computed.

Returns

Rational — The pairwise rational GCD.

getPrecision(): numberMethod

Returns the currently configured rational/Decimal precision setting.

Returns

number — The configured precision value.

gt(num: Expression): booleanMethod

Tests whether this rational is greater than another value.

remarks

Rational/string comparisons are exact. Expression input delegates to Nerdamer's symbolic ordering rules, including their restrictions on unordered complex values.

Parameters

Name	Type	Description
`num`	`Expression`	Value to compare against.

Returns

boolean — `true` when this rational is greater than `num`.

gte(num: string | Rational): booleanMethod

Tests whether this rational is greater than or equal to another rational value.

Parameters

Name	Type	Description
`num`	`string \| Rational`	Rational or numeric string to compare against.

Returns

boolean — `true` when this rational is greater than or equal to `num`.

hook(value: string | bigint | Rational): string | bigint | RationalMethod

Returns a value unchanged for compatibility with generic numeric hooks.

Parameters

Name	Type	Description
`value`	`string \| bigint \| Rational`	Value to pass through.

Returns

string | bigint | Rational — The same value reference or primitive supplied by the caller.

invert(): RationalMethod

Returns the multiplicative inverse of this rational.

remarks

The original object is not modified. For normally constructed rationals, the returned denominator remains positive and the sign is carried by the numerator.

throws

DivisionByZeroError Thrown when this rational is exactly zero.

Returns

Rational — A new rational representing `1 / this`.

isEven(): booleanMethod

Tests whether this value is an even integer.

Returns

boolean — `true` only when the denominator is one and the numerator is even.

isInteger(): booleanMethod

Tests whether this rational is stored in integer form.

remarks

This checks only whether the denominator is exactly

`1n`

. Values built with the raw constructor must therefore be reduced first if equivalent forms such as

`8/4`

should be recognized as integers.

Returns

boolean — `true` when the stored denominator is one.

isMinusOne(): booleanMethod

Tests whether this rational is exactly

`-1`

in normalized integer form.

Returns

boolean — `true` for numerator `-1n` and denominator `1n`.

isNegative(): booleanMethod

Tests whether the stored numerator is negative.

remarks

Nerdamer's normal rational representation keeps the denominator positive, so the numerator carries the sign. Raw constructor values with a negative denominator do not satisfy that invariant.

Returns

boolean — `true` when the numerator is negative.

isOne(): booleanMethod

Tests whether this rational is exactly

`1`

in normalized integer form.

Returns

boolean — `true` for numerator `1n` and denominator `1n`.

isRational(value: unknown): valueMethod

Tests whether a value carries Nerdamer's rational runtime type marker.

remarks

This is a marker-based guard rather than an

`instanceof`

check, which allows compatible Nerdamer rational objects to be recognized where constructor identity is not the useful distinction.

Parameters

Name	Type	Description
`value`	`unknown`	Value to inspect.

Returns

value — `true` when `value.dataType` is Nerdamer's rational marker.

isZero(): booleanMethod

Tests whether this rational is exactly zero.

Returns

boolean — `true` when the numerator is zero.

LCM(num: string | Rational): RationalMethod

Computes the rational least common multiple with another value.

Parameters

Name	Type	Description
`num`	`string \| Rational`	Rational or numeric string to combine with this value.

Returns

Rational — A new reduced, nonnegative rational LCM. Zero combined with any rational returns zero. Decimal presentation is preserved when either operand was marked for decimal output.

LCM(...args: Rational[]): RationalMethod

Computes the rational least common multiple across the supplied values.

remarks

The operation is folded pairwise and preserves decimal presentation intent when it is present on an operand.

Parameters

Name	Type	Description
`args`	`Rational[]`	Rational values whose common multiple should be computed.

Returns

Rational — The pairwise rational LCM.

lt(num: string | Rational): booleanMethod

Tests whether this rational is less than another rational value.

Parameters

Name	Type	Description
`num`	`string \| Rational`	Rational or numeric string to compare against.

Returns

boolean — `true` when this rational is less than `num`.

lte(num: string | Rational): booleanMethod

Tests whether this rational is less than or equal to another rational value.

Parameters

Name	Type	Description
`num`	`string \| Rational`	Rational or numeric string to compare against.

Returns

boolean — `true` when this rational is less than or equal to `num`.

makeCopy(x: Rational): RationalMethod

Copies a rational's representation and presentation metadata.

Parameters

Name	Type	Description
`x`	`Rational`	Rational to copy.

Returns

Rational — A distinct `Rational` with the same numerator, denominator, `value`, and decimal-presentation flag.

minus(num: Expression): ExpressionMethod

Subtracts another rational or expression from this value.

remarks

Rational/string input is handled with exact rational arithmetic. Expression input is promoted to Nerdamer's symbolic arithmetic. The original operands are not intentionally mutated.

Parameters

Name	Type	Description
`num`	`Expression`	Value to subtract.

Returns

Expression — A new `Rational` for rational/string input, or an `Expression` for expression input.

mod(num: string | Rational): RationalMethod

Computes the exact rational modulo with another value.

remarks

The operands are converted to a common denominator, Nerdamer's integer modulo operation is applied to the corresponding numerators, and the resulting fraction is reduced. Decimal presentation is preserved when either operand was marked for decimal output.

throws

A native

`RangeError`

when

`num`

is zero.

Parameters

Name	Type	Description
`num`	`string \| Rational`	Nonzero rational or numeric string used as the modulus.

Returns

Rational — The reduced rational remainder.

neg(): RationalMethod

Returns the additive inverse of this rational.

Returns

Rational — A new rational with the numerator sign reversed.

numerator: bigintProperty

Numerator of the exact rational representation.

PI: RationalProperty

Finite-precision rational approximation of pi at the current configured precision. Recomputed when Rational.set changes the precision.

plus(num: Expression): ExpressionMethod

Adds another rational or expression to this value.

remarks

Rational/string input is added exactly and reduced. If either rational operand carries decimal presentation intent, the rational result carries it as well. Expression input is promoted to Nerdamer's symbolic arithmetic.

Parameters

Name	Type	Description
`num`	`Expression`	Value to add.

Returns

Expression — A new `Rational` for rational/string input, or an `Expression` for expression input.

pow(num: Expression): ExpressionMethod

Raises this rational to a rational or symbolic power.

remarks

Expression exponents use Nerdamer's general symbolic power logic. Integer rational exponents use exact

`bigint`

exponentiation, with negative exponents handled by first inverting the base. Non-integer rational exponents are evaluated through

`decimal.js`

and converted back to a

`Rational`

, so that overload is a real numerical approximation rather than symbolic radical or principal-complex evaluation. Decimal presentation from a numerical result is retained, while an exact integer result stays exact unless the base already carried decimal presentation intent.

throws

ZeroToZeroPowerError Thrown for the indeterminate form

`0^0`

throws

DivisionByZeroError Thrown when zero is raised to a negative integer power.

Parameters

Name	Type	Description
`num`	`Expression`	Exponent to apply.

Returns

Expression — A rational result for rational/string input, or an `Expression` for expression input.

set(values: { … }): voidMethod

Updates shared numeric settings used by rational decimal conversion.

remarks

Currently only

`precision`

is acted upon. Setting it updates the global

`decimal.js`

precision, records the value used by Rational.toDecimalString, and recomputes Rational.PI and Rational.E at the new precision.

Parameters

Name	Type	Description
`values`	`{ … }`	Settings object; `precision` is the supported numeric setting.

Returns

void

sign(): numberMethod

Returns the sign carried by the numerator.

Returns

number — `-1` for a negative numerator, `0` for zero, or `1` for a positive numerator.

text(options?: OptionsObject): stringMethod

Formats this rational as fraction, integer, or decimal text.

remarks

Decimal formatting is selected when Rational.asDecimal is set or when

`options.decimal`

is truthy. Non-integer decimal output uses

`decimal.js`

; an optional

`options.precision`

temporarily controls its significant-digit precision for this conversion. Integer decimal output includes a

`.0`

suffix. Without decimal formatting, non-integer fractions are emitted from the stored numerator and denominator, and integers as plain text.

Parameters

Name	Type	Description
`options`	`OptionsObject`	Formatting options. `decimal` forces decimal output and `precision` controls decimal conversion precision when applicable.

Returns

string — The formatted numeric text.

times(num: Expression): ExpressionMethod

Multiplies this rational by another rational or expression.

remarks

Rational/string multiplication is exact and reduced. If either rational operand carries decimal presentation intent, the rational result carries it as well. Expression input is promoted to Nerdamer's symbolic arithmetic.

Parameters

Name	Type	Description
`num`	`Expression`	Value to multiply by.

Returns

Expression — A new `Rational` for rational/string input, or an `Expression` for expression input.

toDecimal(): DecimalMethod

Converts the exact fraction to a

`decimal.js`

value at the current global Decimal precision. Integer rationals avoid an unnecessary Decimal division.

Returns

Decimal — A new Decimal representing `numerator / denominator`.

toDecimalString(precision?: number): stringMethod

Converts the exact fraction to decimal text using integer arithmetic.

remarks

`precision`

is the maximum number of digits generated after the decimal point. The conversion truncates at that position rather than rounding, then removes trailing zeros and a trailing decimal point. When omitted, the configured Rational precision is used. This method does not depend on Rational.asDecimal; it always requests decimal text.

Parameters

Name	Type	Description
`precision`	`number`	Number of fractional digits to generate.

Returns

string — Truncated decimal text with unnecessary trailing zeros removed.

Examples

Rational.create('1/3').toDecimalString(5); // "0.33333"
Rational.create('7/4').toDecimalString(5); // "1.75"

toRational(x: string | Rational, ensureCopy: boolean): RationalMethod

Converts a string to a rational or normalizes rational ownership for a caller.

remarks

Strings always produce a new value through Rational.create. An existing

`Rational`

is returned by identity unless

`ensureCopy`

`true`

Parameters

Name	Type	Description
`x`	`string \| Rational`	Numeric string or rational value.
`ensureCopy`	`boolean`	Guarantee a distinct object when `x` is already a `Rational`.

Returns

Rational — The converted rational, a copy, or the original rational according to `ensureCopy`.

toString(options?: OptionsObject): stringMethod

Returns the same formatted representation as Rational.text.

Parameters

Name	Type	Description
`options`	`OptionsObject`	Formatting options forwarded to `text`.

Returns

string — The formatted rational string.

updateValue(): RationalMethod

Refreshes Rational.value from the current numerator and denominator.

remarks

This is one of the few mutating methods on

`Rational`

; it updates this object and returns the same reference.

Returns

Rational — This rational instance.

value: stringProperty

Auxiliary textual value retained by Nerdamer internals. Numeric behavior is defined by Rational.numerator and Rational.denominator; callers should not treat this field as an independent authoritative numeric representation.

valueOf(): numberMethod

Converts this rational to a native JavaScript number.

remarks

This conversion is approximate and subject to the range and precision limits of JavaScript

`number`

. Numerator and denominator values that are both safe integers use native division directly; larger values retain the Decimal-backed fallback so finite ratios are not lost merely because an individual component exceeds the native numeric range. Use the rational representation or Rational.toDecimal when native-number limits are unacceptable.

Returns

number — The approximate native numeric value.