Package org.apache.commons.numbers.fraction

Class Fraction

java.lang.Object

java.lang.Number

org.apache.commons.numbers.fraction.Fraction

All Implemented Interfaces:

Serializable, Comparable<Fraction>, Addition<Fraction>, Multiplication<Fraction>, NativeOperators<Fraction>

public final class Fraction
extends Number
implements Comparable<Fraction>, NativeOperators<Fraction>, Serializable

Representation of a rational number.

The number is expressed as the quotient p/q of two 32-bit integers, a numerator p and a non-zero denominator q.

This class is immutable. Rational number

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final Fraction	ONE	A fraction representing "1".
static final Fraction	ZERO	A fraction representing "0".

Method Summary

Modifier and Type	Method	Description
Fraction	abs()	Returns the absolute value of this fraction.
Fraction	add(int value)	Adds the specified value to this fraction, returning the result in reduced form.
Fraction	add(Fraction value)	Adds the specified value to this fraction, returning the result in reduced form.
int	compareTo(Fraction other)	Compares this object with the specified object for order using the signed magnitude.
Fraction	divide(int value)	Divide this fraction by the passed value, returning the result in reduced form.
Fraction	divide(Fraction value)	Divide this fraction by the passed value, returning the result in reduced form.
double	doubleValue()	Returns the double value closest to this fraction.
boolean	equals(Object other)	Test for equality with another object.
float	floatValue()	Returns the float value closest to this fraction.
static Fraction	from(double value)	Create a fraction given the double value.
static Fraction	from(double value, double epsilon, int maxIterations)	Create a fraction given the double value and maximum error allowed.
static Fraction	from(double value, int maxDenominator)	Create a fraction given the double value and maximum denominator.
int	getDenominator()	Access the denominator as an int.
int	getNumerator()	Access the numerator as an int.
int	hashCode()
int	intValue()	Returns the whole number part of the fraction.
boolean	isOne()	Check if this is a neutral element of multiplication, i.e.
boolean	isZero()	Check if this is a neutral element of addition, i.e.
long	longValue()	Returns the whole number part of the fraction.
Fraction	multiply(int value)	Multiply this fraction by the passed value, returning the result in reduced form.
Fraction	multiply(Fraction value)	Multiply this fraction by the passed value, returning the result in reduced form.
Fraction	negate()	Additive inverse.
static Fraction	of(int num)	Create a fraction given the numerator.
static Fraction	of(int num, int den)	Create a fraction given the numerator and denominator.
Fraction	one()	Identity element.
static Fraction	parse(String s)	Returns a Fraction instance representing the specified string s.
Fraction	pow(int exponent)	Returns a Fraction whose value is thisexponent, returning the result in reduced form.
Fraction	reciprocal()	Multiplicative inverse.
int	signum()	Retrieves the sign of this fraction.
Fraction	subtract(int value)	Subtracts the specified value from this fraction, returning the result in reduced form.
Fraction	subtract(Fraction value)	Subtracts the specified value from this fraction, returning the result in reduced form.
String	toString()	Returns the String representing this fraction.
Fraction	zero()	Identity element.

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 Details

ZERO

public static final Fraction ZERO

A fraction representing "0".

ONE

public static final Fraction ONE

A fraction representing "1".

Method Details

from

public static Fraction from(double value)

Create a fraction given the double value.

Parameters:

value - Value to convert to a fraction.

Returns:

a new instance.

Throws:

IllegalArgumentException - if the given value is NaN or infinite.

ArithmeticException - if the continued fraction failed to converge.

from

public static Fraction 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 within epsilon of value, in absolute terms.

maxIterations - Maximum number of convergents.

Returns:

a new instance.

Throws:

IllegalArgumentException - if the given value is NaN or infinite; epsilon is not positive; or maxIterations < 1.

ArithmeticException - if the continued fraction failed to converge.

from

public static Fraction 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 maxDenominator is used allowing use of Integer.MIN_VALUE for a supported maximum denominator of 2³¹.

Parameters:

value - Value to convert to a fraction.

maxDenominator - Maximum allowed value for denominator.

Returns:

a new instance.

Throws:

IllegalArgumentException - if the given value is NaN or infinite or maxDenominator is zero.

ArithmeticException - if the continued fraction failed to converge.

of

public static Fraction of(int num)

Create a fraction given the numerator. The denominator is 1.

Parameters:

num - Numerator.

Returns:

a new instance.

of

public static Fraction 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 - if the denominator is zero.

parse

public static Fraction parse(String s)

Returns a Fraction instance representing the specified string s.

If s is null, then a NullPointerException is thrown.

