Java tutorial
/* * 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 android.annotation.UnsupportedAppUsage; import java.io.IOException; import java.io.InvalidObjectException; /** * <p>An immutable data type representation a rational number.</p> * * <p>Contains a pair of {@code int}s representing the numerator and denominator of a * Rational number. </p> */ public final class Rational extends Number implements Comparable<Rational> { /** * Constant for the <em>Not-a-Number (NaN)</em> value of the {@code Rational} type. * * <p>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}).</p> * * <p>Equivalent to constructing a new rational with both the numerator and denominator * equal to {@code 0}.</p> */ public static final Rational NaN = new Rational(0, 0); /** * Constant for the positive infinity value of the {@code Rational} type. * * <p>Equivalent to constructing a new rational with a positive numerator and a denominator * equal to {@code 0}.</p> */ public static final Rational POSITIVE_INFINITY = new Rational(1, 0); /** * Constant for the negative infinity value of the {@code Rational} type. * * <p>Equivalent to constructing a new rational with a negative numerator and a denominator * equal to {@code 0}.</p> */ public static final Rational NEGATIVE_INFINITY = new Rational(-1, 0); /** * Constant for the zero value of the {@code Rational} type. * * <p>Equivalent to constructing a new rational with a numerator equal to {@code 0} and * any non-zero denominator.</p> */ public static final Rational ZERO = new Rational(0, 1); /** * Unique version number per class to be compliant with {@link java.io.Serializable}. * * <p>Increment each time the fields change in any way.</p> */ 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. */ @UnsupportedAppUsage private final int mNumerator; @UnsupportedAppUsage private final int mDenominator; /** * <p>Create a {@code Rational} with a given numerator and denominator.</p> * * <p>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).</p> * * <p>For example, * <ul> * <li>a rational of {@code 2/4} will be reduced to {@code 1/2}. * <li>a rational of {@code 1/-1} will be flipped to {@code -1/1} * <li>a rational of {@code 5/0} will be reduced to {@code 1/0} * <li>a rational of {@code 0/5} will be reduced to {@code 0/1} * </ul> * </p> * * @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. * * <p>The numerator will always return {@code 1} if this rational represents * infinity (that is, the denominator is {@code 0}).</p> */ public int getNumerator() { return mNumerator; } /** * Gets the denominator of the rational * * <p>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}).</p> * * <p>The denominator will always return {@code 1} if the numerator is {@code 0}. */ public int getDenominator() { return mDenominator; } /** * Indicates whether this rational is a <em>Not-a-Number (NaN)</em> value. * * <p>A {@code NaN} value occurs when both the numerator and the denominator are {@code 0}.</p> * * @return {@code true} if this rational is a <em>Not-a-Number (NaN)</em> 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. * * <p>An infinite value occurs when the denominator is {@code 0} (but the numerator is not).</p> * * @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. * * <p>A finite value occurs when the denominator is not {@code 0}; in other words * the rational is neither infinity or {@code NaN}.</p> * * @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. * * <p>A zero value is a {@link #isFinite finite} rational with a numerator of {@code 0}.</p> * * @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; } /** * <p>Compare this Rational to another object and see if they are equal.</p> * * <p>A Rational object can only be equal to another Rational object (comparing against any * other type will return {@code false}).</p> * * <p>A Rational object is considered equal to another Rational object if and only if one of * the following holds:</p> * <ul><li>Both are {@code NaN}</li> * <li>Both are infinities of the same sign</li> * <li>Both have the same numerator and denominator in their reduced form</li> * </ul> * * <p>A reduced form of a Rational is calculated by dividing both the numerator and the * denominator by their greatest common divisor.</p> * * <pre>{@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 * }</pre> * * @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"}. * * <p>The following rules of conversion apply: * <ul> * <li>{@code NaN} values will return {@code "NaN"} * <li>Positive infinity values will return {@code "Infinity"} * <li>Negative infinity values will return {@code "-Infinity"} * <li>All other values will return {@code "numerator/denominator"} where {@code numerator} * and {@code denominator} are substituted with the appropriate numerator and denominator * values. * </ul></p> */ @Override public String toString() { if (isNaN()) { return "NaN"; } else if (isPosInf()) { return "Infinity"; } else if (isNegInf()) { return "-Infinity"; } else { return mNumerator + "/" + mDenominator; } } /** * <p>Convert to a floating point representation.</p> * * @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. * * <p><em>Visible for testing only.</em></p> * * @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}. * * <p>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.</p> * * @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}. * * <p>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.</p> * * @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}. * * <p>{@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: * * <p> * <ul> * <li>Positive infinity saturates to the largest maximum integer * {@link Integer#MAX_VALUE}</li> * <li>Negative infinity saturates to the smallest maximum integer * {@link Integer#MIN_VALUE}</li> * <li><em>Not-A-Number (NaN)</em> returns {@code 0}.</li> * </ul> * </p> * * @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}. * * <p>{@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: * * <p> * <ul> * <li>Positive infinity saturates to the largest maximum long * {@link Long#MAX_VALUE}</li> * <li>Negative infinity saturates to the smallest maximum long * {@link Long#MIN_VALUE}</li> * <li><em>Not-A-Number (NaN)</em> returns {@code 0}.</li> * </ul> * </p> * * @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}. * * <p>{@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.</p> * * @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. * * <p>{@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:</p> * * <ul> * <li>Positive infinity is greater than any other finite number (or negative infinity) * <li>Negative infinity is less than any other finite number (or positive infinity) * <li>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. * </ul> * * @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. * <p>The ASCII characters {@code \}{@code u003a} (':') and * {@code \}{@code u002f} ('/') are recognized as separators between * the numerator and denumerator.</p> * <p> * For any {@code Rational r}: {@code Rational.parseRational(r.toString()).equals(r)}. * However, the method also handles rational numbers expressed in the * following forms:</p> * <p> * "<i>num</i>{@code /}<i>den</i>" or * "<i>num</i>{@code :}<i>den</i>" {@code => new Rational(num, den);}, * where <i>num</i> and <i>den</i> are string integers potentially * containing a sign, such as "-10", "+7" or "5".</p> * * <pre>{@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 * }</pre> * * @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); } } }