Essential arithmetic operations with arbitrary precision including addition, subtraction, multiplication, division, and modulo operations. All operations return new Decimal instances and preserve immutability.
Add two decimal numbers with full precision.
/**
* Return a new Decimal whose value is the value of this Decimal plus n
* @param n - The value to add
* @returns New Decimal instance with the sum
*/
plus(n: Decimal.Value): Decimal;
add(n: Decimal.Value): Decimal; // Alias for plus
// Static version
static add(x: Decimal.Value, y: Decimal.Value): Decimal;Usage Examples:
import Decimal from "decimal.js";
const a = new Decimal('0.1');
const b = new Decimal('0.2');
const sum = a.plus(b); // '0.3'
// Chaining
const result = new Decimal(100)
.plus(50)
.plus('25.5'); // '175.5'
// Static usage
const total = Decimal.add('123.456', '789.012'); // '912.468'Subtract one decimal number from another with full precision.
/**
* Return a new Decimal whose value is the value of this Decimal minus n
* @param n - The value to subtract
* @returns New Decimal instance with the difference
*/
minus(n: Decimal.Value): Decimal;
sub(n: Decimal.Value): Decimal; // Alias for minus
// Static version
static sub(x: Decimal.Value, y: Decimal.Value): Decimal;Multiply two decimal numbers with full precision.
/**
* Return a new Decimal whose value is the value of this Decimal times n
* @param n - The value to multiply by
* @returns New Decimal instance with the product
*/
times(n: Decimal.Value): Decimal;
mul(n: Decimal.Value): Decimal; // Alias for times
// Static version
static mul(x: Decimal.Value, y: Decimal.Value): Decimal;Usage Examples:
const price = new Decimal('19.99');
const quantity = new Decimal('3');
const total = price.times(quantity); // '59.97'
// High precision multiplication
const precise = new Decimal('1.23456789012345678901234567890')
.times('2.5'); // '3.08641972530864197252308641972250'Divide one decimal number by another with configurable precision.
/**
* Return a new Decimal whose value is the value of this Decimal divided by n
* @param n - The divisor
* @returns New Decimal instance with the quotient
*/
dividedBy(n: Decimal.Value): Decimal;
div(n: Decimal.Value): Decimal; // Alias for dividedBy
// Static version
static div(x: Decimal.Value, y: Decimal.Value): Decimal;Divide and return only the integer part of the result.
/**
* Return a new Decimal whose value is the integer part of dividing this Decimal by n
* @param n - The divisor
* @returns New Decimal instance with the integer quotient
*/
dividedToIntegerBy(n: Decimal.Value): Decimal;
divToInt(n: Decimal.Value): Decimal; // Alias for dividedToIntegerByCalculate the remainder of division with configurable modulo mode.
/**
* Return a new Decimal whose value is the value of this Decimal modulo n
* @param n - The divisor
* @returns New Decimal instance with the remainder
*/
modulo(n: Decimal.Value): Decimal;
mod(n: Decimal.Value): Decimal; // Alias for modulo
// Static version
static mod(x: Decimal.Value, y: Decimal.Value): Decimal;Usage Examples:
const dividend = new Decimal('17');
const divisor = new Decimal('5');
const remainder = dividend.mod(divisor); // '2'
// Decimal modulo
const decimalMod = new Decimal('5.5').mod('2.2'); // '1.1'Return the negative value of a decimal number.
/**
* Return a new Decimal whose value is the negation of the value of this Decimal
* @returns New Decimal instance with negated value
*/
negated(): Decimal;
neg(): Decimal; // Alias for negatedReturn the absolute value of a decimal number.
/**
* Return a new Decimal whose value is the absolute value of this Decimal
* @returns New Decimal instance with absolute value
*/
absoluteValue(): Decimal;
abs(): Decimal; // Alias for absoluteValue
// Static version
static abs(n: Decimal.Value): Decimal;Usage Examples:
const negative = new Decimal('-25.75');
const positive = negative.abs(); // '25.75'
const alreadyPositive = new Decimal('42');
const stillPositive = alreadyPositive.abs(); // '42'
// Static usage
const absolute = Decimal.abs('-123.456'); // '123.456'Round decimal numbers to integers using different rounding modes.
/**
* Return a new Decimal whose value is the value of this Decimal rounded to an integer
* @returns New Decimal instance rounded to integer
*/
round(): Decimal;
/**
* Return a new Decimal whose value is the value of this Decimal rounded up to an integer
* @returns New Decimal instance rounded up
*/
ceil(): Decimal;
/**
* Return a new Decimal whose value is the value of this Decimal rounded down to an integer
* @returns New Decimal instance rounded down
*/
floor(): Decimal;
/**
* Return a new Decimal whose value is the value of this Decimal truncated to an integer
* @returns New Decimal instance truncated to integer
*/
truncated(): Decimal;
trunc(): Decimal; // Alias for truncated
// Static versions
static round(n: Decimal.Value): Decimal;
static ceil(n: Decimal.Value): Decimal;
static floor(n: Decimal.Value): Decimal;
static trunc(n: Decimal.Value): Decimal;Usage Examples:
const value = new Decimal('3.7');
value.floor(); // '3'
value.ceil(); // '4'
value.round(); // '4'
value.trunc(); // '3'
const negative = new Decimal('-3.7');
negative.floor(); // '-4'
negative.ceil(); // '-3'
negative.round(); // '-4'
negative.trunc(); // '-3'Clamp a decimal number to a specified range.
/**
* Return a new Decimal whose value is the value of this Decimal clamped to the range [min, max]
* @param min - The minimum value
* @param max - The maximum value
* @returns New Decimal instance clamped to range
*/
clampedTo(min: Decimal.Value, max: Decimal.Value): Decimal;
clamp(min: Decimal.Value, max: Decimal.Value): Decimal; // Alias for clampedTo
// Static version
static clamp(n: Decimal.Value, min: Decimal.Value, max: Decimal.Value): Decimal;Usage Examples:
const value = new Decimal('15');
const clamped = value.clamp(5, 10); // '10'
const belowMin = new Decimal('2');
const clampedUp = belowMin.clamp(5, 10); // '5'
const inRange = new Decimal('7');
const unchanged = inRange.clamp(5, 10); // '7'