Decimal
Arbitrary precision decimal math. Add, subtract, multiply, divide numbers, shift digits left and right, with control over rounding and precision or scale of the result.
new
Constructs a new decimal value from a number or string.
Syntax
new Decimal(num)
Parameters
num: number | string | Decimal- The number to parse into a
Decimal
- The number to parse into a
Example
import { Decimal } from '@phensley/cldr';
const s = Number.MAX_SAFE_INTEGER;
const n = new Decimal(`${s}${s}.${s}`);
log(n);
90071992547409919007199254740991.9007199254740991
import { Decimal } from '@phensley/cldr';
for (const num of ['-10', 0, '123', Infinity, -Infinity, NaN]) {
const d = new Decimal(num);
log(d.toString());
}
-10 0 123 Infinity -Infinity NaN
abs
Return the absolute value of the number.
Syntax
abs(): Decimal
Example
import { Decimal } from '@phensley/cldr';
const n = new Decimal('-123.456');
log(n.abs().toString());
123.456
add
Adds the argument to this number, returning the sum. The scale of the result will be max(this.scale(), n.scale()).
Syntax
add(n): Decimal
Parameters
n: number | string | Decimal- The number to add to this one.
Example
import { Decimal } from '@phensley/cldr';
const a = new Decimal('0.003');
const b = new Decimal('0.0005');
const c = a.add(b).add(b);
log(c.toString());
0.0040
compare
Compare the decimal u to v, returning a number indicating whether one is larger or they are equal.
The abs
Syntax
compare(v [, abs]): number
Parameters
v: number | string | Decimal- Number to compare
abs: boolean- If
truecompare the absolute values, defaults tofalse.
- If
Return value
- Returns a
numberwith one of the following values:
-1 if u < v 0 if u = v 1 if u > v
Example
import { Decimal } from '@phensley/cldr';
const w = (s: string) => ' '.repeat(10 - s.length) + s;
const cmp = (a: string, b: string) =>
log(`${w(a)} cmp ${w(b)} = ${new Decimal(a).compare(b)}`);
cmp('1234', '1234');
cmp('1e10', '1e11');
cmp('1.23e5', '12e4');
cmp('12e4', '1.23e5');
cmp('-12e4', '1.23e5');
cmp('-1.23e5', '12e4');
cmp('1.2345e-10', '12e4');
1234 cmp 1234 = 0
1e10 cmp 1e11 = -1
1.23e5 cmp 12e4 = 1
12e4 cmp 1.23e5 = -1
-12e4 cmp 1.23e5 = -1
-1.23e5 cmp 12e4 = -1
1.2345e-10 cmp 12e4 = -1
decrement
Subtracts 1 from the number.
Syntax
decrement(): Decimal
Example
import { Decimal } from '@phensley/cldr';
const n = new Decimal('1.57');
log(n.decrement().toString());
0.57
divide
Divides a number by its argument, using the given context.
Syntax
divide(number, context?): Decimal
Parameters
number: number | string | Decimal- Divisor
context?: MathContext- Context to use for scale, precision, rounding
Example
import { Decimal } from '@phensley/cldr';
const rounding: RoundingModeType[] = ['half-even', 'floor'];
const n = new Decimal('1000');
for (const round of rounding) {
log(round);
for (const scale of [5, 10, 15]) {
const r = n.divide(6, { scale, round });
log(` ${r.toString()}`);
}
}
half-even 166.66667 166.6666666667 166.666666666666667 floor 166.66666 166.6666666666 166.666666666666666
divmod
Divides a number by its argument, returning the quotient and remainder as a pair.
Syntax
divmod(number): [Decimal, Decimal]
Parameters
number: number | string | Decimal- Divisor
Example
import { Decimal } from '@phensley/cldr';
const n = new Decimal('100');
for (const d of [3, 12, 15.7, 37.82, 90.122]) {
const [q, r] = n.divmod(d);
log(`(${n.toString()} / ${d}) is ${q.toString()} r ${r.toString()}`);
}
(100 / 3) is 33 r 1 (100 / 12) is 8 r 4 (100 / 15.7) is 6 r 5.8 (100 / 37.82) is 2 r 24.36 (100 / 90.122) is 1 r 9.878
increment
Adds 1 to a number.
Syntax
increment(): Decimal
Example
import { Decimal } from '@phensley/cldr';
const n = new Decimal('-0.57');
log(n.increment().toString());
0.43
integerDigits
Count of the number of integer digits. Always returns a number >= 1.
Syntax
integerDigits(): number
Example
import { Decimal } from '@phensley/cldr';
for (const s of ['.123', '12345.9999999', '1e20']) {
const n = new Decimal(s);
const d = n.integerDigits();
log(`${n.toString()} has ${d} integer digit${d === 1 ? '' : 's'}`);
}
0.123 has 1 integer digit 12345.9999999 has 5 integer digits 100000000000000000000 has 21 integer digits
isInteger
Indicates if this number is an integer or has a fractional part.
Syntax
isInteger(): boolean
Example
import { Decimal } from '@phensley/cldr';
for (const s of ['0', '5', '1e10', '.123', '12345.9999999', '5.999999999999999999999']) {
const n = new Decimal(s);
log(`${n.toString()} ${n.isInteger() ? 'yes' : 'no'}`);
}
0 yes 5 yes 10000000000 yes 0.123 no 12345.9999999 no 5.999999999999999999999 no
isNegative
Indicates if this number is negative.
Syntax
isNegative(): boolean
Example
import { Decimal } from '@phensley/cldr';
for (const s of ['0', '123', '-15.7']) {
const neg = new Decimal(s).isNegative();
log(`${s} ${neg ? 'is' : 'is not'} negative`);
}
0 is not negative 123 is not negative -15.7 is negative
mod
Divides a number by an argument and returns the remainder.
Note This differs from the modulo operator in math in that it can return a negative number.
Syntax
mod(number): Decimal
Parameters
n: number- Number to divide by
Example
import { Decimal } from '@phensley/cldr';
const n = new Decimal(777);
for (const m of [2, 3, 4, 5, 6]) {
const a = n.mod(m);
const b = n.negate().mod(m);
log(`${n.toString()} % ${m} = ${a.toString()} ` +
`-${n.toString()} % ${m} = ${b.toString()}`);
}
777 % 2 = 1 -777 % 2 = -1 777 % 3 = 0 -777 % 3 = -0 777 % 4 = 1 -777 % 4 = -1 777 % 5 = 2 -777 % 5 = -2 777 % 6 = 3 -777 % 6 = -3
movePoint
Move the decimal point left or right n places. Does not change precision, it only
affects the exponent.
Moves to the left if n is negative, and to the right if positive.
Syntax
movePoint(n): Decimal
Parameters
n: number- Number of places to move the decimal point left (if negative) or right (if positive)
Example
import { Decimal } from '@phensley/cldr';
const n = new Decimal('12345.6789');
for (const p of [-5, -3, -1, 1, 3, 5]) {
log(n.movePoint(p).toString());
}
0.123456789 12.3456789 1234.56789 123456.789 12345678.9 1234567890
multiply
Multiply a number by its argument, using the given math context.
Syntax
multiply(number, context?): Decimal
Parameters
number: number | string | Decimal- Multiplier
context?: MathContext- Context to use for scale, precision, rounding
Example
import { Decimal, DecimalConstants } from '@phensley/cldr';
const { E, PI } = DecimalConstants;
const n = new Decimal('7');
for (const m of ['12', '1e10', '0.0000004737', '0.9999999', PI, E]) {
const r = n.multiply(m, { scale: 30 });
log(r.stripTrailingZeros());
}
84 70000000000 0.0000033159 6.9999993 21.991148575128552669238503682957 19.027972799213316647522012299469
negate
Inverts the sign of the number.
Syntax
negate(): Decimal
Example
import { Decimal } from '@phensley/cldr';
for (const n of ['-5', '3.1415']) {
log(new Decimal(n).negate());
}
5 -3.1415
precision
Returns the precision in the number. Precision indicates the number of digits used to express the value.
For example the number 1e10 has 1 digit of precision, while 123e10 has 3.
Syntax
precision(): number
Example
import { Decimal } from '@phensley/cldr';
for (const n of ['1', '1e10', '1.2345']) {
log(new Decimal(n).precision());
}
1 1 5
scale
Returns the scale of the number. Scale that is zero or positive indicates the number of digits to the right of the decimal point. A negative scale indicates the negated power of 10 the unscaled value is multiplied by.
For example the number 1.234 has a scale of 3 while 1e10 has a scale of -10.
Syntax
scale(): number
Example
import { Decimal } from '@phensley/cldr';
for (const n of ['1', '1e-10', '1e10', '1.2345', '1.234e10']) {
log(`${n} scale ${new Decimal(n).scale()}`);
}
1 scale 0 1e-10 scale 10 1e10 scale -10 1.2345 scale 4 1.234e10 scale -7
scientific
Return the coefficient and adjusted exponent of the number, suitable for displaying scientific notation.
Syntax
scientific(minIntDigits: number = 1): [Decimal, number]
Example
import { Decimal } from '@phensley/cldr';
const n = new Decimal('157.39E10');
const [coeff, exp] = n.scientific();
log(`${coeff.toString()} x 10^${exp}`);
1.5739 x 10^12
setScale
Sets the scale of this number.
Syntax
setScale(number): Decimal
Example
import { Decimal } from '@phensley/cldr';
const n = new Decimal('12345.678');
for (let scale = -5; scale <= 5; scale++) {
const r = n.setScale(scale);
log(`scale ${scale} = ${r}`);
}
scale -5 = 0 scale -4 = 10000 scale -3 = 12000 scale -2 = 12300 scale -1 = 12350 scale 0 = 12346 scale 1 = 12345.7 scale 2 = 12345.68 scale 3 = 12345.678 scale 4 = 12345.6780 scale 5 = 12345.67800
shiftleft
Shift digits n places to the left, increasing precision.
Syntax
shiftleft(shift): Decimal
Example
import { Decimal } from '@phensley/cldr';
for (const n of ['1', '0.123456789']) {
log(n.toString());
for (let shift = 1; shift <= 10; shift++) {
const r = new Decimal(n).shiftleft(shift);
log(` ${shift} -> ${r}`);
}
}
1 1 -> 10 2 -> 100 3 -> 1000 4 -> 10000 5 -> 100000 6 -> 1000000 7 -> 10000000 8 -> 100000000 9 -> 1000000000 10 -> 10000000000 0.123456789 1 -> 1.234567890 2 -> 12.345678900 3 -> 123.456789000 4 -> 1234.567890000 5 -> 12345.678900000 6 -> 123456.789000000 7 -> 1234567.890000000 8 -> 12345678.900000000 9 -> 123456789.000000000 10 -> 1234567890.000000000
shiftright
Shifts digits n places to the right and rounds, reducing precision.
Note that when the shift is equal to or greater than the precision it can shift the number to zero. The exponent is also preserved even when the number is shifted to zero.
Syntax
shiftright(shift, round?): Decimal
Parameters
shift: number- Number of decimal places to shift
round?: RoundingModeType- Rounding mode to use
Example
import { Decimal } from '@phensley/cldr';
for (const n of ['12345.67890', '55555.55555']) {
log(n.toString());
for (let shift = 1; shift <= 10; shift++) {
const r = new Decimal(n).shiftright(shift);
log(` ${shift} -> ${r}`);
}
}
12345.67890 1 -> 12345.6789 2 -> 12345.679 3 -> 12345.68 4 -> 12345.7 5 -> 12346 6 -> 12350 7 -> 12300 8 -> 12000 9 -> 10000 10 -> 0 55555.55555 1 -> 55555.5556 2 -> 55555.556 3 -> 55555.56 4 -> 55555.6 5 -> 55556 6 -> 55560 7 -> 55600 8 -> 56000 9 -> 60000 10 -> 0
signum
Returns 1 if the sign of the number is positive, -1 if negative, and 0 if equal to 0.
Syntax
signum(): number
Example
import { Decimal } from '@phensley/cldr';
for (const n of ['0', '-1.2', '345', '10e-10', '-10e10']) {
log(`${n} signum is ${new Decimal(n).signum()}`);
}
0 signum is 0 -1.2 signum is -1 345 signum is 1 10e-10 signum is 1 -10e10 signum is -1
stripTrailingZeros
Remove any trailing zeros from a number.
Syntax
stripTrailingZeros(): Decimal
Example
import { Decimal } from '@phensley/cldr';
for (const n of ['1.0', '0.9999900000', '1.57000000', '1e10']) {
log(new Decimal(n).stripTrailingZeros().toString());
}
1 0.99999 1.57 10000000000
subtract
Subtract the argument from this number.
Syntax
subtract(number): Decimal
Parameters
number: number | string | Decimal- Number to subtract
Example
import { Decimal, DecimalConstants } from '@phensley/cldr';
const { E } = DecimalConstants;
const n = new Decimal('1');
for (const m of ['.999999', '37.79', E]) {
let r = n.subtract(m);
if (r.scale() > 20) {
r = r.setScale(20);
}
log(r.toString());
}
0.000001 -36.79 -1.71828182845904523536
toParts
Render a number into an array of Part.
Syntax
toParts(): Part[]
Example
import { Decimal } from '@phensley/cldr';
for (const n of ['3', '1e10', '3.14159']) {
log(new Decimal(n).toParts());
}
[ { type: 'integer', value: '3' } ]
[ { type: 'integer', value: '10000000000' } ]
[
{ type: 'integer', value: '3' },
{ type: 'decimal', value: '.' },
{ type: 'fraction', value: '14159' }
]
toString
Syntax
toString(): string
Example
import { Decimal } from '@phensley/cldr';
const s = Number.MAX_SAFE_INTEGER;
const n = new Decimal(`${s}${s}.${s}`);
log(n.toString());
90071992547409919007199254740991.9007199254740991
toScientificParts
Format the number in scientific notation as an array of parts.
Syntax
toScientificParts(minIntegers: number = 1): Part[]
Example
import { Decimal } from '@phensley/cldr';
const n = new Decimal('157.39E10');
log(n.toScientificParts());
[
{ type: 'integer', value: '1' },
{ type: 'decimal', value: '.' },
{ type: 'fraction', value: '5739' },
{ type: 'exp', value: 'E' },
{ type: 'plus', value: '+' },
{ type: 'integer', value: '12' }
]
toScientificString
Format the number in scientific notation as a string.
Syntax
toScientificString(minIntegers: number = 1): string
Example
import { Decimal } from '@phensley/cldr';
const n = new Decimal('157.39E10');
log(n.toScientificString());
1.5739E+12
trailingZeros
Returns the number of trailing decimal zeros.
Syntax
trailingZeros(): number
Example
import { Decimal } from '@phensley/cldr';
for (const n of ['1', '1e10', '0.12300000']) {
log(new Decimal(n).trailingZeros());
}
0 0 5