Rational

All Implemented Interfaces:: Serializable, Comparable<Rational>

public class Rational
extends Number
implements Comparable<Rational>

Immutable, arbitrary-precision rational numbers, expressed as fractions. A Rational consists of integral numerator and denominator parts, either or both of which may be negative. Two equal Rational values may be expressed as different fractions, but their canonical forms will always be identical.

The denominator of a Rational value cannot be zero. As such, this class cannot not represent infinite or NaN values, and will throw an ArithmeticException in cases where such a value would be the result.

All methods and constructors for this class throw NullPointerException when passed a null object reference for any input parameter.

See Also:: Wikipedia definition of Rational number

Constructor Summary

Constructors
Constructor	Description
`Rational(long n, long d)`	Creates a Rational number given a numerator and denominator.
`Rational(BigInteger n, BigInteger d)`	Creates a Rational number given a numerator and denominator.

Method Summary

Modifier and Type	Method	Description
`Rational`	`abs()`	Returns a Rational that is the absolute value of this Rational.
`Rational`	`add(double addend)`	Computes the value of this Rational plus the given number.
`Rational`	`add(long addend)`	Computes the value of this Rational plus the given number.
`Rational`	`add(Rational addend)`	Computes the value of this Rational plus the given other Rational.
`Rational`	`canonical()`	Converts this Rational to its canonical form - an irreducible fraction with a positive denominator.
`int`	`compareTo(Rational other)`	Compares this Rational value to another for natural ordering.
`BigDecimal`	`decimalValue()`	Returns the decimal expansion of this Rational value.
`Rational`	`divide(double divisor)`	Computes the value of this Rational divided by the given number.
`Rational`	`divide(long divisor)`	Computes the value of this Rational divided by the given number.
`Rational`	`divide(Rational divisor)`	Computes the value of this Rational divided by the given other Rational.
`double`	`doubleValue()`	Converts this Rational value to a `double`.
`boolean`	`equals(Object other)`	Test whether this Rational is equivalent to the given object.
`float`	`floatValue()`	Converts this Rational value to a `float`.
`BigInteger`	`getDenominator()`	Get the denominator part of this Rational number's fractional form.
`BigInteger`	`getNumerator()`	Get the numerator part of this Rational number's fractional form.
`int`	`hashCode()`	Returns the hash code for this Rational.
`int`	`intValue()`	Converts this Rational value to an `int`.
`boolean`	`isProper()`	Returns true if this is a proper fraction.
`boolean`	`isRepeatingDecimal()`	Returns true if this value has a non-terminating decimal expansion.
`long`	`longValue()`	Converts this Rational value to a `long`.
`Rational`	`multiply(double multiplier)`	Computes the value of this Rational multiplied by the given number.
`Rational`	`multiply(long multiplier)`	Computes the value of this Rational multiplied by the given number.
`Rational`	`multiply(Rational multiplier)`	Computes the value of this Rational multiplied by the given other Rational.
`Rational`	`negate()`	Returns a Rational that is the additive inverse of this value.
`Rational`	`pow(int exponent)`	Computes the value of this Rational raised to the power of the given exponent.
`Rational`	`reciprocal()`	Returns a Rational that is the multiplicative inverse of this value.
`int`	`signum()`	Returns the sign of this value.
`Rational`	`subtract(double subtrahend)`	Computes the value of this Rational minus the given number.
`Rational`	`subtract(long subtrahend)`	Computes the value of this Rational minus the given number.
`Rational`	`subtract(Rational subtrahend)`	Computes the value of this Rational minus the given other Rational.
`String`	`toString()`	Returns the string representation of this Rational.
`static Rational`	`valueOf(double source)`	Translates the given double into an equivalent Rational value.
`static Rational`	`valueOf(long source)`	Translates the given long into an equivalent Rational value.
`static Rational`	`valueOf(String source)`	Translates the given String into an equivalent Rational value.

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details
- Rational
  
  public Rational(long n, long d)
  
  Creates a Rational number given a numerator and denominator.
  
  Parameters:
  
  n - numerator value
  
  d - denominator value
  
  Throws:
  
  ArithmeticException - if the given denominator is zero.
