FileDocCategorySizeDatePackage
Rational.javaAPI DocAndroid 5.1 API21793Thu Mar 12 22:22:10 GMT 2015android.util

Rational

public final class Rational extends Number implements Comparable

An immutable data type representation a rational number.

Contains a pair of {@code int}s representing the numerator and denominator of a Rational number.

Fields Summary
public static final Rational
NaN
Constant for the Not-a-Number (NaN) value of the {@code Rational} type.

A {@code NaN} value is considered to be equal to itself (that is {@code NaN.equals(NaN)} will return {@code true}; it is always greater than any non-{@code NaN} value (that is {@code NaN.compareTo(notNaN)} will return a number greater than {@code 0}).

Equivalent to constructing a new rational with both the numerator and denominator equal to {@code 0}.

public static final Rational
POSITIVE_INFINITY
Constant for the positive infinity value of the {@code Rational} type.

Equivalent to constructing a new rational with a positive numerator and a denominator equal to {@code 0}.

public static final Rational
NEGATIVE_INFINITY
Constant for the negative infinity value of the {@code Rational} type.

Equivalent to constructing a new rational with a negative numerator and a denominator equal to {@code 0}.

public static final Rational
ZERO
Constant for the zero value of the {@code Rational} type.

Equivalent to constructing a new rational with a numerator equal to {@code 0} and any non-zero denominator.

private static final long
serialVersionUID
Unique version number per class to be compliant with {@link java.io.Serializable}.

Increment each time the fields change in any way.

private final int
mNumerator
private final int
mDenominator
Constructors Summary
public Rational(int numerator, int denominator)

Create a {@code Rational} with a given numerator and denominator.

The signs of the numerator and the denominator may be flipped such that the denominator is always positive. Both the numerator and denominator will be converted to their reduced forms (see {@link #equals} for more details).

For example,

  • a rational of {@code 2/4} will be reduced to {@code 1/2}.
  • a rational of {@code 1/-1} will be flipped to {@code -1/1}
  • a rational of {@code 5/0} will be reduced to {@code 1/0}
  • a rational of {@code 0/5} will be reduced to {@code 0/1}

param
numerator the numerator of the rational
param
denominator the denominator of the rational
see
#equals


                                                                                                                        
         

        if (denominator < 0) {
            numerator = -numerator;
            denominator = -denominator;
        }

        // Convert to reduced form
        if (denominator == 0 && numerator > 0) {
            mNumerator = 1; // +Inf
            mDenominator = 0;
        } else if (denominator == 0 && numerator < 0) {
            mNumerator = -1; // -Inf
            mDenominator = 0;
        } else if (denominator == 0 && numerator == 0) {
            mNumerator = 0; // NaN
            mDenominator = 0;
        } else if (numerator == 0) {
            mNumerator = 0;
            mDenominator = 1;
        } else {
            int gcd = gcd(numerator, denominator);

            mNumerator = numerator / gcd;
            mDenominator = denominator / gcd;
        }
Methods Summary
public intcompareTo(android.util.Rational another)
Compare this rational to the specified rational to determine their natural order.

{@link #NaN} is considered to be equal to itself and greater than all other {@code Rational} values. Otherwise, if the objects are not {@link #equals equal}, then the following rules apply:

  • Positive infinity is greater than any other finite number (or negative infinity)
  • Negative infinity is less than any other finite number (or positive infinity)
  • The finite number represented by this rational is checked numerically against the other finite number by converting both rationals to a common denominator multiple and comparing their numerators.

param
another the rational to be compared
return
a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified rational.
throws
NullPointerException if {@code another} was {@code null}

        checkNotNull(another, "another must not be null");

        if (equals(another)) {
            return 0;
        } else if (isNaN()) { // NaN is greater than the other non-NaN value
            return 1;
        } else if (another.isNaN()) { // the other NaN is greater than this non-NaN value
            return -1;
        } else if (isPosInf() || another.isNegInf()) {
            return 1; // positive infinity is greater than any non-NaN/non-posInf value
        } else if (isNegInf() || another.isPosInf()) {
            return -1; // negative infinity is less than any non-NaN/non-negInf value
        }

        // else both this and another are finite numbers

        // make the denominators the same, then compare numerators
        long thisNumerator = ((long)mNumerator) * another.mDenominator; // long to avoid overflow
        long otherNumerator = ((long)another.mNumerator) * mDenominator; // long to avoid overflow

        // avoid underflow from subtraction by doing comparisons
        if (thisNumerator < otherNumerator) {
            return -1;
        } else if (thisNumerator > otherNumerator) {
            return 1;
        } else {
            // This should be covered by #equals, but have this code path just in case
            return 0;
        }
public doubledoubleValue()
Returns the value of the specified number as a {@code double}.

The {@code double} is calculated by converting both the numerator and denominator to a {@code double}; then returning the result of dividing the numerator by the denominator.

return
the divided value of the numerator and denominator as a {@code double}.

        double num = mNumerator;
        double den = mDenominator;

        return num / den;
public booleanequals(java.lang.Object obj)

Compare this Rational to another object and see if they are equal.

A Rational object can only be equal to another Rational object (comparing against any other type will return {@code false}).

A Rational object is considered equal to another Rational object if and only if one of the following holds:

  • Both are {@code NaN}
  • Both are infinities of the same sign
  • Both have the same numerator and denominator in their reduced form

A reduced form of a Rational is calculated by dividing both the numerator and the denominator by their greatest common divisor.

{@code
(new Rational(1, 2)).equals(new Rational(1, 2)) == true // trivially true
(new Rational(2, 3)).equals(new Rational(1, 2)) == false // trivially false
(new Rational(1, 2)).equals(new Rational(2, 4)) == true // true after reduction
(new Rational(0, 0)).equals(new Rational(0, 0)) == true // NaN.equals(NaN)
(new Rational(1, 0)).equals(new Rational(5, 0)) == true // both are +infinity
(new Rational(1, 0)).equals(new Rational(-1, 0)) == false // +infinity != -infinity
}

param
obj a reference to another object
return
A boolean that determines whether or not the two Rational objects are equal.

        return obj instanceof Rational && equals((Rational) obj);
private booleanequals(android.util.Rational other)

        return (mNumerator == other.mNumerator && mDenominator == other.mDenominator);
public floatfloatValue()
Returns the value of the specified number as a {@code float}.

The {@code float} is calculated by converting both the numerator and denominator to a {@code float}; then returning the result of dividing the numerator by the denominator.

return
the divided value of the numerator and denominator as a {@code float}.

        float num = mNumerator;
        float den = mDenominator;

        return num / den;
public static intgcd(int numerator, int denominator)
Calculates the greatest common divisor using Euclid's algorithm.

Visible for testing only.

param
numerator the numerator in a fraction
param
denominator the denominator in a fraction
return
An int value representing the gcd. Always positive.
hide

        /*
         * Non-recursive implementation of Euclid's algorithm:
         *
         *  gcd(a, 0) := a
         *  gcd(a, b) := gcd(b, a mod b)
         *
         */
        int a = numerator;
        int b = denominator;

        while (b != 0) {
            int oldB = b;

            b = a % b;
            a = oldB;
        }

        return Math.abs(a);
public intgetDenominator()
Gets the denominator of the rational

The denominator may return {@code 0}, in which case the rational may represent positive infinity (if the numerator was positive), negative infinity (if the numerator was negative), or {@code NaN} (if the numerator was {@code 0}).

The denominator will always return {@code 1} if the numerator is {@code 0}.

        return mDenominator;
public intgetNumerator()
Gets the numerator of the rational.

The numerator will always return {@code 1} if this rational represents infinity (that is, the denominator is {@code 0}).

        return mNumerator;
public inthashCode()
{@inheritDoc}

        // Bias the hash code for the first (2^16) values for both numerator and denominator
        int numeratorFlipped = mNumerator << 16 | mNumerator >>> 16;

        return mDenominator ^ numeratorFlipped;
public intintValue()
Returns the value of the specified number as a {@code int}.

{@link #isInfinite Finite} rationals are converted to an {@code int} value by dividing the numerator by the denominator; conversion for non-finite values happens identically to casting a floating point value to an {@code int}, in particular:

  • Positive infinity saturates to the largest maximum integer {@link Integer#MAX_VALUE}
  • Negative infinity saturates to the smallest maximum integer {@link Integer#MIN_VALUE}
  • Not-A-Number (NaN) returns {@code 0}.

return
the divided value of the numerator and denominator as a {@code int}.

        // Mimic float to int conversion rules from JLS 5.1.3

        if (isPosInf()) {
            return Integer.MAX_VALUE;
        } else if (isNegInf()) {
            return Integer.MIN_VALUE;
        } else if (isNaN()) {
            return 0;
        } else { // finite
            return mNumerator / mDenominator;
        }
private static java.lang.NumberFormatExceptioninvalidRational(java.lang.String s)

        throw new NumberFormatException("Invalid Rational: \"" + s + "\"");
public booleanisFinite()
Indicates whether this rational represents a finite value.

A finite value occurs when the denominator is not {@code 0}; in other words the rational is neither infinity or {@code NaN}.

return
{@code true} if this rational is a (positive or negative) infinite value; {@code false} if this is a finite number value (or {@code NaN})

        return mDenominator != 0;
public booleanisInfinite()
Indicates whether this rational represents an infinite value.

An infinite value occurs when the denominator is {@code 0} (but the numerator is not).

return
{@code true} if this rational is a (positive or negative) infinite value; {@code false} if this is a finite number value (or {@code NaN})

        return mNumerator != 0 && mDenominator == 0;
public booleanisNaN()
Indicates whether this rational is a Not-a-Number (NaN) value.

A {@code NaN} value occurs when both the numerator and the denominator are {@code 0}.

return
{@code true} if this rational is a Not-a-Number (NaN) value; {@code false} if this is a (potentially infinite) number value

        return mDenominator == 0 && mNumerator == 0;
private booleanisNegInf()

        return mDenominator == 0 && mNumerator < 0;
private booleanisPosInf()

        return mDenominator == 0 && mNumerator > 0;
public booleanisZero()
Indicates whether this rational represents a zero value.

A zero value is a {@link #isFinite finite} rational with a numerator of {@code 0}.

return
{@code true} if this rational is finite zero value; {@code false} otherwise

        return isFinite() && mNumerator == 0;
public longlongValue()
Returns the value of the specified number as a {@code long}.

{@link #isInfinite Finite} rationals are converted to an {@code long} value by dividing the numerator by the denominator; conversion for non-finite values happens identically to casting a floating point value to a {@code long}, in particular:

  • Positive infinity saturates to the largest maximum long {@link Long#MAX_VALUE}
  • Negative infinity saturates to the smallest maximum long {@link Long#MIN_VALUE}
  • Not-A-Number (NaN) returns {@code 0}.

return
the divided value of the numerator and denominator as a {@code long}.

        // Mimic float to long conversion rules from JLS 5.1.3

        if (isPosInf()) {
            return Long.MAX_VALUE;
        } else if (isNegInf()) {
            return Long.MIN_VALUE;
        } else if (isNaN()) {
            return 0;
        } else { // finite
            return mNumerator / mDenominator;
        }
public static android.util.RationalparseRational(java.lang.String string)
Parses the specified string as a rational value.

The ASCII characters {@code \}{@code u003a} (':') and {@code \}{@code u002f} ('/') are recognized as separators between the numerator and denumerator.

For any {@code Rational r}: {@code Rational.parseRational(r.toString()).equals(r)}. However, the method also handles rational numbers expressed in the following forms:

"num{@code /}den" or "num{@code :}den" {@code => new Rational(num, den);}, where num and den are string integers potentially containing a sign, such as "-10", "+7" or "5".

{@code
Rational.parseRational("3:+6").equals(new Rational(1, 2)) == true
Rational.parseRational("-3/-6").equals(new Rational(1, 2)) == true
Rational.parseRational("4.56") => throws NumberFormatException
}

param
string the string representation of a rational value.
return
the rational value represented by {@code string}.
throws
NumberFormatException if {@code string} cannot be parsed as a rational value.
throws
NullPointerException if {@code string} was {@code null}

        checkNotNull(string, "string must not be null");

        if (string.equals("NaN")) {
            return NaN;
        } else if (string.equals("Infinity")) {
            return POSITIVE_INFINITY;
        } else if (string.equals("-Infinity")) {
            return NEGATIVE_INFINITY;
        }

        int sep_ix = string.indexOf(':");
        if (sep_ix < 0) {
            sep_ix = string.indexOf('/");
        }
        if (sep_ix < 0) {
            throw invalidRational(string);
        }
        try {
            return new Rational(Integer.parseInt(string.substring(0, sep_ix)),
                    Integer.parseInt(string.substring(sep_ix + 1)));
        } catch (NumberFormatException e) {
            throw invalidRational(string);
        }
private voidreadObject(java.io.ObjectInputStream in)
writeObject with default serialized form - guards against deserializing non-reduced forms of the rational.

throws
InvalidObjectException if the invariants were violated

        in.defaultReadObject();

        /*
         * Guard against trying to deserialize illegal values (in this case, ones
         * that don't have a standard reduced form).
         *
         * - Non-finite values must be one of [0, 1], [0, 0], [0, 1], [0, -1]
         * - Finite values must always have their greatest common divisor as 1
         */

        if (mNumerator == 0) { // either zero or NaN
            if (mDenominator == 1 || mDenominator == 0) {
                return;
            }
            throw new InvalidObjectException(
                    "Rational must be deserialized from a reduced form for zero values");
        } else if (mDenominator == 0) { // either positive or negative infinity
            if (mNumerator == 1 || mNumerator == -1) {
                return;
            }
            throw new InvalidObjectException(
                    "Rational must be deserialized from a reduced form for infinity values");
        } else { // finite value
            if (gcd(mNumerator, mDenominator) > 1) {
                throw new InvalidObjectException(
                        "Rational must be deserialized from a reduced form for finite values");
            }
        }
public shortshortValue()
Returns the value of the specified number as a {@code short}.

{@link #isInfinite Finite} rationals are converted to a {@code short} value identically to {@link #intValue}; the {@code int} result is then truncated to a {@code short} before returning the value.

return
the divided value of the numerator and denominator as a {@code short}.

        return (short) intValue();
public floattoFloat()

Convert to a floating point representation.

return
The floating point representation of this rational number.
hide

        // TODO: remove this duplicate function (used in CTS and the shim)
        return floatValue();
public java.lang.StringtoString()
Return a string representation of this rational, e.g. {@code "1/2"}.

The following rules of conversion apply:

  • {@code NaN} values will return {@code "NaN"}
  • Positive infinity values will return {@code "Infinity"}
  • Negative infinity values will return {@code "-Infinity"}
  • All other values will return {@code "numerator/denominator"} where {@code numerator} and {@code denominator} are substituted with the appropriate numerator and denominator values. 

        if (isNaN()) {
            return "NaN";
        } else if (isPosInf()) {
            return "Infinity";
        } else if (isNegInf()) {
            return "-Infinity";
        } else {
            return mNumerator + "/" + mDenominator;
        }