nerdamer 1.1.13 → 2.0.0-rc.1

package/output/core/classes/rational/Rational.d.ts

@@ -0,0 +1,504 @@
+import Decimal from 'decimal.js';
+import { Expression } from '../expression/Expression';
+import { RATIONAL } from '../parser/constants';
+import type { OptionsObject } from '../parser/types';
+/**
+ * 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 {@link Rational.pow}, which uses
+ * `decimal.js` numerical exponentiation. The {@link Rational.asDecimal} flag records
+ * presentation intent only; it does not change the underlying rational representation.
+ *
+ * Values produced by {@link 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
+ * preserving that representation.
+ *
+ * `Rational` instances are mutable because their representation fields are public and
+ * {@link Rational.updateValue} updates the instance in place. The ordinary arithmetic methods
+ * return new values and do not mutate their operands.
+ */
+export declare class Rational {
+    /**
+     * Finite-precision rational approximation of Euler's number at the current configured precision.
+     *
+     * Recomputed when {@link Rational.set} changes the precision.
+     */
+    static E: Rational;
+    /**
+     * Finite-precision rational approximation of pi at the current configured precision.
+     *
+     * Recomputed when {@link Rational.set} changes the precision.
+     */
+    static PI: Rational;
+    /**
+     * Precision setting shared with `decimal.js` and used as the default digit count by
+     * {@link Rational.toDecimalString}. Change it through {@link Rational.set}.
+     */
+    private static precision;
+    /**
+     * 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.
+     */
+    asDecimal: boolean;
+    /** Marker used by Nerdamer's runtime type guards. */
+    dataType: typeof RATIONAL;
+    /** Denominator of the exact rational representation. */
+    denominator: bigint;
+    /** Numerator of the exact rational representation. */
+    numerator: bigint;
+    /**
+     * The supplied textual value.
+     *
+     * Numeric behavior is defined by {@link Rational.numerator} and
+     * {@link Rational.denominator}; callers should not treat this field as an independent
+     * authoritative numeric representation.
+     */
+    value: string;
+    /**
+     * Creates a rational from raw numerator and denominator components.
+     *
+     * @remarks
+     * This constructor performs no normalization or validation. Prefer
+     * {@link Rational.create} for user input and for values that must use Nerdamer's normal
+     * reduced-fraction representation.
+     *
+     * @param a - Numerator to store.
+     * @param b - Denominator to store.
+     */
+    constructor(a: bigint, b: bigint);
+    /**
+     * Tests whether every supplied rational is strictly negative.
+     *
+     * @param args - Rational values to test.
+     * @returns `true` when each value has sign `-1`.
+     */
+    static allNegative(...args: Rational[]): boolean;
+    /**
+     * 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 {@link Rational.asDecimal}, so later text output
+     * normally remains decimal even though the stored arithmetic stays exact.
+     *
+     * @param value - Integer `bigint` or numeric string to convert.
+     * @returns A new normalized `Rational`.
+     *
+     * @throws {@link DivisionByZeroError}
+     * Thrown when a fraction string has a zero denominator.
+     *
+     * @example
+     * ```ts
+     * Rational.create('2/4').text();   // "1/2"
+     * Rational.create('0.125').text(); // "0.125"
+     * Rational.create('4e1').text();   // "40.0"
+     * ```
+     */
+    static create(value: string | bigint): Rational;
+    /**
+     * 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.
+     *
+     * @param args - Rational values whose common divisor should be computed.
+     * @returns The pairwise rational GCD.
+     */
+    static GCD(...args: Rational[]): Rational;
+    /**
+     * Returns the currently configured rational/Decimal precision setting.
+     *
+     * @returns The configured precision value.
+     */
+    static getPrecision(): number;
+    /**
+     * Returns a value unchanged for compatibility with generic numeric hooks.
+     *
+     * @param value - Value to pass through.
+     * @returns The same value reference or primitive supplied by the caller.
+     */
+    static hook(value: string | Rational | bigint): string | bigint | Rational;
+    /**
+     * 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.
+     *
+     * @param value - Value to inspect.
+     * @returns `true` when `value.dataType` is Nerdamer's rational marker.
+     */
+    static isRational(value: unknown): value is Rational;
+    /**
+     * 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.
+     *
+     * @param args - Rational values whose common multiple should be computed.
+     * @returns The pairwise rational LCM.
+     */
+    static LCM(...args: Rational[]): Rational;
+    /**
+     * Copies a rational's representation and presentation metadata.
+     *
+     * @param x - Rational to copy.
+     * @returns A distinct `Rational` with the same numerator, denominator, `value`, and
+     * decimal-presentation flag.
+     */
+    static makeCopy(x: Rational): Rational;
+    /**
+     * 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 {@link Rational.toDecimalString}, and recomputes
+     * {@link Rational.PI} and {@link Rational.E} at the new precision.
+     *
+     * @param values - Settings object; `precision` is the supported numeric setting.
+     */
+    static set(values: {
+        [key: string]: number | boolean;
+    }): void;
+    /**
+     * Converts a string to a rational or normalizes rational ownership for a caller.
+     *
+     * @remarks
+     * Strings always produce a new value through {@link Rational.create}. An existing `Rational`
+     * is returned by identity unless `ensureCopy` is `true`.
+     *
+     * @param x - Numeric string or rational value.
+     * @param ensureCopy - Guarantee a distinct object when `x` is already a `Rational`.
+     * @returns The converted rational, a copy, or the original rational according to `ensureCopy`.
+     */
+    static toRational(x: string | Rational, ensureCopy?: boolean): Rational;
+    /**
+     * Returns the absolute value without modifying this rational.
+     *
+     * @returns A copied rational whose numerator is nonnegative.
+     */
+    abs(): Rational;
+    /**
+     * Creates a distinct copy of this rational.
+     *
+     * @returns A new object with the same numeric representation and presentation metadata.
+     */
+    copy(): Rational;
+    /**
+     * 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 {@link Expression} and preserve operand
+     * direction, returning `this / expression`.
+     *
+     * @param num - Value participating in the division.
+     * @returns A rational result for rational/string input, or an `Expression` for expression input.
+     * @throws {@link DivisionByZeroError}
+     * Thrown when exact rational division requires inversion of zero.
+     */
+    div(num: Expression): Expression;
+    div(num: Rational | string): Rational;
+    /**
+     * 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.
+     *
+     * @param num - Value to compare with this rational.
+     * @returns `true` when the two values compare equal.
+     */
+    eq(num: Expression): boolean;
+    eq(num: Rational | string): boolean;
+    /**
+     * Tests whether the stored denominator is even.
+     *
+     * @returns `true` when {@link Rational.denominator} is divisible by two.
+     */
+    evenDenominator(): boolean;
+    /**
+     * Tests whether the stored numerator is even.
+     *
+     * @returns `true` when {@link Rational.numerator} is divisible by two.
+     */
+    evenNumerator(): boolean;
+    /**
+     * Computes the rational greatest common divisor with another value.
+     *
+     * @param num - Rational or numeric string to combine with this value.
+     * @returns A new reduced rational GCD. Decimal presentation is preserved when either operand
+     * was marked for decimal output.
+     */
+    GCD(num: Rational | string): Rational;
+    /**
+     * 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.
+     *
+     * @param num - Value to compare against.
+     * @returns `true` when this rational is greater than `num`.
+     */
+    gt(num: Expression): boolean;
+    gt(num: Rational | string): boolean;
+    /**
+     * Tests whether this rational is greater than or equal to another rational value.
+     *
+     * @param num - Rational or numeric string to compare against.
+     * @returns `true` when this rational is greater than or equal to `num`.
+     */
+    gte(num: Rational | string): boolean;
+    /**
+     * 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.
+     *
+     * @returns A new rational representing `1 / this`.
+     * @throws {@link DivisionByZeroError}
+     * Thrown when this rational is exactly zero.
+     */
+    invert(): Rational;
+    /**
+     * Tests whether this value is an even integer.
+     *
+     * @returns `true` only when the denominator is one and the numerator is even.
+     */
+    isEven(): boolean;
+    /**
+     * 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 `true` when the stored denominator is one.
+     */
+    isInteger(): boolean;
+    /**
+     * Tests whether this rational is exactly `-1` in normalized integer form.
+     *
+     * @returns `true` for numerator `-1n` and denominator `1n`.
+     */
+    isMinusOne(): boolean;
+    /**
+     * 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 follow that
+     * representation.
+     *
+     * @returns `true` when the numerator is negative.
+     */
+    isNegative(): boolean;
+    /**
+     * Tests whether this rational is exactly `1` in normalized integer form.
+     *
+     * @returns `true` for numerator `1n` and denominator `1n`.
+     */
+    isOne(): boolean;
+    /**
+     * Tests whether this rational is exactly zero.
+     *
+     * @returns `true` when the numerator is zero.
+     */
+    isZero(): boolean;
+    /**
+     * Computes the rational least common multiple with another value.
+     *
+     * @param num - Rational or numeric string to combine with this value.
+     * @returns 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(num: Rational | string): Rational;
+    /**
+     * Tests whether this rational is less than another rational value.
+     *
+     * @param num - Rational or numeric string to compare against.
+     * @returns `true` when this rational is less than `num`.
+     */
+    lt(num: Rational | string): boolean;
+    /**
+     * Tests whether this rational is less than or equal to another rational value.
+     *
+     * @param num - Rational or numeric string to compare against.
+     * @returns `true` when this rational is less than or equal to `num`.
+     */
+    lte(num: Rational | string): boolean;
+    /**
+     * 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 mutated.
+     *
+     * @param num - Value to subtract.
+     * @returns A new `Rational` for rational/string input, or an `Expression` for expression input.
+     */
+    minus(num: Expression): Expression;
+    minus(num: Rational | string): Rational;
+    /**
+     * 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.
+     *
+     * @param num - Nonzero rational or numeric string used as the modulus.
+     * @returns The reduced rational remainder.
+     * @throws A native `RangeError` when `num` is zero.
+     */
+    mod(num: Rational | string): Rational;
+    /**
+     * Returns the additive inverse of this rational.
+     *
+     * @returns A new rational with the numerator sign reversed.
+     */
+    neg(): Rational;
+    /**
+     * 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.
+     *
+     * @param num - Value to add.
+     * @returns A new `Rational` for rational/string input, or an `Expression` for expression input.
+     */
+    plus(num: Expression): Expression;
+    plus(num: Rational | string): Rational;
+    /**
+     * 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.
+     *
+     * @param num - Exponent to apply.
+     * @returns A rational result for rational/string input, or an `Expression` for expression input.
+     * @throws {@link ZeroToZeroPowerError}
+     * Thrown for the indeterminate form `0^0`.
+     * @throws {@link DivisionByZeroError}
+     * Thrown when zero is raised to a negative integer power.
+     */
+    pow(num: Expression): Expression;
+    pow(num: Rational | string): Rational;
+    /**
+     * Returns the sign carried by the numerator.
+     *
+     * @returns `-1` for a negative numerator, `0` for zero, or `1` for a positive numerator.
+     */
+    sign(): number;
+    /**
+     * Formats this rational as fraction, integer, or decimal text.
+     *
+     * @remarks
+     * Decimal formatting is selected when {@link 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.
+     *
+     * @param options - Formatting options. `decimal` forces decimal output and `precision` controls
+     * decimal conversion precision when applicable.
+     * @returns The formatted numeric text.
+     */
+    text(options?: OptionsObject): string;
+    /**
+     * 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.
+     *
+     * @param num - Value to multiply by.
+     * @returns A new `Rational` for rational/string input, or an `Expression` for expression input.
+     */
+    times(num: Expression): Expression;
+    times(num: Rational | string): Rational;
+    /**
+     * Converts the exact fraction to a `decimal.js` value at the current global Decimal precision.
+     *
+     * Integer rationals avoid an unnecessary Decimal division.
+     *
+     * @returns A new Decimal representing `numerator / denominator`.
+     */
+    toDecimal(): Decimal;
+    /**
+     * 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 {@link Rational.asDecimal}; it always requests decimal text.
+     *
+     * @param precision - Number of fractional digits to generate.
+     * @returns Truncated decimal text with unnecessary trailing zeros removed.
+     *
+     * @example
+     * ```ts
+     * Rational.create('1/3').toDecimalString(5); // "0.33333"
+     * Rational.create('7/4').toDecimalString(5); // "1.75"
+     * ```
+     */
+    toDecimalString(precision?: number): string;
+    /**
+     * Returns the same formatted representation as {@link Rational.text}.
+     *
+     * @param options - Formatting options forwarded to `text`.
+     * @returns The formatted rational string.
+     */
+    toString(options?: OptionsObject): string;
+    /**
+     * Refreshes {@link 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 This rational instance.
+     */
+    updateValue(): this;
+    /**
+     * 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 {@link Rational.toDecimal} when native-number limits
+     * are unacceptable.
+     *
+     * @returns The approximate native numeric value.
+     */
+    valueOf(): number;
+}