The string must be in a format compatible with that produced by Fraction.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 using Integer.parseInt(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 Fraction are shown below:

 "0"                 = Fraction.of(0)
 "42"                = Fraction.of(42)
 "0 / 1"             = Fraction.of(0, 1)
 "1 / 3"             = Fraction.of(1, 3)
 "-4 / 13"           = Fraction.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 Fraction.parse(s).toString().equals(s) may not be true.

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:

• Integer.parseInt(String)
• toString()

zero

public Fraction zero()

Description copied from interface: Addition

Identity element.

Specified by:

zero in interface Addition<Fraction>

Returns:

the field element such that for all a, zero().add(a).equals(a) is true.

isZero

public boolean isZero()

Check if this is a neutral element of addition, i.e. this.add(a) returns a or an element representing the same value as a.

The default implementation calls equals(zero()). Implementations may want to employ more a efficient method. This may even be required if an implementation has multiple representations of zero and its equals method differentiates between them.

Specified by:

isZero in interface Addition<Fraction>

Returns:

true if this is a neutral element of addition.

See Also:

• Addition.zero()

one

public Fraction one()

Description copied from interface: Multiplication

Identity element.

Specified by:

one in interface Multiplication<Fraction>

Returns:

the field element such that for all a, one().multiply(a).equals(a) is true.

isOne

public boolean isOne()

Check if this is a neutral element of multiplication, i.e. this.multiply(a) returns a or an element representing the same value as a.

The default implementation calls equals(one()). Implementations may want to employ more a efficient method. This may even be required if an implementation has multiple representations of one and its equals method differentiates between them.

Specified by:

isOne in interface Multiplication<Fraction>

Returns:

true if this is a neutral element of multiplication.

See Also:

• Multiplication.one()

getNumerator

public int getNumerator()

Access the numerator as an int.

Returns:

the numerator as an int.

getDenominator

public int getDenominator()

Access the denominator as an int.

Returns:

the denominator as an int.

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 Fraction abs()

Returns the absolute value of this fraction.

Returns:

the absolute value.

negate

public Fraction negate()

Description copied from interface: Addition

Additive inverse.

Specified by:

negate in interface Addition<Fraction>

Returns:

-this.

reciprocal

public Fraction reciprocal()

Multiplicative inverse.

Raises an exception if the fraction is equal to zero.

Specified by:

reciprocal in interface Multiplication<Fraction>

Returns:

this-1.

Throws:

ArithmeticException - if the current numerator is zero

doubleValue

public double doubleValue()

Returns the double value closest to this fraction. This calculates the fraction as numerator divided by denominator.

Specified by:

doubleValue in class Number

Returns:

the fraction as a double.

floatValue

public float floatValue()

Returns the float value closest to this fraction. This calculates the fraction as numerator divided by denominator.

Specified by:

floatValue in class Number

Returns:

the fraction as a float.

intValue

public int intValue()

Returns the whole number part of the fraction.

Specified by:

intValue in class Number

Returns:

the largest int value that is not larger than this fraction.

longValue

public long longValue()

Returns the whole number part of the fraction.

Specified by:

longValue in class Number

Returns:

the largest long value that is not larger than this fraction.

add

public Fraction add(int value)

Adds the specified value to this fraction, returning the result in reduced form.

Parameters:

value - Value to add.

Returns:

this + value.

Throws:

ArithmeticException - if the resulting numerator cannot be represented in an int.

add

public Fraction add(Fraction value)

Adds the specified value to this fraction, returning the result in reduced form.

Specified by:

add in interface Addition<Fraction>

Parameters:

value - Value to add.

Returns:

this + value.

Throws:

ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

subtract

public Fraction subtract(int value)

Subtracts the specified value from this fraction, returning the result in reduced form.

Parameters:

value - Value to subtract.

Returns:

this - value.

Throws:

ArithmeticException - if the resulting numerator cannot be represented in an int.

subtract

public Fraction subtract(Fraction value)

Subtracts the specified value from this fraction, returning the result in reduced form.

Specified by:

subtract in interface NativeOperators<Fraction>

Parameters:

value - Value to subtract.

Returns:

this - value.

Throws:

ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

multiply

public Fraction multiply(int value)

Multiply this fraction by the passed value, returning the result in reduced form.

Specified by:

multiply in interface NativeOperators<Fraction>

Parameters:

value - Value to multiply by.

Returns:

this * value.

Throws:

ArithmeticException - if the resulting numerator cannot be represented in an int.

multiply

public Fraction multiply(Fraction value)

Multiply this fraction by the passed value, returning the result in reduced form.

Specified by:

multiply in interface Multiplication<Fraction>

Parameters:

value - Value to multiply by.

Returns:

this * value.

Throws:

ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

divide

public Fraction divide(int value)

Divide this fraction by the passed value, 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 or if the resulting numerator or denominator cannot be represented by an int.

divide

public Fraction divide(Fraction value)

Divide this fraction by the passed value, returning the result in reduced form.

Specified by:

divide in interface NativeOperators<Fraction>

Parameters:

value - Value to divide by

Returns:

this / value.

Throws:

ArithmeticException - if the value to divide by is zero or if the resulting numerator or denominator cannot be represented by an int.

pow

public Fraction pow(int exponent)

Returns a Fraction whose value is thisexponent, returning the result in reduced form.

Specified by:

pow in interface NativeOperators<Fraction>

Parameters:

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

Returns:

thisexponent.

Throws:

ArithmeticException - if the intermediate result would overflow.

toString

public String toString()

Returns the String representing this fraction. Uses:

• "0" if numerator is zero.
• "numerator" if denominator is one.
• "numerator / denominator" for all other cases.

Overrides:

toString in class Object

Returns:

a string representation of the fraction.

compareTo

public int compareTo(Fraction other)

Compares this object with the specified object for order using the signed magnitude.

Specified by:

compareTo in interface Comparable<Fraction>

Parameters:

other -

Returns:

equals

public boolean equals(Object other)

Test for equality with another object. If the other object is a Fraction then a comparison is made of the sign and magnitude; otherwise false is returned.

Overrides:

equals in class Object

Parameters:

other -

Returns:

hashCode

public int hashCode()

Overrides:

hashCode in class Object