Module org.apache.sis.util
Package org.apache.sis.math

Class Fraction

Object
Number
Fraction
All Implemented Interfaces:
Serializable, Comparable<Fraction>
public final class Fraction extends Number implements Comparable<Fraction>, Serializable
A value class for rational numbers. Fraction objects are represented by a numerator and a denominator stored at 32 bits integers. Fractions can be simplified. All Fraction instances are immutable and thus inherently thread-safe.
Since:
0.8
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final int
    denominator
    The b term in the a/b fraction.
    final int
    numerator
    The a term in the a/b fraction.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Fraction(int numerator, int denominator)
    Creates a new fraction.
    Fraction(String s)
    Creates a new fraction from the given text.

  • Method Summary

    Modifier and Type
    Method
    Description
    Fraction
    add(Fraction other)
    Returns the simplified result of adding the given fraction to this fraction.
    int
    ceil()
    Returns this fraction rounded toward positive infinity.
    int
    compare­To(Fraction other)
    Compares this fraction with the given one for order.
    Fraction
    divide(Fraction other)
    Returns the simplified result of dividing this fraction by the given fraction.
    double
    double­Value()
    Returns the fraction as a double-precision floating point number.
    boolean
    equals(Object other)
    Compares this fraction with the given object for equality.
    float
    float­Value()
    Returns the fraction as a single-precision floating point number.
    int
    floor()
    Returns this fraction rounded toward negative infinity.
    int
    hash­Code()
    Returns a hash code value for this fraction.
    int
    int­Value()
    Returns this fraction rounded toward zero.
    Fraction
    inverse()
    Returns the inverse value of this fraction.
    boolean
    is­Na­N()
    Returns true if the numerator and denominator are both zero.
    long
    long­Value()
    Returns this fraction rounded toward zero.
    Fraction
    multiply(Fraction other)
    Returns the simplified result of multiplying the given fraction with this fraction.
    Fraction
    negate()
    Returns the negative value of this fraction.
    int
    round()
    Returns this fraction rounded toward nearest integer.
    int
    signum()
    Returns the sign of this fraction.
    Fraction
    simplify()
    Returns a fraction equivalent to this but represented by the smallest possible numerator and denominator values.
    Fraction
    subtract(Fraction other)
    Returns the simplified result of subtracting the given fraction from this fraction.
    String
    to­String()
    Returns a string representation of this fraction.
    Fraction
    unique()
    Returns a unique fraction instance equals to this.
    static Fraction
    value­Of(double value)
    Converts the given IEEE 754 double-precision value to a fraction.
    static Fraction
    value­Of(long numerator, long denominator)
    Returns the given fraction after simplification.

    Methods inherited from class Number

    byte­Value, short­Value

    Methods inherited from class Object

    clone, finalize, get­Class, notify, notify­All, wait, wait, wait

  • Field Details

    • numerator

      public final int numerator
      The a term in the a/b fraction. Can be positive, negative or zero.
      See Also:

    • denominator

      public final int denominator
      The b term in the a/b fraction. Can be positive, negative or zero. If zero, then the fraction floating point value will be positive infinity, negative infinity or NaN depending on the numerator value.
      See Also:

  • Constructor Details

    • Fraction

      public Fraction(int numerator, int denominator)
      Creates a new fraction. This constructor stores the fraction exactly as specified; it does not simplify it. The fraction can be simplified after construction by a call to simplify().
      Parameters:
      numerator - the a term in the a/b fraction.
      denominator - the b term in the a/b fraction.

    • Fraction

      public Fraction(String s) throws NumberFormatException
      Creates a new fraction from the given text. This constructor is the converse of to­String() method. It can parse single numbers like "3", fractions like "2/3", Unicode characters like "⅔" and infinity symbols "∞" and "−∞". The given text shall not contain spaces.
      Parameters:
      s - the text to parse.
      Throws:
      Number­Format­Exception - if the given text cannot be parsed.
      Since:
      1.0

  • Method Details

    • valueOf

      public static Fraction valueOf(long numerator, long denominator)
      Returns the given fraction after simplification. If the numerator or denominator is still too large for 32 bit integer after simplification, then an Arithmetic­Exception is thrown.
      Parameters:
      numerator - numerator of the fraction to return.
      denominator - denominator of the fraction to return.
      Returns:
      the simplified fraction.
      Throws:
      Arithmetic­Exception - if the numerator and denominator cannot be represented by 32 bit integers.
      Since:
      1.4

    • valueOf

      public static Fraction valueOf(double value)
      Converts the given IEEE 754 double-precision value to a fraction. If successful, this method returns a fraction such as double­Value() is equal to the given value in the sense of Double​.equals(Object): infinities, positive and negative zeros are preserved, but various NaN values are collapsed to a single NaN value.

      This method accepts only values between -2147483648 and 2147483647 inclusive, i.e. values in the range of 32-bits integers. If the given value has fraction digits, then the validity range will be smaller depending on the denominator required for representing that value.

      Design note

      This method does not return approximated values because it is difficult to choose which fraction is best. For example, choosing an approximated fraction for π value is quite arbitrary, and searching the fraction closer than any other fraction representable by this class is computationally expensive. Even with common fractions, the algorithm currently implemented in this class can detect that 1.6666666666666667 is equal to 5⁄3 but cannot detect easily that 1.66666666666666 (same number with two decimal digits dropped) is close to 5⁄3.
      Parameters:
      value - the double-precision value to convert to a fraction.
      Returns:
      a fraction such as double­Value() is equal to the given value.
      Throws:
      Illegal­Argument­Exception - if the given value cannot be converted to a fraction.
      Since:
      1.0

    • unique

      public Fraction unique()
      Returns a unique fraction instance equals to this. If this method has been invoked previously on another Fraction with the same value than this, then that previous instance is returned (provided that it has not yet been garbage collected). Otherwise this method adds this fraction to the pool of fractions that may be returned in next unique() invocations, then returns this.

      This method is useful for saving memory when a potentially large amount of Fraction instances will be kept for a long time and many instances are likely to have the same values. It is usually not worth to invoke this method for short-lived instances.

      Returns:
      a unique instance of a fraction equals to this.

    • simplify

      public Fraction simplify()
      Returns a fraction equivalent to this but represented by the smallest possible numerator and denominator values. If this fraction cannot be simplified, then this method returns this.
      Returns:
      the simplest fraction equivalent to this fraction.

    • inverse

      public Fraction inverse()
      Returns the inverse value of this fraction. This method does not simplify the fraction.
      Returns:
      the result of 1/this.
      Throws:
      Arithmetic­Exception - if the result overflows.
      Since:
      1.4
      See Also:

    • negate

      public Fraction negate()
      Returns the negative value of this fraction. This method does not simplify the fraction.
      Returns:
      the result of -this.
      Throws:
      Arithmetic­Exception - if the result overflows.
      See Also:

    • add

      public Fraction add(Fraction other)
      Returns the simplified result of adding the given fraction to this fraction.
      Parameters:
      other - the fraction to add to this fraction.
      Returns:
      the simplified result of this + other.
      Throws:
      Arithmetic­Exception - if the result overflows.

    • subtract

      public Fraction subtract(Fraction other)
      Returns the simplified result of subtracting the given fraction from this fraction.
      Parameters:
      other - the fraction to subtract from this fraction.
      Returns:
      the simplified result of this - other.
      Throws:
      Arithmetic­Exception - if the result overflows.
      See Also:

    • multiply

      public Fraction multiply(Fraction other)
      Returns the simplified result of multiplying the given fraction with this fraction.
      Parameters:
      other - the fraction to multiply with this fraction.
      Returns:
      the simplified result of this × other.
      Throws:
      Arithmetic­Exception - if the result overflows.

    • divide

      public Fraction divide(Fraction other)
      Returns the simplified result of dividing this fraction by the given fraction.
      Parameters:
      other - the fraction by which to divide this fraction.
      Returns:
      the simplified result of this ∕ other.
      Throws:
      Arithmetic­Exception - if the result overflows.
      See Also:

    • round

      public int round()
      Returns this fraction rounded toward nearest integer. If the result is located at equal distance from the two nearest integers, then rounds to the even one.
      Returns:
      numerator / denominator rounded toward nearest integer.

    • floor

      public int floor()
      Returns this fraction rounded toward negative infinity. This is different from the default operation on primitive types, which rounds toward zero.

      Tip: if the numerator and the denominator are both positive or both negative, then the result is positive and identical to numerator / denominator.

      Returns:
      numerator / denominator rounded toward negative infinity.

    • ceil

      public int ceil()
      Returns this fraction rounded toward positive infinity. This is different from the default operation on primitive types, which rounds toward zero.
      Returns:
      numerator / denominator rounded toward positive infinity.

    • doubleValue

      public double doubleValue()
      Returns the fraction as a double-precision floating point number. Special cases:
      Specified by:
      double­Value in class Number
      Returns:
      this fraction as a floating point number.

    • floatValue

      public float floatValue()
      Returns the fraction as a single-precision floating point number. Special cases:
      Specified by:
      float­Value in class Number
      Returns:
      this fraction as a floating point number.

    • longValue

      public long longValue()
      Returns this fraction rounded toward zero. If the fraction value is NaN, then this method returns 0. If the fraction value is positive or negative infinity, then this method returns Long​.MAX_VALUE or Long​.MIN_VALUE respectively.
      Specified by:
      long­Value in class Number
      Returns:
      this fraction rounded toward zero.

    • intValue

      public int intValue()
      Returns this fraction rounded toward zero. If the fraction value is NaN, then this method returns 0. If the fraction value is positive or negative infinity, then this method returns Integer​.MAX_VALUE or Integer​.MIN_VALUE respectively.
      Specified by:
      int­Value in class Number
      Returns:
      numerator / denominator rounded toward zero.
      See Also:

    • isNaN

      public boolean isNaN()
      Returns true if the numerator and denominator are both zero.
      Returns:
      whether this fraction is 0/0.
      Since:
      1.4

    • signum

      public int signum()
      Returns the sign of this fraction. The return value is -1 if this fraction is negative; 0 if the numerator is zero; and 1 if this fraction is positive.
      Returns:
      the sign of this fraction.
      Since:
      1.0
      See Also:

    • compareTo

      public int compareTo(Fraction other)
      Compares this fraction with the given one for order.
      Specified by:
      compare­To in interface Comparable<Fraction>
      Parameters:
      other - the fraction to compare to this fraction for ordering.
      Returns:
      a negative number if this fraction is smaller than the given fraction, a positive number if greater, or 0 if equals.

    • equals

      public boolean equals(Object other)
      Compares this fraction with the given object for equality. This method returns true only if the two objects are fractions with same numerator and denominator values. Fractions with different values are not considered equal even if the two fraction are equivalent.
      Overrides:
      equals in class Object
      Parameters:
      other - the object to compare with this fraction for equality.
      Returns:
      true if the given object is another fraction with the same numerator and denominator values.

    • hashCode

      public int hashCode()
      Returns a hash code value for this fraction.
      Overrides:
      hash­Code in class Object

    • toString

      public String toString()
      Returns a string representation of this fraction. This method returns Unicode symbol if possible.
      Overrides:
      to­String in class Object
      Returns:
      a string representation of this fraction.