/* * Copyright (C) 2013 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.util; import static com.android.internal.util.Preconditions.*; import java.io.IOException; import java.io.InvalidObjectException; /** *

An immutable data type representation a rational number.

* *

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

*/ public final class Rational extends Number implements Comparable { /** * 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 NaN = new Rational(0, 0); /** * 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 POSITIVE_INFINITY = new Rational(1, 0); /** * 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 NEGATIVE_INFINITY = new Rational(-1, 0); /** * 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.

*/ public static final Rational ZERO = new Rational(0, 1); /** * Unique version number per class to be compliant with {@link java.io.Serializable}. * *

Increment each time the fields change in any way.

*/ private static final long serialVersionUID = 1L; /* * Do not change the order of these fields or add new instance fields to maintain the * Serializable compatibility across API revisions. */ private final int mNumerator; private final int mDenominator; /** *

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, *

*

* * @param numerator the numerator of the rational * @param denominator the denominator of the rational * * @see #equals */ public Rational(int numerator, int denominator) { 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; } } /** * 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}).

*/ public int getNumerator() { return mNumerator; } /** * 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}. */ public int getDenominator() { return mDenominator; } /** * 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 */ public boolean isNaN() { return mDenominator == 0 && mNumerator == 0; } /** * 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}) */ public boolean isInfinite() { return mNumerator != 0 && mDenominator == 0; } /** * 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}) */ public boolean isFinite() { return mDenominator != 0; } /** * 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 */ public boolean isZero() { return isFinite() && mNumerator == 0; } private boolean isPosInf() { return mDenominator == 0 && mNumerator > 0; } private boolean isNegInf() { return mDenominator == 0 && mNumerator < 0; } /** *

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:

* * *

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. */ @Override public boolean equals(Object obj) { return obj instanceof Rational && equals((Rational) obj); } private boolean equals(Rational other) { return (mNumerator == other.mNumerator && mDenominator == other.mDenominator); } /** * Return a string representation of this rational, e.g. {@code "1/2"}. * *

The following rules of conversion apply: *

*/ @Override public String toString() { if (isNaN()) { return "NaN"; } else if (isPosInf()) { return "Infinity"; } else if (isNegInf()) { return "-Infinity"; } else { return mNumerator + "/" + mDenominator; } } /** *

Convert to a floating point representation.

* * @return The floating point representation of this rational number. * @hide */ public float toFloat() { // TODO: remove this duplicate function (used in CTS and the shim) return floatValue(); } /** * {@inheritDoc} */ @Override public int hashCode() { // Bias the hash code for the first (2^16) values for both numerator and denominator int numeratorFlipped = mNumerator << 16 | mNumerator >>> 16; return mDenominator ^ numeratorFlipped; } /** * 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 */ public static int gcd(int numerator, int denominator) { /* * 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); } /** * 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}. */ @Override public double doubleValue() { double num = mNumerator; double den = mDenominator; return num / den; } /** * 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}. */ @Override public float floatValue() { float num = mNumerator; float den = mDenominator; return num / den; } /** * 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: * *

*

*

* * @return the divided value of the numerator and denominator as a {@code int}. */ @Override public int intValue() { // 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; } } /** * 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: * *

*

*

* * @return the divided value of the numerator and denominator as a {@code long}. */ @Override public long longValue() { // 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; } } /** * 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}. */ @Override public short shortValue() { return (short) intValue(); } /** * 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:

* * * * @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} */ @Override public int compareTo(Rational another) { 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; } } /* * Serializable implementation. * * The following methods are omitted: * >> writeObject - the default is sufficient (field by field serialization) * >> readObjectNoData - the default is sufficient (0s for both fields is a NaN) */ /** * writeObject with default serialized form - guards against * deserializing non-reduced forms of the rational. * * @throws InvalidObjectException if the invariants were violated */ private void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException { 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"); } } } private static NumberFormatException invalidRational(String s) { throw new NumberFormatException("Invalid Rational: \"" + s + "\""); } /** * 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} */ public static Rational parseRational(String string) throws NumberFormatException { 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); } } }