ch.javasoft.math
Class BigFraction

java.lang.Object
  java.lang.Number
      ch.javasoft.math.BigFraction

All Implemented Interfaces:

Serializable, Comparable<BigFraction>

public class BigFraction
extends Number
implements Comparable<BigFraction>, Serializable

The BigFraction is a fractional with numerator and denominator both being BigInteger numbers.

Big integer fractionals are constant, they don't change after instantiation.

See Also:

Serialized Form

Field Summary

static BigFraction	ONE The BigFraction constant one.
static BigFraction	TEN The BigFraction constant ten.
static BigFraction	TWO The BigFraction constant two.
static BigFraction	ZERO The BigFraction constant zero.

Constructor Summary

BigFraction(BigInteger numerator, BigInteger denominator)
Constructor with numerator and denominator.

BigFraction(long numerator, long denominator)
Constructor with numerator and denominator.

BigFraction(String s)
It is recommended to use valueOf(String) instead.

Method Summary

BigFraction	abs() Returns a BigFraction whose value is the absolute value of this BigFraction.
BigFraction	add(BigFraction val) Returns a BigFraction whose value is (this + val).
int	compareTo(BigFraction other) Compares this BigFraction with the specified BigInteger.
BigFraction	divide(BigFraction by) Returns a BigFraction whose value is (this / val) = (this.numerator * by.denominator) / (this.denominator * by.numerator) .
double	doubleValue()
boolean	equals(Object obj) Returns true if and only if the numerator and denominator of the two objects are equal.
boolean	equalsNumerically(BigFraction other) Returns true iff this big integer fraction number is numerically equal to other.
float	floatValue()
static BigFraction	gcd(BigFraction... values) Calculates the greatest common divisor of the specified fraction numbers.
BigFraction	gcd(BigFraction val) Calculates the greatest common divisor of this fraction number and val.
BigInteger	getDenominator() Returns the denominator
BigInteger	getNumerator() Returns the enumerator
int	hashCode() Returns the hash code for this BigFraction.
int	intValue() Converts this BigFraction to an int.
BigFraction	invert() Returns a BigFraction whose value is (1/this).
boolean	isInteger() Returns true if this number represents an integer, that is, if remainder of numerator/denominator equals zero.
boolean	isNegative() Convenience method to check whether this big integer fraction number is negative, say this < 0
boolean	isNonNegative() Convenience method to check whether this big integer fraction number is non-negative, say this >= 0
boolean	isNonPositive() Convenience method to check whether this big integer fraction number is non-positive, say this <= 0
boolean	isNonZero() Convenience method to check whether this big integer fraction number is numerically not equal to zero, say this != 0
boolean	isOne() Convenience method to check whether this big integer fraction number is numerically equal to one.
boolean	isPositive() Convenience method to check whether this big integer fraction number is positive, say this > 0
boolean	isReduced() Returns true if this fraction is already reduced, i.e.
boolean	isZero() Convenience method to check whether this big integer fraction number is numerically equal to zero, say this == 0
long	longValue() Converts this BigFraction to a long.
BigFraction	max(BigFraction with) Returns the maximum of this BigFraction and val.
BigFraction	min(BigFraction with) Returns the minimum of this BigFraction and val.
BigFraction	multiply(BigFraction val) Returns a BigFraction whose value is (this * val).
BigFraction	negate() Returns a BigFraction whose value is (-this).
BigFraction	pow(int exponent) Returns a BigFraction whose value is (thisexponent) == (this.nominatorexponent / this.denominatorexponent).
BigFraction	reduce() Divides denominator and numerator by their greatest common divisor (gcd).
BigFraction	shiftLeft(int n) Returns a BigInteger whose value is (this << n).
BigFraction	shiftRight(int n) Returns a BigFraction whose value is (this >> n).
int	signum() Returns the signum function of this BigFraction.
BigFraction	subtract(BigFraction val) Returns a BigFraction whose value is (this - val).
BigDecimal	toBigDecimal() Returns a BigDecimal whose value is (numerator / denominator), and whose preferred scale is 0; if the exact quotient cannot be represented (because it has a non-terminating decimal expansion) an ArithmeticException is thrown.
BigDecimal	toBigDecimal(int scale, RoundingMode roundingMode) Returns a BigDecimal whose value is (numerator / divisor), and whose scale is as specified.
BigDecimal	toBigDecimal(MathContext mc) Returns a BigDecimal whose value is (numerator / divisor), with rounding according to the context settings.
BigInteger	toBigInteger() Returns a BigInteger whose value is (numerator / denominator), using integer division (no rounding).
BigInteger	toBigInteger(RoundingMode roundingMode) Returns a BigInteger whose value is (numerator / denominator), using decimal division.
static double	toDouble(BigInteger numerator, BigInteger denominator) Converts big integer numerator/denominator arguments to a double value
static float	toFloat(BigInteger numerator, BigInteger denominator) Converts big integer numerator/denominator arguments to a float value
String	toString() Returns a string representation of this BigFraction.
static BigFraction	valueOf(BigDecimal val) Translates a BigDecimal to a BigFraction
static BigFraction	valueOf(BigInteger val) Translates a BigInteger to a BigFraction
static BigFraction	valueOf(BigInteger numerator, BigInteger denominator) Returns a BigFraction from big integer numerator and denominator.
static BigFraction	valueOf(double val) Translates a double to a BigFraction
static BigFraction	valueOf(long val) Translates a long to a BigFraction
static BigFraction	valueOf(long numerator, long denominator) Returns a BigFraction from long numerator and denominator.
static BigFraction	valueOf(Number val) Translates any number into a big integer fractional number.
static BigFraction	valueOf(String s) Translates string representation of a fractional number into a BigFraction instance.
static BigFraction	valueOfAdjusted(double val) Translates a double to a BigFraction, but tries to adjust the value to a nice fractional number, with numerator/denominator as small as possible.

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ZERO

