@fav/arith.number

@fav/arith.number

Creates a number for accurate arithmetics.

"fav" is an abbreviation of "favorite" and also the acronym of "for all versions". This package is intended to support all Node.js versions and many browsers as possible. At least, this package supports Node.js >= v0.10 and major Web browsers: Chrome, Firefox, IE11, Edge, Vivaldi and Safari.

Install

To install from npm:

$ npm install --save @fav/arith.number.

NOTE: npm < 2.7.0 does not support scoped package, but old version Node.js supports it. So when you use such older npm, you should download this package from github.com, and move it in node_modules/@fav/arith.number/ directory manually.

Usage

For Node.js:

var arithNumber = require('@fav/arith.number');
var add = require('@fav/arith.add');

var num1 = arithNumber(1.23) // => { numerator: 123, denominator: 1, exponent: -2 }
num1.toApproximateString() // => '1.23'
num1.toApproximateString(1) // => '1.2'
num1.toApproximateString(1, Math.ceil) // => '1.3'

var num2 = arithNumber('4.56') // => { numerator: 456, denominator: 1, exponent: -2 }
num2.toApproximateString() // => '4.56'
num2.toApproximateString(1) // => '4.5'
num2.toApproximateString(1, Math.ceil) // => '4.6'

1.23 + 4.56 // => 5.789999999999999

var num3 = add(num1, num2) // => { numerator: 579, denominator: 1, exponent: -2 }
num3.toApproximateString() // => '5.79'
num3.toApproximateString(1) // => '5.7'
num3.toApproximateString(1, Math.ceil) // => '5.8'

For Web browsers:

<script src="fav.arith.number.min.js"></script>
<script>
var arithNumber = fav.arith.number;
var num1 = arithNumber(1.23) // => { numerator: 123, denominator: 1, exponent: -2 }
num1.toApproximateString() // => '1.23'
num1.toApproximateString(1) // => '1.2'
num1.toApproximateString(1, Math.ceil) // => '1.3'
</script>

API

arithNumber(value) : ArithNumber

Creates an object of which prototype is ArithNumber. ArithNumber represents a number and consists of three integers: numerator, denominator and exponent.

If value is a string, this function supports following notations:

• '123', '-45', '+678'
• '12.3', '-.45'
• '123e+45', '-6.789E-12'

Parameters:

Parameter	Type	Description
value	number | string	A number value or its string notation.

Returns:

A number object of which prototype is ArithNumber.

Type: ArithNumber

ArithNumber

Represents a number, and its instance consists of three integers: numerator, denominator, exponent. (a number = ( numerator / denominator ) * 10^exponent ).

Arithmetics in program often causes rounding error. However, integer operations except division is accurate as long as the integer value is within safe range. (Number.MIN_SAFE_INTEGER 〜 Number.MAX_SAFE_INTEGER in Javascript).

Therefore, @fav/arith.* packages operate a number data which consists of the above three integer elements.

The safe ranges of the three elements are as follows:

Elements	Range	Note
numerator	-9007199254740991 〜 9007199254740991	Number.MIN_SAFE_INTEGER 〜 Number.MAX_SAFE_INTEGER
denominator	1 〜 900719925474099	1 〜 Number.MAX_SAFE_INTEGER/10
exponent	-9007199254740975 〜 9007199254740975	Number.MIN_SAFE_INTEGER - String(Number.MIN_SAFE_INTEGER).length 〜 Number.MAX_SAFE_INTEGER - String(Number.MAX_SAFE_INTEGER).length

If each element is out of its safe range, the value of ArithNumber object is inaccurate. But it does not mean that the ArithNumber object is infinity, because 9007199254740992e+0 is less than 9007199254740991e+1. So ArithNumber prototype does not provide any methods for infinity like .isFinite.

For the ArithNumber object, it is more important that this object is accurate or not than infinity or NaN. Therefore this prototype provides the methods: .isAccurate.

This prototype also provide a method: .toApproximateString. Since the conversion to a string is not always accurate, this method can take decimalPlaces and a rounding function as parameters.

Methods:

.isAccurate() : boolean

Checks whether the ArithNumber object has an accurate number value.

Returns:

True, if the value of the ArithNumber object is accurate.

Type: boolean

.toApproximateString([decimalPlaces, [rounding]]) : string

Gets a string of this number value. If numerator can not be divided by denominator, the result string is approximate and the maximum decimal places is 20. (round down 21th place).

When a parameter decimalPlaces is specified, this function always output decimal until the specified place, and in addition a parameter rounding is specified, this function rounds up or down the next of the specified place.

Parameters:

Paramerter	Type	Description
decimalPlaces	number	The fixed decimal places.
rounding	function	The rounding function to round the next of decimalPlaces place.

Returns:

A string of an approximate number value of this object.

Type: string

Checked

Node.js (4〜)

Platform	4	5	6	7	8	9	10
macOS	◯	◯	◯	◯	◯	◯	◯
Windows10	◯	◯	◯	◯	◯	◯	◯
Linux	◯	◯	◯	◯	◯	◯	◯

io.js (1〜3)

Platform	1	2	3
macOS	◯	◯	◯
Windows10	◯	◯	◯
Linux	◯	◯	◯

Node.js (〜0.12)

Platform	0.8	0.9	0.10	0.11	0.12
macOS	◯	◯	◯	◯	◯
Windows10	◯	◯	◯	◯	◯
Linux	◯	◯	◯	◯	◯

Web browsers

Platform	Chrome	Firefox	Vivaldi	Safari	Edge	IE11
macOS	◯	◯	◯	◯	--	--
Windows10	◯	◯	◯	--	◯	◯
Linux	◯	◯	◯	--	--	--

License

Copyright (C) 2018 Takayuki Sato

This program is free software under MIT License. See the file LICENSE in this distribution for more details.