@juici/math/dist/index.d.ts

A mathematics utility library

/**
 * A big decimal type.
 */
export declare class BigDecimal {
  /**
   * The digits in this BigDecimal.
   */
  readonly digits: bigint;
  /**
   * The scale by which the digits in this BigDecimal are shifted.
   */
  readonly scale: number;
  /**
   * Creates a BigDecimal with the given digits and scale.
   */
  constructor(digits: bigint, scale: number);
  /**
   * Creates a BigDecimal from the given value.
   */
  constructor(n: DecimalValue);
  /**
   * The number of decimal places in this BigDecimal.
   */
  get dp(): number;
  /**
   * The sign of this BigDecimal.
   */
  get sign(): -1 | 0 | 1;
  /**
   * Checks if this BigDecimal is an integer.
   */
  isInt(): boolean;
  /**
   * Checks if this BigDecimal is negative.
   */
  isNeg(): boolean;
  /**
   * Checks if this BigDecimal is positive.
   */
  isPos(): boolean;
  /**
   * Checks if this BigDecimal is 0.
   */
  isZero(): boolean;
  /**
   * Checks if this BigDecimal is 1.
   */
  isOne(): boolean;
  /**
   * Checks for equality of this BigDecimal with the given value.
   */
  eq(other: DecimalValue): boolean;
  /**
   * Returns the the ordering of this BigDecimal and the given value.
   */
  cmp(other: DecimalValue): -1 | 0 | 1;
  /**
   * Checks if this BigDecimal is less than the given value.
   */
  lt(other: DecimalValue): boolean;
  /**
   * Checks if this BigDecimal is less than or equal to the given value.
   */
  le(other: DecimalValue): boolean;
  /**
   * Checks if this BigDecimal is greater than the given value.
   */
  gt(other: DecimalValue): boolean;
  /**
   * Checks if this BigDecimal is greater than or equal to the given value.
   */
  ge(other: DecimalValue): boolean;
  /**
   * Returns the absolute value of this BigDecimal.
   */
  abs(): BigDecimal;
  /**
   * Returns the negation of this BigDecimal.
   */
  neg(): BigDecimal;
  /**
   * Returns the addition of this BigDecimal with the given value.
   */
  add(other: DecimalValue): BigDecimal;
  /**
   * Returns the subtraction of this BigDecimal by the given value.
   */
  sub(other: DecimalValue): BigDecimal;
  /**
   * Returns the multiplication of this BigDecimal with the given value.
   */
  mul(other: DecimalValue): BigDecimal;
  /**
   * Returns the division of this BigDecimal by the given value.
   *
   * The result is rounded if necessary.
   *
   * @param dp The maximum number of decimal places precision, default `20`.
   * @throws {RangeError} If `other` is `0`.
   */
  div(other: DecimalValue, dp?: number): BigDecimal;
  /**
   * Returns the remainder of this BigDecimal divided by the given value.
   *
   * @throws {RangeError} If `other` is `0`.
   */
  rem(other: DecimalValue): BigDecimal;
  /**
   * Returns the division of this BigDecimal by `2`.
   *
   * This function is more efficient than `.div(2)`.
   */
  half(): BigDecimal;
  /**
   * Returns the value of this BigDecimal rounded to the given number of decimal places.
   */
  toDP(dp: number): BigDecimal;
  /**
   * Returns the value of this BigDecimal converted to a primitive number.
   */
  toNumber(): number;
  /**
   * Returns the value of this BigDecimal rounded to a primitive bigint.
   */
  toBigInt(): bigint;
  /**
   * Returns a string representing the value of this BigDecimal.
   */
  toString(): string;
  /**
   * Returns this BigDecimal formatted using fixed-point notation.
   *
   * The result is rounded if necessary, and the fractional component is padded
   * with zeros if necessary so that it has the specified length.
   *
   * @param dp The number of decimal places, default `0`.
   * @throws {RangeError} If `dp` is less than `0`.
   */
  toFixed(dp?: number): string;
  /**
   * Returns this BigDecimal formatted using exponential notation, with one
   * digit before the decimal point.
   *
   * The result is rounded if necessary, and the fractional component is padded
   * with zeros if necessary so that it has the specified length.
   *
   * @param dp The number of decimal places, default to the number of decimal
   *           places required to represent the value uniquely.
   * @throws {RangeError} If `dp` is less than `0`.
   */
  toExponential(dp?: number): string;
  /**
   * Returns a string representing the value of this BigDecimal.
   */
  toJSON(): string;
  /**
   * Returns a string representing the value of this BigDecimal.
   */
  valueOf(): string;
  /**
   * Getter for the string tag used in the `Object.prototype.toString` method.
   */
  get [Symbol.toStringTag](): "BigDecimal";
  /**
   * Converts a BigDecimal into a string.
   */
  [Symbol.toPrimitive](hint: "string"): string;
  /**
   * Converts a BigDecimal into a number.
   */
  [Symbol.toPrimitive](hint: "number" | "default"): number;
}

export declare interface BigDecimalLike {
  readonly digits: bigint;
  readonly scale: number;
}

export declare type DecimalValue = string | number | bigint | BigDecimalLike;

/**
 * An error parsing a decimal from a string.
 */
export declare class ParseDecimalError extends Error {}

export {};