Ratio.js

Provides a Fraction / Rational / Ratio object for javascript.

Why use Ratio.js?

By keeping values in a rational form, you can maintain precision and can avoid common floating point operation errors in Javascript.

• Simple Demo
• Documentation
• Testcase
• Release Notes

Support:

Node.js, Chrome 19+, Firefox 12+, IE 7+, and Opera 11+.

Note: Run the test cases to check for additional browser compatibility.

##Current version 0.3.11

Installation

Just include the Ratio.js script.

Browser:

<script src="./lib/Ratio-0.3.11.js</b>

Install from npm

npm install lb-ratio

Include in project

var Ratio = require("lb-ratio");

##Examples

1. What is 12.12121212121212 as a fraction?

   Solution:

    var result = Ratio.parse( 12.12121212121212 ).reduce().toString();
    result == "400/33";
   

2. Evaluate ( 0.1 + 0.2 )/( 1/3 * 12 ) as a Ratio?

   Solution:

    var a = Ratio.parse(0.1).add(0.2).divide( Ratio(1,3).multiply(12) );
    a.divSign = ":";
    var result = a.toString();
    result == "3:40"
   

3. Does Math.PI equal 22/7?

   Solution:

    var result = Ratio.parse( "22/7" ).equals( Math.PI );
    result == false;
   

Short Tutorial

Ratio Constructor

Ratio.js introduces a global constructor called Ratio.

new is not require to make a new object since it's done for you.
Thus new Ratio() and Ratio() are both valid to instantiate an object.

Ratio Properties

All Ratio objects have a numerator, denominator, and divSign property. The default value of the numerator is 0 and denominator is 1.

var a = Ratio();
a.toString() == "0/1";
a.numerator == 0;
a.denominator == 1;
a.divSign == "/";

Examples:

// Good Values
Ratio().toString() === "0/1"
Ratio(4).toString() === "4/1"
Ratio(4,5).toString() === "4/5"

// Bad Values
Ratio("five").toString() === "NaN/1"
Ratio(1,"ten").toString() === "1/NaN"
Ratio("five","ten").toString() === "NaN/NaN"

Ratio values

To retrieve the value inside a Ratio object you can use toString(), toLocaleString(), toArray() or valueOf().
toString() - returns string "numerator/denominator".
toArray() - returns [ numerator, denominator ].
valueOf() - returns (numerator/denominator).
toLocaleString() - returns string mixed number, whole number or proper fraction.

var a = Ratio(30,10);
a.toString() == "30/10";
a.toLocaleString() == "3";
a.toArray() == [30,10];
a.valueOf() == 3; // same as +a or Number(a)

Ratio Comparison

valueOf() is called when inequality comparisons are made on a Ratio object.
However, equalivance( == ) will compare the object and not the value of the object. Use .equals() instead.
Thus you can do the following.

var a = Ratio(15,3), b = Ratio(3,15);
a > b == true;
a < b == false;
( a == b ) == false; 
a.equals( a ) == true;
a.equals( b ) == false;

Creating new Ratio Objects

There are various ways to create a new Ratio object. Ratio.parse() is the prefered methods.

Ratio()

// "0/1" is the default ratio
Ratio().toString() === "0/1";

// Accepts whole numbers
Ratio(1).toString() === "1/1";

// Accepts an numerator and denominator
Ratio(1,2).toString() === "1/2";

Ratio.parse( value )

// Use Ratio.parse() to parse any other values that aren't whole numbers.

// Accepts decimals
Ratio.parse(1/2).toString() === "1/2";

// Accepts fractions as strings
Ratio.parse("1/2").toString() === "1/2";

// Accepts mixed numbers as strings
Ratio.parse( "1 1/2" ).toString() === "3/2";

// Accepts a Ratio object
Ratio.parse( Ratio(1/2) ).toString() === "1/2";

Ratio.parse( value1, value2 )
This is the same as value1 / value2 or Ratio.parse(value1).divide(value2)

// Converts the Ratio objects to a single fraction.
Ratio.parse( Ratio(1), Ratio(2) ).toString() == "1/2";

// Accepts 
// (1/2) / (1/3) = 3/2
Ratio.parse( "1/2", "1/3" ).toString() === "3/2";

Methods

All proproty methods are non-destructive and return a new Ratio object.

var a = Ratio(1,3);
a.toString() == "1/3"
a.add(1,5).toString() == "8/15"
a.toString() == "1/3"

Refer to the documentation for a complete method list.

Additional Examples

// in Javascript
var a = 0.1 + 0.2;
var b = 0.3;
( a == b ) == false;
a == 0.30000000000000004;

var a = Ratio();
a.toString() == "0/1";
a.divSign = ":";
a.toString() == "0:1";

// Ratio operations
var c = Ratio.parse(1/3).negate().add("-0.1").multiply(0xF3).divide(1,2).divide(1e-4).abs();
c.toString() == "1053/5";

// in Ratio.js
var a = Ratio( 0.1 ).add( 0.2 );
var b = Ratio( 0.3 );
(+a == +b ) == true;

// another way of writing it.
Ratio( "0.1" ).add( 0.2 ).equals( 0.3 ); // true!

// And another.
var a = Ratio(1,10);
var b = Ratio(2,10);
var c = Ratio(3,10);
a.add( b ).toString() === c.toString(); // true!

a.toString() === "1/10";
+a === 0.1;
( +a === a.valueOf() ) ;
a.toArray(); // returns [ 1, 10 ]

License

License: MIT License and GPL v3

Known Issues

• Precision is lost for values passed +/- 9007199254740992. stackoverflow.com
  
• It's best to call .correctRatio() if you manually change the denominator. Alternatively you could use .clone(null, new_denominator_value) to get a new ratio with a modified denominator.