- Rational
  
  public Rational(BigInteger n, BigInteger d)
  
  Creates a Rational number given a numerator and denominator.
  
  Parameters:
  
  n - numerator value
  
  d - denominator value
  
  Throws:
  
  ArithmeticException - if the given denominator is zero.
  
  NullPointerException - if either parameter is null.
Method Details
- valueOf
  
  public static Rational valueOf(double source)
  
  Translates the given double into an equivalent Rational value.
  Note that the results of this method may be surprising if invoked with a value that is not exactly representable by Java's double type. For example, calling Rational.valueOf(1/3) likely won't result in a Rational exactly equivalent to 1/3. For more intuitively predictable results, use the valueOf(String) method instead.
  
  Parameters:
  
  source - a value to convert
  
  Returns:
  
  the given value as a Rational instance
  
  Throws:
  
  IllegalArgumentException - if source is NaN or infinite.
  
  See Also:
  
  BigDecimal.valueOf(double), BigDecimal.unscaledValue(), BigDecimal.scale()
- valueOf
  
  public static Rational valueOf(long source)
  
  Translates the given long into an equivalent Rational value.
  The denominator of any Rational returned by this method will always be 1.
  
  Parameters:
  
  source - a value to convert
  
  Returns:
  
  the given value as a Rational instance
  
  See Also:
  
  BigInteger.valueOf(long)
- valueOf
  
  public static Rational valueOf(String source)
  
  Translates the given String into an equivalent Rational value.
  The source value may be given in the form "a / b" where a and b are integral values and b is non-zero, or as a single decimal number.
  
  Parameters:
  
  source - fractional or numeric value to convert
  
  Returns:
  
  the given value as a Rational instance
  
  Throws:
  
  NumberFormatException - if source contains a '/' but has non-integral numerator or denominator values, or if given any other String that cannot be interpreted by BigDecimal(String)
  
  See Also:
  
  BigInteger(String), BigDecimal(String), BigDecimal.unscaledValue(), BigDecimal.scale()
- signum
  
  public int signum()
  
  Returns the sign of this value.
  Hint: numerator * denominator
  
  Returns:
  
  -1 if this value is negative, +1 if positive, or 0 if exactly zero.
  
  See Also:
  
  BigInteger.signum()
- isProper
  
  public boolean isProper()
  
  Returns true if this is a proper fraction.
  
  Returns:
  
  true if the absolute value of the numerator is less than the absolute value of the denominator; false otherwise.
  
  See Also:
  
  Wikipedia definition of proper fractions
- isRepeatingDecimal
  
  public boolean isRepeatingDecimal()
  
  Returns true if this value has a non-terminating decimal expansion.
  
  Returns:
  
  false if this value can be represented by a BigDecimal without rounding; false otherwise.
  
  See Also:
  
  BigDecimal.divide(BigDecimal)
- getNumerator
  
  public BigInteger getNumerator()
  
  Get the numerator part of this Rational number's fractional form.
  
  Returns:
  
  the numerator value
- getDenominator
  
  public BigInteger getDenominator()
  
  Get the denominator part of this Rational number's fractional form.
  
  Returns:
  
  the denominator value
- canonical
  
  public Rational canonical()
  
  Convert this Rational to its canonical form - an irreducible fraction with a positive denominator.
  Hint: divide the numerator and denominator by the greatest common divisor.
  
  Returns:
  
  an equivalent Rational value in canonical form.
  
  See Also:
  
  Wikipedia definition of rational canonical form., BigInteger.gcd(BigInteger)
- add
  
  public Rational add(double addend)
  
  Computes the value of this Rational plus the given number.
  
  Parameters:
  
  addend - a number to add
  
  Returns:
  
  this + addend
  
  See Also:
  
  valueOf(double), add(Rational)
- add
  
  public Rational add(long addend)
  
  Computes the value of this Rational plus the given number.
  
  Parameters:
  
  addend - a number to add
  
  Returns:
  
  this + addend
  
  See Also:
  
  valueOf(long), add(Rational)
- add
  
  public Rational add(Rational addend)
  
  Computes the value of this Rational plus the given other Rational.
  Hint: get a common denominator by multiplication first
  
  Parameters:
  
  addend - a Rational value to add
  
  Returns:
  
  this + addend
  
  See Also:
  
  Wikipedia entry on adding rational numbers, BigInteger.multiply(BigInteger), BigInteger.add(BigInteger)
