rational-number

RationalNumber is an implementation for fractions in JavaScript consisting of two integers. Mathematical operations such as addition, subtraction, multiplication and division are provided. Division by zero is allowed and should produce correct mathematical results according to the use of Infinity and NaN in JavaScript.

Fractions are maintained by default in reduced form. For example, setting the value to 2/4 will automatically be reduced (simplified) to 1/2. However functions forcing non-reduced fractions are provided, particularly to avoid speed issues in intermediate calculations (although the current mathematical functions will reduce the fraction after every calculation to minimize the chance of overflow).

This implementation of rational numbers limits the numerator and denominator to the range from 0 to 2^53–1 plus a sign. Optional overflow detection is included, with the methods checkOverflowOn() and CheckOverflowOff() turning this feature on and off.

Using in node applications

The RationalNumber module can be installed globally for use in node with the command:

$ npm install -g rational-number

If you want only to use locally in a node project, then install as a package dependency with the command:

$ npm install --save rational-number

Here is an example of loading the module into a node script and adding two rational numbers together:

var RationalNumber = require('rational-number');
    
var rn1 = new RationalNumber(4, 5);
var rn2 = new RationalNumber('26/4');
var rn3 = rn1.add(rn2);
console.log(rn1.toString(),"+",rn2.toString(),"=",rn3.toString());
console.log(rn1.toStringMixed("_"),"+",rn2.toStringMixed("_"),
   "=",rn3.toStringMixed("_"));
console.log(rn1.valueOf()+" + "+rn2.valueOf()+" = "+rn3.valueOf());

The above code should output the following text to the console:

4/5 + 13/2 = 73/10
4/5 + 6_1/2 = 7_3/10
0.8 + 6.5 = 7.3

Using in web browsers

The JavaScript files for RationalNumber can also be used within a webpage by including these two files:

<script src="RationalNumber-base.js"></script>
<script src="RationalNumber-math.js"></script>

The first file (RationalNumber-base.js) is required, while the second one containing mathematical functions (add, subtract, etc.) is optional. The lib directory contains a makefile with example commands to generate minified versions of the programs files. Visit the RationalNumber homepage to try an online demo of rational number calculations running within a webpage.

Testing

Input and output from the code can be tested using mocha and the JavaScript files in the test directory. To test from a node installation:

$ npm install   # to download mocha dependency if necessary
$ npm test

Website

The website for RationalNumber documentation is http://rationalnumber.sapp.org.

And the corresponding GitHub repository is https://github.com/craigsapp/RationalNumber.

List of RationalNumber methods

Click on the method name to view documentation for that function.

• getNumerator — Return the numerator, including sign.
• getNumeratorAbsoluteValue — Return the numerator, excluding sign.
• setNumerator — Set the numerator, reducing fraction if necessary.
• setNumeratorNoReduce — Set the numerator but don't reduce fraction.
• setNumeratorAbsoluteValueNoReduce — Sets numerator without changing sign or reducing.
• getDenominator — Return the denominator (always non-negative).
• setDenominatorAbsoluteValue — Set the denominator (sign ignored).
• setDenominatorAbsoluteValueNoReduce — Set denominator, not trying to reduce the fraction.
• setValue — Set the numerator and denominator (sign can be on either or both).
• setValueNoReduce — Set the numerator and denominator, but don't try to reduce.
• setSign — Set the sign to positive or negative.
• getSign — Returns –1 if negative, +1 otherwise.
• reduce — Reduce the fraction if needed.
• toFloat — Alias for valueOf method.
• toNumber — Alias for valueOf method.
• valueOf — Return a floating-point copy of the rational number.
• toString — Convert to a string in the form "n/d".
• toStringMixed — Return a string as a mixed fraction.
• toJSON — Create a JSON string.
• fromString — Read number from string.
• fromStringNoReduce — Read number from string without reducing.
• parseString — Return a new RationalNumber rather than changing current object.
• clone — Make a new copy of the RationalNumber.
• copy — Copy the value of another RationalNumber.
• isSafe — Numerator and denominator both less than 2⁵³.
• isNaN — Returns true if equal to 0/0.
• isInfinite — Returns true if denominator is 0 and numerator is not.
• isValid — Returns true if safe, finite and not NaN.
• checkOverflow — Same as isSafe(), but throws an error.
• checkOverflowOn — Force validity check for overflows.
• checkOverflowOff — Turn off automatic overflow validity checks.
• isEqual — Return true if sign, numerator and denominator of two numbers are identical.
• isPositive — Returns true if larger than 0.
• isNegative — Returns true if smaller than 0.
• isInteger — Returns true if denominator is 1.

Additional methods provided in RationalNumber-math.js:

• abs — Return non-negative copy of the rational number.
• invert — Switch the numerator and denominator.
• inversion — Alias for getInversion method.
• getInversion — Return a reciprocal copy of called object.
• negate — Make positive values negative and vice-versa.
• negation — Alias for getNegation method.
• getNegation — Return a copy of the object, with sign reversed.
• addTo — To this RationalNumber, add additional numbers.
• add — Similar to addTo(), but returns sum rather than altering contents.
• subtractTo — To this RationalNumber, subtract values.
• subtract — Similar to subtractTo(), but returns result rather than altering calling object.
• multiplyTo — To this RationalNumber, multiply values.
• multiply — Similar to multiplyTo(), but returns result rather than altering calling object.
• divideTo — To this RationalNumber, divide values.
• divide — Similar to divideTo(), but returns result rather than altering calling object.