public static final BigFraction ZERO

The BigFraction constant zero.

ONE

public static final BigFraction ONE

The BigFraction constant one.

TWO

public static final BigFraction TWO

The BigFraction constant two.

TEN

public static final BigFraction TEN

The BigFraction constant ten.

Constructor Detail

BigFraction

public BigFraction(long numerator,
                   long denominator)

Constructor with numerator and denominator. See also valueOf(..) methods for various conversions to a big integer fractional.

Parameters:

numerator - numerator of the fraction number

denominator - denominator of the fraction number

BigFraction

public BigFraction(BigInteger numerator,
                   BigInteger denominator)

Constructor with numerator and denominator. See also valueOf(..) methods for various conversions to a big integer fractional.

Parameters:

numerator - numerator of the fraction number

denominator - denominator of the fraction number

BigFraction

public BigFraction(String s)

It is recommended to use valueOf(String) instead. This method is a convenient method mainly for reflection use by frameworks.

Parameters:

s - the string to parse

Method Detail

getNumerator

public BigInteger getNumerator()

Returns the enumerator

getDenominator

public BigInteger getDenominator()

Returns the denominator

doubleValue

public double doubleValue()

Specified by:

doubleValue in class Number

floatValue

public float floatValue()

Specified by:

floatValue in class Number

intValue

public int intValue()

Converts this BigFraction to an int. This conversion is analogous to a narrowing primitive conversion from long to int as defined in the Java Language Specification: if this BigFraction is too big to fit in an int, only the low-order 32 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigFraction value as well as return a result with the opposite sign.

Specified by:

intValue in class Number

Returns:

this BigFraction converted to an int.

longValue

public long longValue()

Converts this BigFraction to a long. This conversion is analogous to a narrowing primitive conversion from long to int as defined in the Java Language Specification: if this BigFraction is too big to fit in a long, only the low-order 64 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigFraction value as well as return a result with the opposite sign.

Specified by:

longValue in class Number

Returns:

this BigFraction converted to a long.

toBigInteger

public BigInteger toBigInteger()

Returns a BigInteger whose value is (numerator / denominator), using integer division (no rounding).

Returns:

numerator / denominator using integer division

toBigInteger

public BigInteger toBigInteger(RoundingMode roundingMode)

Returns a BigInteger whose value is (numerator / denominator), using decimal division. If rounding must be performed to generate an integer result, the specified rounding mode is applied.

Parameters:

roundingMode - Mode rounding mode to apply

