Class BigFraction
- java.lang.Object
-
- java.lang.Number
-
- org.apache.commons.numbers.fraction.BigFraction
-
- All Implemented Interfaces:
Serializable,Comparable<BigFraction>,Addition<BigFraction>,Multiplication<BigFraction>,NativeOperators<BigFraction>
public final class BigFraction extends Number implements Comparable<BigFraction>, NativeOperators<BigFraction>, Serializable
Representation of a rational number using arbitrary precision.The number is expressed as the quotient
p/qof twoBigIntegers, a numeratorpand a non-zero denominatorq.This class is immutable. Rational number
- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static BigFractionONEA fraction representing "1".static BigFractionZEROA fraction representing "0".
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description BigFractionabs()Returns the absolute value of this fraction.BigFractionadd(int value)Adds the specifiedvalueto this fraction, returning the result in reduced form.BigFractionadd(long value)Adds the specifiedvalueto this fraction, returning the result in reduced form.BigFractionadd(BigInteger value)Adds the specifiedvalueto this fraction, returning the result in reduced form.BigFractionadd(BigFraction value)Adds the specifiedvalueto this fraction, returning the result in reduced form.BigDecimalbigDecimalValue()Returns theBigDecimalrepresentation of this fraction.BigDecimalbigDecimalValue(int scale, RoundingMode roundingMode)Returns theBigDecimalrepresentation of this fraction.BigDecimalbigDecimalValue(RoundingMode roundingMode)Returns theBigDecimalrepresentation of this fraction.intcompareTo(BigFraction other)Compares this object with the specified object for order using the signed magnitude.BigFractiondivide(int value)Divide this fraction by the passedvalue, returning the result in reduced form.BigFractiondivide(long value)Divide this fraction by the passedvalue, returning the result in reduced form.BigFractiondivide(BigInteger value)Divide this fraction by the passedvalue, returning the result in reduced form.BigFractiondivide(BigFraction value)Divide this fraction by the passedvalue, returning the result in reduced form.doubledoubleValue()Returns thedoublevalue closest to this fraction.booleanequals(Object other)Test for equality with another object.floatfloatValue()Returns thefloatvalue closest to this fraction.static BigFractionfrom(double value)Create a fraction given the double value.static BigFractionfrom(double value, double epsilon, int maxIterations)Create a fraction given the double value and maximum error allowed.static BigFractionfrom(double value, int maxDenominator)Create a fraction given the double value and maximum denominator.BigIntegergetDenominator()Access the denominator as aBigInteger.intgetDenominatorAsInt()Access the denominator as anint.longgetDenominatorAsLong()Access the denominator as along.BigIntegergetNumerator()Access the numerator as aBigInteger.intgetNumeratorAsInt()Access the numerator as anint.longgetNumeratorAsLong()Access the numerator as along.inthashCode()intintValue()Returns the whole number part of the fraction.booleanisOne()booleanisZero()longlongValue()Returns the whole number part of the fraction.BigFractionmultiply(int value)Multiply this fraction by the passedvalue, returning the result in reduced form.BigFractionmultiply(long value)Multiply this fraction by the passedvalue, returning the result in reduced form.BigFractionmultiply(BigInteger value)Multiply this fraction by the passedvalue, returning the result in reduced form.BigFractionmultiply(BigFraction value)Multiply this fraction by the passedvalue, returning the result in reduced form.BigFractionnegate()static BigFractionof(int num)Create a fraction given the numerator.static BigFractionof(int num, int den)Create a fraction given the numerator and denominator.static BigFractionof(long num)Create a fraction given the numerator.static BigFractionof(long num, long den)Create a fraction given the numerator and denominator.static BigFractionof(BigInteger num)Create a fraction given the numerator.static BigFractionof(BigInteger num, BigInteger den)Create a fraction given the numerator and denominator.BigFractionone()static BigFractionparse(String s)Returns aBigFractioninstance representing the specified strings.BigFractionpow(int exponent)Returns aBigFractionwhose value isthisexponent, returning the result in reduced form.BigFractionreciprocal()intsignum()Retrieves the sign of this fraction.BigFractionsubtract(int value)Subtracts the specifiedvaluefrom this fraction, returning the result in reduced form.BigFractionsubtract(long value)Subtracts the specifiedvaluefrom this fraction, returning the result in reduced form.BigFractionsubtract(BigInteger value)Subtracts the specifiedvaluefrom this fraction, returning the result in reduced form.BigFractionsubtract(BigFraction value)Subtracts the specifiedvaluefrom this fraction, returning the result in reduced form.StringtoString()Returns theStringrepresenting this fraction.BigFractionzero()-
Methods inherited from class java.lang.Number
byteValue, shortValue
-
-
-
-
Field Detail
-
ZERO
public static final BigFraction ZERO
A fraction representing "0".
-
ONE
public static final BigFraction ONE
A fraction representing "1".
-
-
Method Detail
-
from
public static BigFraction from(double value)
Create a fraction given the double value.This factory method behaves differently to the method
from(double, double, int). It converts the double value exactly, considering its internal bits representation. This works for all values except NaN and infinities and does not requires any loop or convergence threshold.Since this conversion is exact and since double numbers are sometimes approximated, the fraction created may seem strange in some cases. For example, calling
from(1.0 / 3.0)does not create the fraction \( \frac{1}{3} \), but the fraction \( \frac{6004799503160661}{18014398509481984} \) because the double number passed to the method is not exactly \( \frac{1}{3} \) (which cannot be represented exactly in IEEE754).- Parameters:
value- Value to convert to a fraction.- Returns:
- a new instance.
- Throws:
IllegalArgumentException- if the givenvalueis NaN or infinite.- See Also:
from(double,double,int)
-
from
public static BigFraction from(double value, double epsilon, int maxIterations)
Create a fraction given the double value and maximum error allowed.References:
- Continued Fraction equations (11) and (22)-(26)
- Parameters:
value- Value to convert to a fraction.epsilon- Maximum error allowed. The resulting fraction is withinepsilonofvalue, in absolute terms.maxIterations- Maximum number of convergents.- Returns:
- a new instance.
- Throws:
IllegalArgumentException- if the givenvalueis NaN or infinite;epsilonis not positive; ormaxIterations < 1.ArithmeticException- if the continued fraction failed to converge.
-
from
public static BigFraction from(double value, int maxDenominator)
Create a fraction given the double value and maximum denominator.References:
- Continued Fraction equations (11) and (22)-(26)
Note: The magnitude of the
maxDenominatoris used allowing use ofInteger.MIN_VALUEfor a supported maximum denominator of 231.- Parameters:
value- Value to convert to a fraction.maxDenominator- Maximum allowed value for denominator.- Returns:
- a new instance.
- Throws:
IllegalArgumentException- if the givenvalueis NaN or infinite ormaxDenominatoris zero.ArithmeticException- if the continued fraction failed to converge.
-
of
public static BigFraction of(int num)
Create a fraction given the numerator. The denominator is1.- Parameters:
num- the numerator.- Returns:
- a new instance.
-
of
public static BigFraction of(long num)
Create a fraction given the numerator. The denominator is1.- Parameters:
num- Numerator.- Returns:
- a new instance.
-
of
public static BigFraction of(BigInteger num)
Create a fraction given the numerator. The denominator is1.- Parameters:
num- Numerator.- Returns:
- a new instance.
- Throws:
NullPointerException- if numerator is null.
-
of
public static BigFraction of(int num, int den)
Create a fraction given the numerator and denominator. The fraction is reduced to lowest terms.- Parameters:
num- Numerator.den- Denominator.- Returns:
- a new instance.
- Throws:
ArithmeticException- ifdenis zero.
-
of
public static BigFraction of(long num, long den)
Create a fraction given the numerator and denominator. The fraction is reduced to lowest terms.- Parameters:
num- Numerator.den- Denominator.- Returns:
- a new instance.
- Throws:
ArithmeticException- ifdenis zero.
-
of
public static BigFraction of(BigInteger num, BigInteger den)
Create a fraction given the numerator and denominator. The fraction is reduced to lowest terms.- Parameters:
num- Numerator.den- Denominator.- Returns:
- a new instance.
- Throws:
NullPointerException- if numerator or denominator are null.ArithmeticException- if the denominator is zero.
-
parse
public static BigFraction parse(String s)
Returns aBigFractioninstance representing the specified strings.If
sisnull, then aNullPointerExceptionis thrown.The string must be in a format compatible with that produced by
BigFraction.toString(). The format expects an integer optionally followed by a'/'character and and second integer. Leading and trailing spaces are allowed around each numeric part. Each numeric part is parsed usingBigInteger(String). The parts are interpreted as the numerator and optional denominator of the fraction. If absent the denominator is assumed to be "1".Examples of valid strings and the equivalent
BigFractionare shown below:"0" = BigFraction.of(0) "42" = BigFraction.of(42) "0 / 1" = BigFraction.of(0, 1) "1 / 3" = BigFraction.of(1, 3) "-4 / 13" = BigFraction.of(-4, 13)
Note: The fraction is returned in reduced form and the numerator and denominator may not match the values in the input string. For this reason the result of
BigFraction.parse(s).toString().equals(s)may not betrue.- Parameters:
s- String representation.- Returns:
- an instance.
- Throws:
NullPointerException- if the string is null.NumberFormatException- if the string does not contain a parsable fraction.- See Also:
BigInteger(String),toString()
-
zero
public BigFraction zero()
- Specified by:
zeroin interfaceAddition<BigFraction>
-
isZero
public boolean isZero()
- Specified by:
isZeroin interfaceAddition<BigFraction>
-
one
public BigFraction one()
- Specified by:
onein interfaceMultiplication<BigFraction>
-
isOne
public boolean isOne()
- Specified by:
isOnein interfaceMultiplication<BigFraction>
-
getNumerator
public BigInteger getNumerator()
Access the numerator as aBigInteger.- Returns:
- the numerator as a
BigInteger.
-
getNumeratorAsInt
public int getNumeratorAsInt()
Access the numerator as anint.- Returns:
- the numerator as an
int.
-
getNumeratorAsLong
public long getNumeratorAsLong()
Access the numerator as along.- Returns:
- the numerator as a
long.
-
getDenominator
public BigInteger getDenominator()
Access the denominator as aBigInteger.- Returns:
- the denominator as a
BigInteger.
-
getDenominatorAsInt
public int getDenominatorAsInt()
Access the denominator as anint.- Returns:
- the denominator as an
int.
-
getDenominatorAsLong
public long getDenominatorAsLong()
Access the denominator as along.- Returns:
- the denominator as a
long.
-
signum
public int signum()
Retrieves the sign of this fraction.- Returns:
- -1 if the value is strictly negative, 1 if it is strictly positive, 0 if it is 0.
-
abs
public BigFraction abs()
Returns the absolute value of this fraction.- Returns:
- the absolute value.
-
negate
public BigFraction negate()
- Specified by:
negatein interfaceAddition<BigFraction>
-
reciprocal
public BigFraction reciprocal()
Raises an exception if the fraction is equal to zero.
- Specified by:
reciprocalin interfaceMultiplication<BigFraction>- Throws:
ArithmeticException- if the current numerator iszero
-
doubleValue
public double doubleValue()
Returns thedoublevalue closest to this fraction.- Specified by:
doubleValuein classNumber- Returns:
- the fraction as a
double.
-
floatValue
public float floatValue()
Returns thefloatvalue closest to this fraction.- Specified by:
floatValuein classNumber- Returns:
- the fraction as a
double.
-
intValue
public int intValue()
Returns the whole number part of the fraction.
-
longValue
public long longValue()
Returns the whole number part of the fraction.
-
bigDecimalValue
public BigDecimal bigDecimalValue()
Returns theBigDecimalrepresentation of this fraction. This calculates the fraction as numerator divided by denominator.- Returns:
- the fraction as a
BigDecimal. - Throws:
ArithmeticException- if the exact quotient does not have a terminating decimal expansion.- See Also:
BigDecimal
-
bigDecimalValue
public BigDecimal bigDecimalValue(RoundingMode roundingMode)
Returns theBigDecimalrepresentation of this fraction. This calculates the fraction as numerator divided by denominator following the passed rounding mode.- Parameters:
roundingMode- Rounding mode to apply.- Returns:
- the fraction as a
BigDecimal. - See Also:
BigDecimal
-
bigDecimalValue
public BigDecimal bigDecimalValue(int scale, RoundingMode roundingMode)
Returns theBigDecimalrepresentation of this fraction. This calculates the fraction as numerator divided by denominator following the passed scale and rounding mode.- Parameters:
scale- scale of theBigDecimalquotient to be returned. seeBigDecimalfor more information.roundingMode- Rounding mode to apply.- Returns:
- the fraction as a
BigDecimal. - Throws:
ArithmeticException- ifroundingMode==RoundingMode.UNNECESSARYand the specified scale is insufficient to represent the result of the division exactly.- See Also:
BigDecimal
-
add
public BigFraction add(int value)
Adds the specifiedvalueto this fraction, returning the result in reduced form.- Parameters:
value- Value to add.- Returns:
this + value.
-
add
public BigFraction add(long value)
Adds the specifiedvalueto this fraction, returning the result in reduced form.- Parameters:
value- Value to add.- Returns:
this + value.
-
add
public BigFraction add(BigInteger value)
Adds the specifiedvalueto this fraction, returning the result in reduced form.- Parameters:
value- Value to add.- Returns:
this + value.
-
add
public BigFraction add(BigFraction value)
Adds the specifiedvalueto this fraction, returning the result in reduced form.- Specified by:
addin interfaceAddition<BigFraction>- Parameters:
value- Value to add.- Returns:
this + value.
-
subtract
public BigFraction subtract(int value)
Subtracts the specifiedvaluefrom this fraction, returning the result in reduced form.- Parameters:
value- Value to subtract.- Returns:
this - value.
-
subtract
public BigFraction subtract(long value)
Subtracts the specifiedvaluefrom this fraction, returning the result in reduced form.- Parameters:
value- Value to subtract.- Returns:
this - value.
-
subtract
public BigFraction subtract(BigInteger value)
Subtracts the specifiedvaluefrom this fraction, returning the result in reduced form.- Parameters:
value- Value to subtract.- Returns:
this - value.
-
subtract
public BigFraction subtract(BigFraction value)
Subtracts the specifiedvaluefrom this fraction, returning the result in reduced form.- Specified by:
subtractin interfaceNativeOperators<BigFraction>- Parameters:
value- Value to subtract.- Returns:
this - value.
-
multiply
public BigFraction multiply(int value)
Multiply this fraction by the passedvalue, returning the result in reduced form.- Specified by:
multiplyin interfaceNativeOperators<BigFraction>- Parameters:
value- Value to multiply by.- Returns:
this * value.
-
multiply
public BigFraction multiply(long value)
Multiply this fraction by the passedvalue, returning the result in reduced form.- Parameters:
value- Value to multiply by.- Returns:
this * value.
-
multiply
public BigFraction multiply(BigInteger value)
Multiply this fraction by the passedvalue, returning the result in reduced form.- Parameters:
value- Value to multiply by.- Returns:
this * value.
-
multiply
public BigFraction multiply(BigFraction value)
Multiply this fraction by the passedvalue, returning the result in reduced form.- Specified by:
multiplyin interfaceMultiplication<BigFraction>- Parameters:
value- Value to multiply by.- Returns:
this * value.
-
divide
public BigFraction divide(int value)
Divide this fraction by the passedvalue, returning the result in reduced form.- Parameters:
value- Value to divide by- Returns:
this / value.- Throws:
ArithmeticException- if the value to divide by is zero
-
divide
public BigFraction divide(long value)
Divide this fraction by the passedvalue, returning the result in reduced form.- Parameters:
value- Value to divide by- Returns:
this / value.- Throws:
ArithmeticException- if the value to divide by is zero
-
divide
public BigFraction divide(BigInteger value)
Divide this fraction by the passedvalue, returning the result in reduced form.- Parameters:
value- Value to divide by- Returns:
this / value.- Throws:
ArithmeticException- if the value to divide by is zero
-
divide
public BigFraction divide(BigFraction value)
Divide this fraction by the passedvalue, returning the result in reduced form.- Specified by:
dividein interfaceNativeOperators<BigFraction>- Parameters:
value- Value to divide by- Returns:
this / value.- Throws:
ArithmeticException- if the value to divide by is zero
-
pow
public BigFraction pow(int exponent)
Returns aBigFractionwhose value isthisexponent, returning the result in reduced form.- Specified by:
powin interfaceNativeOperators<BigFraction>- Parameters:
exponent- exponent to which thisBigFractionis to be raised.- Returns:
thisexponent.- Throws:
ArithmeticException- if the intermediate result would overflow.
-
toString
public String toString()
Returns theStringrepresenting this fraction. Uses:"0"ifnumeratoris zero."numerator"ifdenominatoris one."numerator / denominator"for all other cases.
-
compareTo
public int compareTo(BigFraction other)
Compares this object with the specified object for order using the signed magnitude.- Specified by:
compareToin interfaceComparable<BigFraction>- Parameters:
other-- Returns:
-
equals
public boolean equals(Object other)
Test for equality with another object. If the other object is aFractionthen a comparison is made of the sign and magnitude; otherwisefalseis returned.
-
-