Comparison and Utility Methods

/**
 * Return 1 if the value of this Decimal is greater than n, -1 if less than n, or 0 if equal
 * @param n - The value to compare against
 * @returns 1, 0, or -1 indicating comparison result
 */
comparedTo(n: Decimal.Value): number;
cmp(n: Decimal.Value): number; // Alias for comparedTo

/**
 * Return true if the value of this Decimal equals n, otherwise false
 * @param n - The value to compare against
 * @returns Boolean indicating equality
 */
equals(n: Decimal.Value): boolean;
eq(n: Decimal.Value): boolean; // Alias for equals

/**
 * Return true if the value of this Decimal is greater than n, otherwise false
 * @param n - The value to compare against
 * @returns Boolean indicating if this is greater
 */
greaterThan(n: Decimal.Value): boolean;
gt(n: Decimal.Value): boolean; // Alias for greaterThan

/**
 * Return true if the value of this Decimal is greater than or equal to n, otherwise false
 * @param n - The value to compare against
 * @returns Boolean indicating if this is greater than or equal
 */
greaterThanOrEqualTo(n: Decimal.Value): boolean;
gte(n: Decimal.Value): boolean; // Alias for greaterThanOrEqualTo

/**
 * Return true if the value of this Decimal is less than n, otherwise false
 * @param n - The value to compare against
 * @returns Boolean indicating if this is less
 */
lessThan(n: Decimal.Value): boolean;
lt(n: Decimal.Value): boolean; // Alias for lessThan

/**
 * Return true if the value of this Decimal is less than or equal to n, otherwise false
 * @param n - The value to compare against
 * @returns Boolean indicating if this is less than or equal
 */
lessThanOrEqualTo(n: Decimal.Value): boolean;
lte(n: Decimal.Value): boolean; // Alias for lessThanOrEqualTo

import Decimal from "decimal.js";

const a = new Decimal('10.5');
const b = new Decimal('5.25');
const c = new Decimal('10.5');

// Comparison operations
a.comparedTo(b);    // 1 (a > b)
b.comparedTo(a);    // -1 (b < a)
a.comparedTo(c);    // 0 (a == c)

// Boolean comparisons
a.equals(c);        // true
a.gt(b);           // true
b.lt(a);           // true
a.gte(c);          // true
a.lte(c);          // true

// Precision-safe comparison (no floating-point errors)
const precise1 = new Decimal('0.1').plus('0.2');
const precise2 = new Decimal('0.3');
precise1.equals(precise2);  // true (would be false with regular JavaScript numbers)

/**
 * Return true if the value of this Decimal is a finite number, otherwise false
 * @returns Boolean indicating if value is finite
 */
isFinite(): boolean;

/**
 * Return true if the value of this Decimal is an integer, otherwise false
 * @returns Boolean indicating if value is an integer
 */
isInteger(): boolean;
isInt(): boolean; // Alias for isInteger

/**
 * Return true if the value of this Decimal is NaN, otherwise false
 * @returns Boolean indicating if value is NaN
 */
isNaN(): boolean;

/**
 * Return true if the value of this Decimal is negative, otherwise false
 * @returns Boolean indicating if value is negative
 */
isNegative(): boolean;
isNeg(): boolean; // Alias for isNegative

/**
 * Return true if the value of this Decimal is positive, otherwise false
 * @returns Boolean indicating if value is positive
 */
isPositive(): boolean;
isPos(): boolean; // Alias for isPositive

/**
 * Return true if the value of this Decimal is zero, otherwise false
 * @returns Boolean indicating if value is zero
 */
isZero(): boolean;

// Type checking examples
const integer = new Decimal('42');
const decimal = new Decimal('42.5');
const zero = new Decimal('0');
const negative = new Decimal('-10');
const infinity = new Decimal(Infinity);
const nan = new Decimal(NaN);

integer.isInteger();    // true
decimal.isInteger();    // false

zero.isZero();         // true
negative.isZero();     // false

negative.isNegative(); // true
negative.isPositive(); // false

integer.isPositive();  // true
zero.isPositive();     // false (zero is neither positive nor negative)

infinity.isFinite();   // false
integer.isFinite();    // true

nan.isNaN();          // true
integer.isNaN();      // false

/**
 * Return a new Decimal whose value is the maximum of the arguments
 * @param args - Values to compare
 * @returns New Decimal instance with the maximum value
 */
static max(...n: Decimal.Value[]): Decimal;

/**
 * Return a new Decimal whose value is the minimum of the arguments
 * @param args - Values to compare
 * @returns New Decimal instance with the minimum value
 */
static min(...n: Decimal.Value[]): Decimal;

/**
 * Return true if object is a Decimal instance, otherwise false
 * @param obj - Object to test
 * @returns Boolean indicating if object is a Decimal instance
 */
