Comprehensive formatting and conversion methods for different number representations and output formats. Convert Decimal values to strings, numbers, fractions, and various base representations with precise control over formatting.
Convert Decimal values to string representations with various formatting options.
/**
* Return a string representing the value of this Decimal
* @returns String representation of the decimal value
*/
toString(): string;
/**
* Return a string representing the value of this Decimal in fixed-point notation
* @param decimalPlaces - Number of decimal places (optional)
* @returns String in fixed-point notation
*/
toFixed(decimalPlaces?: number): string;
/**
* Return a string representing the value of this Decimal in fixed-point notation
* @param decimalPlaces - Number of decimal places
* @param rounding - Rounding mode
* @returns String in fixed-point notation
*/
toFixed(decimalPlaces: number, rounding: Decimal.Rounding): string;
/**
* Return a string representing the value of this Decimal in exponential notation
* @param decimalPlaces - Number of decimal places (optional)
* @returns String in exponential notation
*/
toExponential(decimalPlaces?: number): string;
/**
* Return a string representing the value of this Decimal in exponential notation
* @param decimalPlaces - Number of decimal places
* @param rounding - Rounding mode
* @returns String in exponential notation
*/
toExponential(decimalPlaces: number, rounding: Decimal.Rounding): string;
/**
* Return a string representing the value of this Decimal with specified precision
* @param significantDigits - Number of significant digits (optional)
* @returns String with specified precision
*/
toPrecision(significantDigits?: number): string;
/**
* Return a string representing the value of this Decimal with specified precision
* @param significantDigits - Number of significant digits
* @param rounding - Rounding mode
* @returns String with specified precision
*/
toPrecision(significantDigits: number, rounding: Decimal.Rounding): string;
/**
* Return a string value (same as toString)
* @returns String representation of the decimal value
*/
valueOf(): string;
/**
* Return a JSON representation (same as toString)
* @returns JSON string representation
*/
toJSON(): string;Usage Examples:
import Decimal from "decimal.js";
const value = new Decimal('123.456789');
// Basic string conversion
value.toString(); // '123.456789'
value.valueOf(); // '123.456789'
value.toJSON(); // '123.456789'
// Fixed-point notation
value.toFixed(); // '123'
value.toFixed(2); // '123.46'
value.toFixed(0); // '123'
// Exponential notation
value.toExponential(); // '1.23456789e+2'
value.toExponential(2); // '1.23e+2'
value.toExponential(5); // '1.23457e+2'
// Precision notation
value.toPrecision(); // '123.456789'
value.toPrecision(4); // '123.5'
value.toPrecision(2); // '1.2e+2'
// Very small numbers show exponential notation automatically
const small = new Decimal('0.0000001');
small.toString(); // '1e-7'
small.toFixed(); // '0.0000001'Convert Decimal values to different number base representations.
/**
* Return a string representing the value of this Decimal in binary (base 2)
* @param significantDigits - Number of significant digits (optional)
* @returns String in binary representation
*/
toBinary(significantDigits?: number): string;
/**
* Return a string representing the value of this Decimal in binary (base 2)
* @param significantDigits - Number of significant digits
* @param rounding - Rounding mode
* @returns String in binary representation
*/
toBinary(significantDigits: number, rounding: Decimal.Rounding): string;
/**
* Return a string representing the value of this Decimal in hexadecimal (base 16)
* @param significantDigits - Number of significant digits (optional)
* @returns String in hexadecimal representation
*/
toHexadecimal(significantDigits?: number): string;
/**
* Return a string representing the value of this Decimal in hexadecimal (base 16)
* @param significantDigits - Number of significant digits
* @param rounding - Rounding mode
* @returns String in hexadecimal representation
*/
toHexadecimal(significantDigits: number, rounding: Decimal.Rounding): string;
/**
* Return a string representing the value of this Decimal in hexadecimal (base 16) - alias for toHexadecimal
* @param significantDigits - Number of significant digits (optional)
* @returns String in hexadecimal representation
*/
toHex(significantDigits?: number): string;
/**
* Return a string representing the value of this Decimal in hexadecimal (base 16) - alias for toHexadecimal
* @param significantDigits - Number of significant digits
* @param rounding - Rounding mode (optional)
* @returns String in hexadecimal representation
*/
toHex(significantDigits: number, rounding?: Decimal.Rounding): string;
/**
* Return a string representing the value of this Decimal in octal (base 8)
* @param significantDigits - Number of significant digits (optional)
* @returns String in octal representation
*/
toOctal(significantDigits?: number): string;
/**
* Return a string representing the value of this Decimal in octal (base 8)
* @param significantDigits - Number of significant digits
* @param rounding - Rounding mode
* @returns String in octal representation
*/
toOctal(significantDigits: number, rounding: Decimal.Rounding): string;Usage Examples:
const decimal = new Decimal('255');
const fractional = new Decimal('255.9375');
// Binary conversion
decimal.toBinary(); // '0b11111111'
fractional.toBinary(); // '0b11111111.1111'
fractional.toBinary(10); // '0b1.111111111p+7' (scientific notation)
// Hexadecimal conversion
decimal.toHexadecimal(); // '0xff'
decimal.toHex(); // '0xff' (alias)
fractional.toHex(); // '0xff.f'
// Octal conversion
decimal.toOctal(); // '0o377'
fractional.toOctal(); // '0o377.74'
// Large numbers use scientific notation in bases
const large = new Decimal('1000000');
large.toBinary(5); // '0b1.1110p+19'
large.toHex(3); // '0xf.42p+4'Convert Decimal values to fraction representation.
/**
* Return an array representing this Decimal as a fraction [numerator, denominator]
* @param maxDenominator - Maximum denominator value (optional)
* @returns Array with [numerator, denominator] as Decimal instances
*/
toFraction(maxDenominator?: Decimal.Value): Decimal[];Usage Examples:
// Simple fractions
const half = new Decimal('0.5');
half.toFraction(); // [Decimal('1'), Decimal('2')]
const quarter = new Decimal('0.25');
quarter.toFraction(); // [Decimal('1'), Decimal('4')]
// Complex fractions with maximum denominator
const pi = new Decimal('3.1415929204');
pi.toFraction(); // [Decimal('7853982301'), Decimal('2500000000')]
pi.toFraction(1000); // [Decimal('355'), Decimal('113')] (better approximation)
// Mixed numbers represented as improper fractions
const mixed = new Decimal('2.75');
mixed.toFraction(); // [Decimal('11'), Decimal('4')]
// Access numerator and denominator
const fraction = new Decimal('0.6').toFraction();
const numerator = fraction[0]; // Decimal('3')
const denominator = fraction[1]; // Decimal('5')Convert Decimal values to JavaScript numbers.
/**
* Return the value of this Decimal as a JavaScript number
* May lose precision for very large or very small numbers
* @returns JavaScript number representation
*/
toNumber(): number;Usage Examples:
const decimal = new Decimal('123.456');
const jsNumber = decimal.toNumber(); // 123.456 (JavaScript number)
// Precision considerations
const precise = new Decimal('123.456789012345678901234567890');
const rounded = precise.toNumber(); // 123.45678901234568 (loses precision)
// Range considerations
const veryLarge = new Decimal('1e308');
const infinity = veryLarge.toNumber(); // Infinity
const verySmall = new Decimal('1e-324');
const zero = verySmall.toNumber(); // 0
// Safe conversion check
function safeToNumber(decimal) {
const num = decimal.toNumber();
if (!Number.isFinite(num)) {
throw new Error('Value cannot be safely converted to number');
}
return num;
}All formatting methods support optional rounding mode parameters for precise control.
// Rounding mode constants available on Decimal class
static readonly ROUND_UP: 0; // Away from zero
static readonly ROUND_DOWN: 1; // Towards zero
static readonly ROUND_CEIL: 2; // Towards positive infinity
static readonly ROUND_FLOOR: 3; // Towards negative infinity
static readonly ROUND_HALF_UP: 4; // Towards nearest neighbor, ties away from zero
static readonly ROUND_HALF_DOWN: 5; // Towards nearest neighbor, ties towards zero
static readonly ROUND_HALF_EVEN: 6; // Towards nearest neighbor, ties to even
static readonly ROUND_HALF_CEIL: 7; // Towards nearest neighbor, ties towards positive infinity
static readonly ROUND_HALF_FLOOR: 8;// Towards nearest neighbor, ties towards negative infinity
type Decimal.Rounding = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;Usage Examples:
const value = new Decimal('123.456');
// Different rounding modes with toFixed
value.toFixed(1, Decimal.ROUND_UP); // '123.5'
value.toFixed(1, Decimal.ROUND_DOWN); // '123.4'
value.toFixed(1, Decimal.ROUND_CEIL); // '123.5'
value.toFixed(1, Decimal.ROUND_FLOOR); // '123.4'
// Rounding ties (exactly between two values)
const tie = new Decimal('123.45');
tie.toFixed(1, Decimal.ROUND_HALF_UP); // '123.5'
tie.toFixed(1, Decimal.ROUND_HALF_DOWN); // '123.4'
tie.toFixed(1, Decimal.ROUND_HALF_EVEN); // '123.4' (even digit)
// Rounding with exponential notation
const exp = new Decimal('1.235e+5');
exp.toExponential(1, Decimal.ROUND_UP); // '1.3e+5'
exp.toExponential(1, Decimal.ROUND_DOWN); // '1.2e+5'
// Rounding with precision notation
const prec = new Decimal('99.95');
prec.toPrecision(3, Decimal.ROUND_UP); // '100'
prec.toPrecision(3, Decimal.ROUND_DOWN); // '99.9'Handle special cases and edge scenarios in formatting.
Usage Examples:
// Negative numbers
const negative = new Decimal('-123.456');
negative.toFixed(2); // '-123.46'
negative.toExponential(2); // '-1.23e+2'
// Zero handling
const zero = new Decimal('0');
zero.toFixed(3); // '0.000'
zero.toExponential(2); // '0.00e+0'
zero.toBinary(); // '0b0'
// Very large precision
Decimal.set({ precision: 50 });
const highPrecision = new Decimal('1').div('3');
highPrecision.toString(); // '0.33333333333333333333333333333333333333333333333333'
// Infinity and NaN handling
const inf = new Decimal(Infinity);
const nan = new Decimal(NaN);
inf.toString(); // 'Infinity'
nan.toString(); // 'NaN'
inf.toFixed(2); // 'Infinity'
nan.toFixed(2); // 'NaN'