- subtract
  
  public Rational subtract(long subtrahend)
  
  Computes the value of this Rational minus the given number.
  
  Parameters:
  
  subtrahend - a number to subtract
  
  Returns:
  
  this - subtrahend
  
  See Also:
  
  valueOf(long), subtract(Rational)
- subtract
  
  public Rational subtract(double subtrahend)
  
  Computes the value of this Rational minus the given number.
  
  Parameters:
  
  subtrahend - a number to subtract
  
  Returns:
  
  this - subtrahend
  
  See Also:
  
  valueOf(double), subtract(Rational)
- subtract
  
  public Rational subtract(Rational subtrahend)
  
  Computes the value of this Rational minus the given other Rational.
  Hint: get a common denominator by multiplication first
  
  Parameters:
  
  subtrahend - a Rational value to subtract
  
  Returns:
  
  this - subtrahend
  
  See Also:
  
  Wikipedia entry on subtracting rational numbers, BigInteger.multiply(BigInteger), BigInteger.subtract(BigInteger)
- multiply
  
  public Rational multiply(double multiplier)
  
  Computes the value of this Rational multiplied by the given number.
  
  Parameters:
  
  multiplier - a number to multiply by
  
  Returns:
  
  this * multiplier
  
  See Also:
  
  valueOf(double), multiply(Rational)
- multiply
  
  public Rational multiply(long multiplier)
  
  Computes the value of this Rational multiplied by the given number.
  
  Parameters:
  
  multiplier - a number to multiply by
  
  Returns:
  
  this * multiplier
  
  See Also:
  
  valueOf(long), multiply(Rational)
- multiply
  
  public Rational multiply(Rational multiplier)
  
  Computes the value of this Rational multiplied by the given other Rational.
  
  Parameters:
  
  multiplier - a Rational value to multiply by
  
  Returns:
  
  this * multiplier
  
  See Also:
  
  Wikipedia entry on multiplying rational numbers, BigInteger.multiply(BigInteger)
- divide
  
  public Rational divide(double divisor)
  
  Computes the value of this Rational divided by the given number.
  
  Parameters:
  
  divisor - a number to divide by
  
  Returns:
  
  this / divisor
  
  Throws:
  
  ArithmeticException - if divisor is zero
  
  See Also:
  
  valueOf(double), divide(Rational)
- divide
  
  public Rational divide(long divisor)
  
  Computes the value of this Rational divided by the given number.
  
  Parameters:
  
  divisor - a number to divide by
  
  Returns:
  
  this / divisor
  
  Throws:
  
  ArithmeticException - if divisor is zero
  
  See Also:
  
  valueOf(long), divide(Rational)
- divide
  
  public Rational divide(Rational divisor)
  
  Computes the value of this Rational divided by the given other Rational.
  Hint: use reciprocal multiplication
  
  Parameters:
  
  divisor - a Rational value to divide by
  
  Returns:
  
  this / divisor
  
  Throws:
  
  ArithmeticException - if divisor is zero
  
  See Also:
  
  Wikipedia entry on division of rational numbers, multiply(Rational), reciprocal()
- pow
  
  public Rational pow(int exponent)
  
  Computes the value of this Rational raised to the power of the given exponent.
  
  Parameters:
  
  exponent - exponent to raise this value by
  
  Returns:
  
  this^exponent
  
  Throws:
  
  ArithmeticException - if this value is zero and a negative exponent is given.
  
  See Also:
  
  Wikipedia definition of exponentiation to an integer power, BigInteger.pow(int)
- negate
  
  public Rational negate()
  
  Returns a Rational that is the additive inverse of this value.
  
  Returns:
  
  this * -1
  
  See Also:
  
  Wikipedia definition of rational inverses, BigInteger.negate()
- abs
  
  public Rational abs()
  
  Returns a Rational that is the absolute value of this Rational.
  
  Returns:
  
  |this|
  
  See Also:
  
  Wikipedia definition of absolute value, BigInteger.abs()