Returns:

numerator / denominator using decimal division and rounding if necessary

toBigDecimal

public BigDecimal toBigDecimal()

Returns a BigDecimal whose value is (numerator / denominator), and whose preferred scale is 0; if the exact quotient cannot be represented (because it has a non-terminating decimal expansion) an ArithmeticException is thrown.

Returns:

numerator / denominator

Throws:

ArithmeticException - if the exact quotient does not have a terminating decimal expansion

toBigDecimal

public BigDecimal toBigDecimal(MathContext mc)

Returns a BigDecimal whose value is (numerator / divisor), with rounding according to the context settings.

Parameters:

mc - the context to use.

Returns:

numerator / divisor, rounded as necessary.

Throws:

ArithmeticException - if the result is inexact but the rounding mode is UNNECESSARY or mc.precision == 0 and the quotient has a non-terminating decimal expansion.

toBigDecimal

public BigDecimal toBigDecimal(int scale,
                               RoundingMode roundingMode)

Returns a BigDecimal whose value is (numerator / divisor), and whose scale is as specified. If rounding must be performed to generate a result with the specified scale, the specified rounding mode is applied.

Parameters:

scale - scale of the BigDecimal quotient to be returned.

roundingMode - rounding mode to apply.

Returns:

this / divisor

Throws:

ArithmeticException - if divisor is zero, roundingMode==RoundingMode.UNNECESSARY and the specified scale is insufficient to represent the result of the division exactly.

hashCode

public int hashCode()

Returns the hash code for this BigFraction.

Overrides:

hashCode in class Object

Returns:

hash code for this BigFraction.

equals

public boolean equals(Object obj)

Returns true if and only if the numerator and denominator of the two objects are equal. For numerical equality, use equalsNumerically(BigFraction) or compareTo(BigFraction)

Overrides:

equals in class Object

compareTo

public int compareTo(BigFraction other)

Compares this BigFraction with the specified BigInteger. This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=). The suggested idiom for performing these comparisons is: (x.compareTo(y) <op> 0), where <op> is one of the six comparison operators.

Specified by:

compareTo in interface Comparable<BigFraction>

Parameters:

other - fractional number to which this fraction is to be compared.

Returns:

-1, 0 or 1 as this fraction is numerically less than, equal to, or greater than val.

signum

public int signum()

Returns the signum function of this BigFraction.

Returns:

-1, 0 or 1 as the value of this fraction is negative, zero or positive.

abs

public BigFraction abs()

Returns a BigFraction whose value is the absolute value of this BigFraction. The fractional number is not reduced, that is, gcd(nominator, denominator) might be != 1.

Returns:

abs(this)

negate

public BigFraction negate()

Returns a BigFraction whose value is (-this). The fractional number is not reduced, that is, gcd(nominator, denominator) might be != 1.

Returns:

-this

invert

public BigFraction invert()

Returns a BigFraction whose value is (1/this). The fractional number is not reduced, that is, gcd(nominator, denominator) might be != 1.

The resulting denominator is guaranteed to be non-negative.

Returns:

1/this

add

public BigFraction add(BigFraction val)

Returns a BigFraction whose value is (this + val). The fractional number is not reduced, that is, gcd(nominator, denominator) might be != 1.

Parameters:

val - value to be added to this BigFraction.

Returns:

this + val

subtract

public BigFraction subtract(BigFraction val)

Returns a BigFraction whose value is (this - val). The fractional number is not reduced, that is, gcd(nominator, denominator) might be != 1.

Parameters:

val - value to be subtracted from this BigFraction.

Returns:

this - val

multiply

public BigFraction multiply(BigFraction val)

Returns a BigFraction whose value is (this * val). The fractional number is not reduced, that is, gcd(nominator, denominator) might be != 1.

Parameters:

val - value to be multiplied by this BigFraction.

Returns:

this * val

divide

public BigFraction divide(BigFraction by)

Returns a BigFraction whose value is (this / val) = (this.numerator * by.denominator) / (this.denominator * by.numerator) . The fractional number is not reduced, that is, gcd(nominator, denominator) might be != 1.

Parameters:

by - value by which this BigFraction is to be divided.

Returns:

this / val

Throws:

