* Dynamically sized means that (provided enough memory) the BigRational * numbers can't overflow (nor underflow); this characteristic is * different from Java's data types int and long, but common with * BigInteger (which however implements only integer numbers, i.e. no * fractions) and BigDecimal (which however only implements precisely * rational numbers with denominators that are products of 2 and 5 [and * implied 10]). * Arbitrary precision means that there is no loss of precision with * common arithmetic operations such as addition, subtraction, * multiplication, and division (BigDecimal loses precision with * division, if factors other than 2 or 5 are involved). * [Doubles and floats can overflow and underflow, have a limited * precision, and only implement precisely rationals with a denominator * that is a power of 2.] * *

* BigRational provides most operations needed in rational number space * calculations, including addition, subtraction, multiplication, division, * integer power, remainder/modulus, comparison, and different roundings. * *

* BigRational provides conversion methods to and from the native types * long, int, short, and byte (including support for unsigned values), * double (binary64), float (binary32), quad (binary128, quadruple), * half (binary16), and BigInteger. * BigRational can parse and print many string representations: rational, * dot notations, with exponent, even mixtures thereof, and supports * different radixes/bases (2 to typically 36 [limited by BigInteger * parsing implementation]). * *

* BigRational uses java.math.BigInteger (JDK 1.1 and later). * *

* Binary operations (e.g. add, multiply) calculate their results from a * BigRational object ('this') and one [BigRational or long] argument, * returning a new immutable BigRational object. * Both the original object and the argument are left unchanged (hence * immutable). * Unary operations (e.g. negate, invert) calculate their result from the * BigRational object ('this'), returning a new immutable BigRational object. * The original object is left unchanged. * *

* Most operations are precise (i.e. without loss of precision); * exceptions are the conversion methods to limited precision types * (doubleValue, floatValue), rounding (round), * truncation (bigIntegerValue, floor, ceiling, truncate), * as well as obviously the printing methods that include a precision * parameter (toStringDot, toStringDotRelative, toStringExponent). * *

* BigRational doesn't provide a notion of "infinity" ([+-]Infinity) * and "not a number" (NaN); * IEEE 754 floating point Infinity and NaN are rejected (throwing a * NumberFormatException). * Operations such as 0/0 result in an ArithmeticException. * *

* Some commonly used short function names (abs, ceil, div, inv, max, min, * mod, mul, neg, pow, rem, sign, sub, trunc) are additionally defined as * aliases to to the full function names (absolute, ceiling, divide, invert, * maximum, minimum, modulus, multiply, negate, power, remainder, signum, * subtract, truncate). * [This makes the interface somewhat fatter.] * *

* BigRational internally uses private proxy functions for BigInteger * functionality, including scanning and multiplying, to enhance speed * and to realize fast checks for common values (1, 0, etc.). * *

* Constructor samples: * normal rational form, * abbreviated form, * fixed point form, * abbreviated fixed point form, * [exponential] floating point form, * different radixes/bases different from 10, * doubles/floats: *

* BigRational("-21/35"): rational -3/5 * BigRational("/3"): rational 1/3 * BigRational("3.4"): rational 17/5 * BigRational(".7"): 0.7, rational 7/10 * BigRational("-65.4E-3"): -327/5000 * BigRational("f/37", 0x10): 3/11 * BigRational("f.37", 0x10): 3895/256 * BigRational("-dcba.efgh", 23): -46112938320/279841 * BigRational("1011101011010110", 2): 47830 * BigRational(StrictMath.E): 6121026514868073/2251799813685248 * BigRational((float)StrictMath.E): 2850325/1048576 ** *

* Also accepted are denormalized representations such as: *

* BigRational("2.5/-3.5"): -5/7 * BigRational("12.34E-1/-56.78E-1"): -617/2839 ** *

* Printing: * rational form, * fixed point (dot) forms with different absolute precisions * (including negative precision), * with relative precisions, * exponential form, * different radix: *

* BigRational("1234.5678"): "6172839/5000" * BigRational("1234.5678").toStringDot(6): "1234.567800" * BigRational("1234.5678").toStringDot(2): "1234.57" * BigRational("1234.5678").toStringDot(-2): "1200" * BigRational("1234.5678").toStringDotRelative(6): "1234.57" * BigRational("0.00012345678").toStringDotRelative(3): "0.000123" * BigRational("1234.5678").toStringExponent(2): "1.2E3" * BigRational("1011101011010110", 2).toString(0x10): "bad6" ** *

* Usage: * BigRational operations can be conveniently chained * (sample from BigRational internal conversion from IEEE 754 bits): *

* BigRational.valueOf(2).power(exponent).multiply(fraction.add( * BigRational.valueOfUnsigned(mantissa))).multiply(sign); ** *

* The BigRational source and documentation can typically be found at * the author's (Eric Laroche) site, at * http://www.lrdev.com/lr/java/BigRational.java (source) and * http://www.lrdev.com/lr/java/BigRational.html (documentation). * * @author Eric Laroche <laroche@lrdev.com> * @version @(#)$Id: BigRational.java,v 1.3 2010/03/24 20:11:34 laroche Exp $ * */ // @Immutable public class BigRational extends Number implements // note: clone() not so much needed, since the BigRational objects are immutable Cloneable, // note: Comparable