dirac-number

A collection of utility methods for floating point Number operations

dirac-number is a dirac-flavoured wrapper for BigNumber.js.

Instead of constructing BigNumber objects from your numbers and performing operations on them within your app, this module provides a set of simplified math utilities that take simple Number or String types, and use BigNumber operations for accuracy behind the scenes.

API

DiracNumber is an extension of the BigNumber class.

import DiracNumber from 'dirac-number'

const num = new DiracNumber('123.456')
num.round(2) // '123.46'
num instanceof BigNumber // true

There is a shortcut method of construction in DiracNumber.vn:

import DiracNumber, { vn } from 'dirac-number'

const num = vn(123.456)
num.round(2) // '123.46'
num instanceof DiracNumber // true

Math operations

The following static methods can take any number of values and perform the operation on each of them in the specified order.

Add a list of values

DiracNumber.add(1, 2, 3) // 1 + 2 + 3 = 6

Subtract a list of values

DiracNumber.subtract(2, 1) // 2 - 1 = 1

Multiply a list of values

DiracNumber.multiply(2, 2) // 2 * 2 = 4

Divide a list of values

DiracNumber.divide(10, 2) // 10 / 2 = 5

Keep in mind when using the DiracNumber math functions that when performing multiple calculations you will need to make sure the execution order is correct.

Native JS will execute in order of BEDMAS automatically, whereas with these methods, you have to make sure of this manually.

E.g.

4 * 5 + 3 // returns 23

multiply(4, add(5, 3)) // returns 32

You need to take into account the order in which the functions will be executed, so in this case it should be:

add(3, multiply(4, 5)) // returns 23

Rounding and formatting

Round a value to a specified number of decimal points. The default rounding mode is ROUND_HALF_UP, the 'Round Half Away From Zero' tie-breaking rule.

DiracNumber.round(5.545333, 2) // "5.55"

Rounding modes

You can specify any of the Big Number rounding modes to the round function. These are available via DiracNumber.ROUNDING_METHODS.

import DiracNumber, { ROUNDING_MODES } from 'dirac-number'

DiracNumber.round(5.545333, 2, ROUNDING_MODES.ROUND_DOWN) // "5.54"

isFinite

A static equivalent to BigNumber.isFinite that reports false for non-numeric values.

DiracNumber.isFinite(null) // false
DiracNumber.isFinite('') // false
DiracNumber.isFinite(Infinity) // false

DiracNumber.isFinite(0) // true
DiracNumber.isFinite(Number.MAX_VALUE) // true
DiracNumber.isFinite('-123.456') // true

sumBy

Calculates the sum of all items in a collection based on a property name.

Accepts the following parameters:

• Array an array of items to loop through.
• String a property name to sum by.
• Number an optional decimal points number to round the sum value to (defaults to 2 d.p.).

Example:

DiracNumber.sumBy([], '') // 0.00
DiracNumber.sumBy([{ a: 1 }, { a: 2 }], 'a') // 3.00
DiracNumber.sumBy([{ a: 1.4222 }, { a: 2.1115 }], 'a', 3) // 3.534

Contributing

Build

npm run build

Test

npm test

Watch

To watch for changes, build them and run the tests:

npm run watch

License

MIT © Dirac