static isDecimal(obj: any): obj is Decimal;

// Find maximum and minimum values
const values = ['3.14', '2.71', '1.41', '4.47'];
const maximum = Decimal.max(...values);       // '4.47'
const minimum = Decimal.min(...values);       // '1.41'

// Mixed value types
const mixed = Decimal.max('10', 25, new Decimal('15.5')); // '25'

// Type checking
const decimal = new Decimal('123');
const number = 123;
const string = '123';

Decimal.isDecimal(decimal);   // true
Decimal.isDecimal(number);    // false
Decimal.isDecimal(string);    // false

/**
 * Return the number of significant digits of this Decimal
 * @param includeZeros - Whether to include trailing zeros in the count
 * @returns Number of significant digits
 */
precision(includeZeros?: boolean): number;
sd(includeZeros?: boolean): number; // Alias for precision

/**
 * Return the number of decimal places of this Decimal
 * @returns Number of decimal places
 */
decimalPlaces(): number;
dp(): number; // Alias for decimalPlaces

const value1 = new Decimal('123.4500');
const value2 = new Decimal('0.00123');
const integer = new Decimal('42000');

// Precision (significant digits)
value1.precision();         // 7 (includes trailing zeros)
value1.precision(false);    // 5 (excludes trailing zeros)
value2.precision();         // 3
integer.precision();        // 5

// Decimal places
value1.decimalPlaces();     // 4
value2.decimalPlaces();     // 5
integer.decimalPlaces();    // 0

/**
 * Return a new Decimal whose value is this Decimal rounded to dp decimal places
 * @param decimalPlaces - Number of decimal places (optional)
 * @returns New Decimal instance rounded to decimal places
 */
toDecimalPlaces(decimalPlaces?: number): Decimal;
/**
 * Return a new Decimal whose value is this Decimal rounded to dp decimal places
 * @param decimalPlaces - Number of decimal places
 * @param rounding - Rounding mode
 * @returns New Decimal instance rounded to decimal places
 */
toDecimalPlaces(decimalPlaces: number, rounding: Decimal.Rounding): Decimal;
/**
 * Alias for toDecimalPlaces - Return a new Decimal rounded to dp decimal places
 * @param decimalPlaces - Number of decimal places (optional)
 * @returns New Decimal instance rounded to decimal places
 */
toDP(decimalPlaces?: number): Decimal;
/**
 * Alias for toDecimalPlaces - Return a new Decimal rounded to dp decimal places
 * @param decimalPlaces - Number of decimal places
 * @param rounding - Rounding mode
 * @returns New Decimal instance rounded to decimal places
 */
toDP(decimalPlaces: number, rounding: Decimal.Rounding): Decimal;

/**
 * Return a new Decimal whose value is this Decimal rounded to sd significant digits
 * @param significantDigits - Number of significant digits (optional)
 * @returns New Decimal instance rounded to significant digits
 */
toSignificantDigits(significantDigits?: number): Decimal;
/**
 * Return a new Decimal whose value is this Decimal rounded to sd significant digits
 * @param significantDigits - Number of significant digits
 * @param rounding - Rounding mode
 * @returns New Decimal instance rounded to significant digits
 */
toSignificantDigits(significantDigits: number, rounding: Decimal.Rounding): Decimal;
/**
 * Alias for toSignificantDigits - Return a new Decimal rounded to sd significant digits
 * @param significantDigits - Number of significant digits (optional)
 * @returns New Decimal instance rounded to significant digits
 */
toSD(significantDigits?: number): Decimal;
/**
 * Alias for toSignificantDigits - Return a new Decimal rounded to sd significant digits
 * @param significantDigits - Number of significant digits
 * @param rounding - Rounding mode
 * @returns New Decimal instance rounded to significant digits
 */
toSD(significantDigits: number, rounding: Decimal.Rounding): Decimal;

/**
 * Return a new Decimal whose value is this Decimal rounded to the nearest multiple of n
 * @param n - The value to round to nearest multiple of
 * @param rm - Rounding mode (optional)
 * @returns New Decimal instance rounded to nearest multiple
 */
toNearest(n: Decimal.Value, rm?: Decimal.Rounding): Decimal;

const value = new Decimal('123.456789');

// Round to decimal places
value.toDecimalPlaces(2);           // '123.46'
value.toDP(0);                      // '123'

// Round to significant digits  
value.toSignificantDigits(4);       // '123.5'
value.toSD(2);                      // '120'

// Round to nearest multiple
const price = new Decimal('123.47');
price.toNearest('0.05');            // '123.45' (nearest nickel)
price.toNearest('0.25');            // '123.50' (nearest quarter)

// Using specific rounding modes
value.toDP(2, Decimal.ROUND_UP);    // '123.46'
value.toDP(2, Decimal.ROUND_DOWN);  // '123.45'