ArithmeticException - val==0

pow

public BigFraction pow(int exponent)

Returns a BigFraction whose value is (this^exponent) == (this.nominator^exponent / this.denominator^exponent). Note that exponent is an integer rather than a BigFraction. The fractional number is not reduced, that is, gcd(nominator, denominator) might be != 1.

Parameters:

exponent - exponent to which this BigFraction is to be raised.

Returns:

this^exponent

Throws:

ArithmeticException - exponent is negative and this is zero. (This would cause a division by zero.)

shiftLeft

public BigFraction shiftLeft(int n)

Returns a BigInteger whose value is (this << n). The shift distance, n, may be negative, in which case this method performs a right shift. (Computes this * 2ⁿ.)

To achieve that the resulting fraction number is smallest possible, the denominator is shifted to the right as far as possible. The remaining positions are left shifts of the numerator.

Parameters:

n - shift distance, in bits.

Returns:

this << n

See Also:

shiftRight(int)

shiftRight

public BigFraction shiftRight(int n)

Returns a BigFraction whose value is (this >> n). The shift distance, n, may be negative, in which case this method performs a left shift. (Computes this / 2ⁿ.)

To achieve that the resulting fraction number is smallest possible, the numerator is shifted to the right as far as possible. The remaining positions are left shifts of the denominator.

Parameters:

n - shift distance, in bits.

Returns:

this >> n

See Also:

shiftLeft(int)

max

public BigFraction max(BigFraction with)

Returns the maximum of this BigFraction and val.

Parameters:

with - value with which the maximum is to be computed.

Returns:

the BigFraction whose value is the greater of this and val. If they are equal, either may be returned.

min

public BigFraction min(BigFraction with)

Returns the minimum of this BigFraction and val.

Parameters:

with - value with which the minimum is to be computed.

Returns:

the BigFraction whose value is the lesser of this and val. If they are equal, either may be returned.

reduce

public BigFraction reduce()

Divides denominator and numerator by their greatest common divisor (gcd). The denominator of the returned integer fractional will always be positive. If the numerator is 0, the denominator will be one.

See Also:

isReduced()

gcd

public BigFraction gcd(BigFraction val)

Calculates the greatest common divisor of this fraction number and val. The gcd of two fraction numbers is gcd of numerators divided by gcd of deniminators.

If both numbers are negative, the resulting gcd is also negative. If both numbers are zero, the result is zero. Otherwise, the result is positive.

Parameters:

val - value with which the gcd is to be computed

Returns:

sgn * gcd(this.numerator, val.numberator) / gcd(this.denominator, val.denominator)

gcd

public static BigFraction gcd(BigFraction... values)

Calculates the greatest common divisor of the specified fraction numbers. The gcd of fraction numbers is gcd of numerators divided by gcd of deniminators.

This method might be useful to scale down a vector of fraction numbers.

If all numbers are negative, the resulting gcd is also negative. If all numbers are zero, the result is zero. Otherwise, the result is positive.

Parameters:

values - values for which the gcd is to be computed

Returns:

sgn * gcd(values[*].numberator) / gcd(values[*].denominator)

isZero

public boolean isZero()

Convenience method to check whether this big integer fraction number is numerically equal to zero, say this == 0

See Also:

signum(), compareTo(BigFraction), equalsNumerically(BigFraction)

isReduced

public boolean isReduced()

Returns true if this fraction is already reduced, i.e. if the greatest common divisor of numerator and denominator is one.

See Also:

reduce()

isNonZero

public boolean isNonZero()

Convenience method to check whether this big integer fraction number is numerically not equal to zero, say this != 0

See Also:

signum(), compareTo(BigFraction), equalsNumerically(BigFraction)

isNegative

public boolean isNegative()

Convenience method to check whether this big integer fraction number is negative, say this < 0

See Also:

signum(), compareTo(BigFraction)

isNonNegative

public boolean isNonNegative()

Convenience method to check whether this big integer fraction number is non-negative, say this >= 0

See Also:

signum(), compareTo(BigFraction)

isPositive

public boolean isPositive()

Convenience method to check whether this big integer fraction number is positive, say this > 0

See Also:

signum(), compareTo(BigFraction)

isNonPositive

