numeric-types
v0.3.1
Published
Numeric types such as precise decimals
Downloads
28
Readme
Numeric types for JavaScript
This library contains implementations of useful numeric types for JavaScript and TypeScript.
npm install numeric-types
Features and status
This is currently an early release.
- Rounding modes: up, down, half down, half even, half up, floor and ceiling
- Decimal number representation
Decimal
on top ofnumber
with limited precision of 15 digitsBigDecimal
for more precise numbers, with up toNumber.MAX_SAFE_INTEGER
digits- Basic math operations: add, subtract, multiply, divide
- Integer representation
Integer
for integers betweenNumber.MIN_SAFE_INTEGER
andNumber.MAX_SAFE_INTEGER
BigInteger
for large integers
API
In this library all numeric types are immutable, so functions always return a new instance. Each numeric type provides a limited API to support their creation and basic use.
Operations on the number types is provided as separate functions that can be imported. This design is to allow the library to take advantage of tree-shaking.
static NumericType.fromNumber(value: number): NumericType
Create an instance of the numeric type from a regular JavaScript number.
static NumericType.parse(value: string): NumericType
Create an instance of the numeric type from a string.
numericType.toString(): string
Turn the numeric type into a string representation supported by
fromString
.
MathContext
and rounding
This library uses a class named MathContext
to support operations such as
setting the scale or precision and rounding a number.
import { MathContext, RoundingMode } from 'numeric-types';
// Create a context that requests 2 digits after the decimal using Half Up rounding
const contextWithScale = MathContext.ofScale(2, RoundingMode.HalfUp);
// Context that requests at max 10 digits of precision
const contextWithPrecision = MathContext.ofPrecision(10, RoundingMode.Ceiling);
Rounding modes
RoundingMode.Down
- Round towards zero.RoundingMode.Up
- Round away from zero.RoundingMode.HalfDown
- Round towards the nearest neighbor, but if in the middle round towards zero.RoundingMode.HalfEven
- Round towards the nearest neighbor, but if in the middle round towards the even neighbor.RoundingMode.HalfUp
- Round towards the nearest neighbor, but if in the middle round away from zero.RoundingMode.Floor
- Round towards negative infinity.RoundingMode.Ceiling
- Round towards positive infinity.RoundingMode.Unnecessary
- Do not round, instead throw an error if rounding is required.
Type: Decimal
Decimal is an implementation of a numeric type that avoids the rounding
errors common with floating point numbers. There are two versions, Decimal
and BigDecimal
where Decimal
is limited to safely handling 15 digits and
BigDecimal
can handle up to Number.MAX_SAFE_INTEGER
digits:
import { Decimal, multiply } from 'numeric-types/decimal';
const a = Decimal.fromNumber(0.1);
const b = Decimal.parse('12');
const ab = multiply(a, b);
console.log(ab.toString());
Types are available for TypeScript:
import { AbstractDecimal, Decimal } from 'numeric-types/decimal';
const decimal: AbstractDecimal<any> = Decimal.fromNumber(0.1);
Operations
These operations are available from numeric-types/decimal
. Import them
separately like:
import { operationHere, anotherOperation } from 'numeric-types/decimal';
const { operationHere, anotherOperation } = require('numeric-types/decimal');
compare(a: DecimalType, b: DecimalType): -1 | 0 | 1
Compare two decimal numbers. This method will return
0
if the numbers are the same,-1
ifa
is less thanb
and1
ifa
is greater thanb
.isEqual(a: DecimalType, b: DecimalType): boolean
Get if two decimal numbers are equal.
isLessThan(a: DecimalType, b: DecimalType): boolean
Get if the decimal number
a
is less than the numberb
.isLessThanOrEqual(a: DecimalType, b: DecimalType): boolean
Get if the decimal number
a
is less than or equal to the numberb
.isGreaterThan(a: DecimalType, b: DecimalType): boolean
Get if the decimal number
a
is greater than the numberb
.isGreaterThanOrEqual(a: DecimalType, b: DecimalType): boolean
Get if the decimal number
a
is greater than or equal to the numberb
.toString(a: DecimalType): string
Turn a decimal numbers into its string representation.
scale(a: DecimalType, context: MathContext): DecimalType
Scale the given decimal number according to the specified context.
round(a: DecimalType, roundingMode?: RoundingMode): DecimalType
Round the given decimal number. If the rounding mode is not specified
RoundingMode.HalfUp
is used. This is equivalent to callingscale
withMathContext.ofScale(0, roundingMode)
.add(a: DecimalType, b: DecimalType, context?: MathContext): DecimalType
Add two decimal numbers together, optionally specifying a context to be used to adjust the scale of the result.
subtract(a: DecimalType, b: DecimalType, context?: MathContext): DecimalType
Subtract a decimal number
b
from the numbera
. Optionally specify a context to be used to adjust the scale of the result.multiply(a: DecimalType, b: DecimalType, context?: MathContext): DecimalType
Multiply two decimal numbers together. Optionally specify a context to be used to adjust the scale of the result.
divide(a: DecimalType, b: DecimalType, context: MathContext): DecimalType
Divide a decimal number
b
from the numbera
. A context is required to determine the scale and how to round things.
Type: Integer
Integer is an implementation of a whole number. There are currently two versions
available, Integer
which is limited to the range of number
and BigInteger
which is can represent larger numbers.
import { Integer, multiply } from 'numeric-types/integer';
const a = Integer.fromNumber(20);
const b = Integer.parse('40');
const ab = multiply(a, b);
console.log(ab.toString());
Types are available for TypeScript:
import { AbstractInteger, Integer } from 'numeric-types/integer';
const integer: AbstractInteger<any> = Integer.fromNumber(1);
Operations
These operations are available from numeric-types/integer
. Import them
separately like:
import { operationHere, anotherOperation } from 'numeric-types/integer';
const { operationHere, anotherOperation } = require('numeric-types/integer');
compare(a: IntegerType, b: IntegerType): -1 | 0 | 1
Compare two integers. This method will return
0
if the numbers are the same,-1
ifa
is less thanb
and1
ifa
is greater thanb
.isEqual(a: IntegerType, b: IntegerType): boolean
Get if two integers are equal.
isLessThan(a: IntegerType, b: IntegerType): boolean
Get if the integer
a
is less than the numberb
.isLessThanOrEqual(a: IntegerType, b: IntegerType): boolean
Get if the integer
a
is less than or equal to the numberb
.isGreaterThan(a: IntegerType, b: IntegerType): boolean
Get if the integer
a
is greater than the numberb
.isGreaterThanOrEqual(a: IntegerType, b: IntegerType): boolean
Get if the integer
a
is greater than or equal to the numberb
.toString(a: IntegerType): string
Turn a integers into its string representation.
add(a: IntegerType, b: IntegerType): IntegerType
Add two integers together.
subtract(a: IntegerType, b: IntegerType): IntegerType
Subtract
b
froma
multiply(a: IntegerType, b: IntegerType): IntegerType
Multiply two integers together.
divide(a: IntegerType, b: IntegerType): IntegerType
Divide
a
by the divisorb
.