- reciprocal
  
  public Rational reciprocal()
  
  Returns a Rational that is the multiplicative inverse of this value.
  Hint: swap the numerator and denominator
  
  Returns:
  
  this^-1
  
  Throws:
  
  ArithmeticException - if the value of this is zero
  
  See Also:
  
  Wikipedia definition of rational inverses
- intValue
  
  public int intValue()
  
  Converts this Rational value to an int. This is a narrowing conversion that will discard any fractional part of the value (rounded down) and can lose information about the overall magnitude of the value as well as return a result with the opposite sign.
  
  Specified by:
  
  intValue in class Number
  
  Returns:
  
  an approximately equivalent integral value
  
  See Also:
  
  BigInteger.divide(BigInteger), BigInteger.intValue()
- longValue
  
  public long longValue()
  
  Converts this Rational value to a long. This is a narrowing conversion that will discard any fractional part of the value (rounded down) and can lose information about the overall magnitude of the value as well as return a result with the opposite sign.
  
  Specified by:
  
  longValue in class Number
  
  Returns:
  
  an approximately equivalent integral value
  
  See Also:
  
  BigInteger.divide(BigInteger), BigInteger.longValue()
- floatValue
  
  public float floatValue()
  
  Converts this Rational value to a float. If the value has too great a magnitude to be represented as a float, it will be converted to Float.NEGATIVE_INFINITY or Float.POSITIVE_INFINITY as appropriate. This is a narrowing conversion and may result in loss of precision, even if the result is finite.
  
  Specified by:
  
  floatValue in class Number
  
  See Also:
  
  BigDecimal(BigInteger), BigDecimal.divide(BigDecimal, MathContext), BigDecimal.floatValue()
- doubleValue
  
  public double doubleValue()
  
  Converts this Rational value to a double. If the value has too great a magnitude to be represented as a double, it will be converted to Double.NEGATIVE_INFINITY or Double.POSITIVE_INFINITY as appropriate. This is a narrowing conversion and may result in loss of precision, even if the result is finite.
  
  Specified by:
  
  doubleValue in class Number
  
  See Also:
  
  BigDecimal(BigInteger), BigDecimal.divide(BigDecimal, MathContext), BigDecimal.doubleValue()
- decimalValue
  
  public BigDecimal decimalValue()
  
  Returns the decimal expansion of this Rational value.
  
  Returns:
  
  an equivalent BigDecimal value
  
  Throws:
  
  ArithmeticException - if this value has a non-terminating decimal expansion.
  
  See Also:
  
  BigDecimal(BigInteger), BigDecimal.divide(BigDecimal)
- toString
  
  public String toString()
  
  Returns the string representation of this Rational, in the format "numerator/denominator". Note that either (or both) of the numerator or denominator may be negative.
  
  Overrides:
  
  toString in class Object
  
  See Also:
  
  BigInteger.toString()
- compareTo
  
  public int compareTo(Rational other)
  
  Compares this Rational value to another for natural ordering.
  Hint: multiply to get a common denominator
  
  Specified by:
  
  compareTo in interface Comparable<Rational>
  
  Parameters:
  
  other - the object to compare to
  
  See Also:
  
  BigInteger.compareTo(BigInteger), BigInteger.multiply(BigInteger)
- equals
  
  public boolean equals(Object other)
  
  Test whether this Rational is equivalent to the given object.
  Returns true if and only if other is a Rational object that represents the same exact numerical value as this.
  
  Hint: get a common denominator by multiplication first
  
  Overrides:
  
  equals in class Object
  
  Parameters:
  
  other - the object to compare to
  
  Returns:
  
  this == other
  
  See Also:
  
  BigInteger.multiply(BigInteger), BigInteger.equals(Object)
- hashCode
  
  public int hashCode()
  
  Returns the hash code for this Rational.
  Hint: use canonical() first to ensure equal values have the same hashCode
  
  Overrides:
  
  hashCode in class Object
  
  Returns:
  
  hash code for this Rational
  
  See Also:
  
  canonical(), Objects.hash(Object...)

Class Rational

Constructor Summary

Method Summary

Methods inherited from class java.lang.Number

Methods inherited from class java.lang.Object

Constructor Details

Method Details