public boolean isNonPositive()

Convenience method to check whether this big integer fraction number is non-positive, say this <= 0

See Also:

signum(), compareTo(BigFraction)

isOne

public boolean isOne()

Convenience method to check whether this big integer fraction number is numerically equal to one. This is true if numerator and denominator are numerically equal.

See Also:

equalsNumerically(BigFraction), compareTo(BigFraction)

isInteger

public boolean isInteger()

Returns true if this number represents an integer, that is, if remainder of numerator/denominator equals zero.

equalsNumerically

public boolean equalsNumerically(BigFraction other)

Returns true iff this big integer fraction number is numerically equal to other. Note that equals(Object) only returns true if both nominator and denominator are equal, and false otherwise, even if both fractional numbers represent the same numeric value.

See Also:

equals(Object)

toString

public String toString()

Returns a string representation of this BigFraction. If the denominator is 1, the numerator's string representation is returned. Otherwise, numerator/denominator is returned.

Strings returned here are parsable by valueOf(String)

Overrides:

toString in class Object

valueOf

public static BigFraction valueOf(String s)
                           throws NumberFormatException

Translates string representation of a fractional number into a BigFraction instance. Valid strings are those of BigInteger and BigDecimal, or strings of the form numerator/denominator with two big integers.

Parameters:

s - the string representation of a big integer fraction to parse

Throws:

NumberFormatException - val is not a valid representation of a BigFraction.

See Also:

BigInteger.BigInteger(String), BigDecimal.BigDecimal(String)

valueOf

public static BigFraction valueOf(BigInteger val)

Translates a BigInteger to a BigFraction

Parameters:

val - the big integer to translate

Returns:

the BigFraction representing val

valueOf

public static BigFraction valueOf(BigDecimal val)

Translates a BigDecimal to a BigFraction

Parameters:

val - the big decimal to translate

Returns:

the BigFraction representing val

valueOf

public static BigFraction valueOf(long val)

Translates a long to a BigFraction

Parameters:

val - the long to translate

Returns:

the BigFraction representing val

See Also:

BigDecimal.valueOf(long)

valueOf

public static BigFraction valueOf(double val)

Translates a double to a BigFraction

Parameters:

val - the double to translate

Returns:

the BigFraction representing val

See Also:

BigDecimal.valueOf(double)

valueOf

public static BigFraction valueOf(long numerator,
                                  long denominator)

Returns a BigFraction from long numerator and denominator. This is the same as BigFraction(long, long), but possibly, some caching is used for commonly used values.

Parameters:

numerator - the numerator for the fraction number to be created

denominator - the denominator for the fraction number to be created

Returns:

the BigFraction representing numerator/denominator

See Also:

BigFraction(long, long)

valueOf

public static BigFraction valueOf(BigInteger numerator,
                                  BigInteger denominator)

Returns a BigFraction from big integer numerator and denominator. This is the same as BigFraction(BigInteger, BigInteger), but possibly, some caching is used for commonly used values.

Parameters:

numerator - the numerator for the fraction number to be created

denominator - the denominator for the fraction number to be created

Returns:

the BigFraction representing numerator/denominator

See Also:

BigFraction(BigInteger, BigInteger)

valueOf

public static BigFraction valueOf(Number val)

Translates any number into a big integer fractional number. The most appropriate valueOf(..) method is used. If no better method is found, valueOf(String) is invoked after converting the given number to a string value.

This method is guaranteed to work for java number types, including BigInteger and BigDecimal.

valueOfAdjusted

public static BigFraction valueOfAdjusted(double val)

Translates a double to a BigFraction, but tries to adjust the value to a nice fractional number, with numerator/denominator as small as possible. This method is especially useful for double values representing 1/3, 1/6 etc. but it works also fine with any/10^i.

Parameters:

val - the double to translate

Returns:

the BigFraction representing val

Throws:

ArithmeticException - if the value is NaN or infinite

See Also:

valueOf(double)

toDouble

public static double toDouble(BigInteger numerator,
                              BigInteger denominator)

Converts big integer numerator/denominator arguments to a double value

toFloat

public static float toFloat(BigInteger numerator,
                            BigInteger denominator)

Converts big integer numerator/denominator arguments to a float value