Advanced mathematical functions including roots, exponentials, logarithms, and power operations with configurable precision. All functions handle arbitrary precision calculations and support both instance and static method calls.
Calculate the square root of a decimal number.
/**
* Return a new Decimal whose value is the square root of this Decimal
* @returns New Decimal instance with the square root
*/
squareRoot(): Decimal;
sqrt(): Decimal; // Alias for squareRoot
// Static version
static sqrt(n: Decimal.Value): Decimal;Usage Examples:
import Decimal from "decimal.js";
const value = new Decimal('16');
const root = value.sqrt(); // '4'
// High precision square root
const precise = new Decimal('2').sqrt(); // '1.4142135623730950488'
// Static usage
const staticRoot = Decimal.sqrt('25'); // '5'Calculate the cube root of a decimal number.
/**
* Return a new Decimal whose value is the cube root of this Decimal
* @returns New Decimal instance with the cube root
*/
cubeRoot(): Decimal;
cbrt(): Decimal; // Alias for cubeRoot
// Static version
static cbrt(n: Decimal.Value): Decimal;Usage Examples:
const value = new Decimal('27');
const cubeRoot = value.cbrt(); // '3'
const negative = new Decimal('-8');
const negativeRoot = negative.cbrt(); // '-2'Raise a decimal number to a power.
/**
* Return a new Decimal whose value is the value of this Decimal raised to the power n
* @param n - The exponent
* @returns New Decimal instance with the result
*/
toPower(n: Decimal.Value): Decimal;
pow(n: Decimal.Value): Decimal; // Alias for toPower
// Static version
static pow(base: Decimal.Value, exponent: Decimal.Value): Decimal;Usage Examples:
const base = new Decimal('2');
const power = base.pow('3'); // '8'
// Fractional exponents
const fractional = new Decimal('4').pow('0.5'); // '2' (same as sqrt)
// Negative exponents
const negative = new Decimal('2').pow('-3'); // '0.125'
// Static usage
const result = Decimal.pow('3', '4'); // '81'Calculate e raised to the power of the decimal number.
/**
* Return a new Decimal whose value is the exponential of this Decimal (e^x)
* @returns New Decimal instance with e^x
*/
naturalExponential(): Decimal;
exp(): Decimal; // Alias for naturalExponential
// Static version
static exp(n: Decimal.Value): Decimal;Usage Examples:
const value = new Decimal('1');
const e = value.exp(); // '2.7182818284590452354' (e^1)
const zero = new Decimal('0');
const one = zero.exp(); // '1' (e^0)
// Static usage
const expTwo = Decimal.exp('2'); // '7.3890560989306502272'Calculate the natural logarithm (base e) of a decimal number.
/**
* Return a new Decimal whose value is the natural logarithm of this Decimal
* @returns New Decimal instance with ln(x)
*/
naturalLogarithm(): Decimal;
ln(): Decimal; // Alias for naturalLogarithm
// Static version
static ln(n: Decimal.Value): Decimal;Calculate the logarithm of a decimal number with optional base.
/**
* Return a new Decimal whose value is the logarithm of this Decimal to the specified base
* @param base - The logarithm base (defaults to 10)
* @returns New Decimal instance with the logarithm
*/
logarithm(base?: Decimal.Value): Decimal;
log(base?: Decimal.Value): Decimal; // Alias for logarithm
// Static version
static log(n: Decimal.Value, base?: Decimal.Value): Decimal;Usage Examples:
const value = new Decimal('100');
const log10 = value.log(); // '2' (log base 10)
const log2 = value.log('2'); // '6.6438561897747246957' (log base 2)
const e = new Decimal('2.718281828459045');
const natural = e.ln(); // '1' (approximately)
// Static usage
const logResult = Decimal.log('1000', '10'); // '3'Calculate logarithms with common bases.
/**
* Return a new Decimal whose value is the base 2 logarithm of n
* @param n - The value
* @returns New Decimal instance with log2(n)
*/
static log2(n: Decimal.Value): Decimal;
/**
* Return a new Decimal whose value is the base 10 logarithm of n
* @param n - The value
* @returns New Decimal instance with log10(n)
*/
static log10(n: Decimal.Value): Decimal;Usage Examples:
const log2Result = Decimal.log2('8'); // '3'
const log10Result = Decimal.log10('1000'); // '3'Mathematical operations on multiple values.
/**
* 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 a new Decimal whose value is the sum of the arguments
* @param args - Values to sum
* @returns New Decimal instance with the sum
*/
static sum(...n: Decimal.Value[]): Decimal;
/**
* Return a new Decimal whose value is the square root of the sum of squares (Euclidean norm)
* @param args - Values for the calculation
* @returns New Decimal instance with sqrt(sum of squares)
*/
static hypot(...n: Decimal.Value[]): Decimal;Usage Examples:
const maximum = Decimal.max('3.5', '2.8', '4.1', '1.9'); // '4.1'
const minimum = Decimal.min('3.5', '2.8', '4.1', '1.9'); // '1.9'
const total = Decimal.sum('10', '20', '30'); // '60'
// Euclidean distance in 2D
const distance = Decimal.hypot('3', '4'); // '5'
// Euclidean distance in 3D
const distance3D = Decimal.hypot('1', '2', '2'); // '3'Get the sign of a value.
/**
* Return the sign of n: 1 if positive, -1 if negative, 0 if zero, NaN if NaN
* @param n - The value to check
* @returns The sign as a number
*/
static sign(n: Decimal.Value): number;Usage Examples:
const positiveSign = Decimal.sign('5.5'); // 1
const negativeSign = Decimal.sign('-3.2'); // -1
const zeroSign = Decimal.sign('0'); // 0
const nanSign = Decimal.sign(NaN); // NaNGenerate random decimal numbers with configurable precision.
/**
* Return a new Decimal with a random value >= 0 and < 1
* @param significantDigits - Number of significant digits (defaults to current precision)
* @returns New Decimal instance with random value
*/
static random(significantDigits?: number): Decimal;Usage Examples:
// Random number with default precision
const random1 = Decimal.random(); // e.g., '0.12345678901234567890'
// Random number with specific precision
const random2 = Decimal.random(5); // e.g., '0.67890'
// Generate random number in range [min, max]
const min = new Decimal('10');
const max = new Decimal('20');
const randomInRange = Decimal.random()
.times(max.minus(min))
.plus(min); // Random number between 10 and 20