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:
    Serialized Form

  Defined in the `sis-utility` module

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Fraction(int numerator, int denominator)` Creates a new fraction.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Fraction` | `add(Fraction other)` Returns the simplified result of adding the given fraction to this fraction.
    `byte` | `byteValue()` Returns this fraction rounded toward zero, if the result can be represented as a signed byte.
    `int` | `ceil()` Returns this fraction rounded toward positive infinity.
    `int` | `compareTo(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` | `doubleValue()` Returns the fraction as a double-precision floating point number.
    `boolean` | `equals(Object other)` Compares this fraction with the given object for equality.
    `float` | `floatValue()` Returns the fraction as a single-precision floating point number.
    `int` | `floor()` Returns this fraction rounded toward negative infinity.
    `int` | `hashCode()` Returns a hash code value for this fraction.
    `int` | `intValue()` Returns this fraction rounded toward zero.
    `long` | `longValue()` 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.
    `short` | `shortValue()` Returns this fraction rounded toward zero, if the result can be represented as a short integer.
    `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` | `toString()` Returns a string representation of this fraction.
    `Fraction` | `unique()` Returns a unique fraction instance equals to `this`.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### numerator

          public final int numerator

      The a term in the a/b fraction. Can be positive, negative or zero.
      See Also:
        `doubleValue()`

    - #### 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:
        `doubleValue()`

  - ### Constructor Detail

    - #### 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.

  - ### Method Detail

    - #### 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 can not be simplified, then this method returns `this`.
      Returns:
        the simplest fraction equivalent to this fraction.

    - #### negate

          public Fraction negate()

      Returns the negative value of this fraction. This method does not simplify the fraction.
      Returns:
        the result of `-this`.
      Throws:
        `ArithmeticException` - if the result overflows.

    - #### 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:
        `ArithmeticException` - 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:
        `ArithmeticException` - if the result overflows.

    - #### 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:
        `ArithmeticException` - 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:
        `ArithmeticException` - if the result overflows.

    - #### 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:
      - If the numerator and the denominator are both 0, then this method returns `Double​.NaN`.
      - If only the denominator is zero, then this method returns positive infinity or negative infinity accordingly the numerator sign.
      Specified by:
        `doubleValue` 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:
      - If the numerator and the denominator are both 0, then this method returns `Float​.NaN`.
      - If only the denominator is zero, then this method returns positive infinity or negative infinity accordingly the numerator sign.
      Specified by:
        `floatValue` in class `Number`
      Returns:
        this fraction as a floating point number.

    - #### longValue

          public long longValue()

      Returns this fraction rounded toward zero.
      Specified by:
        `longValue` in class `Number`
      Returns:
        this fraction rounded toward zero.

    - #### intValue

          public int intValue()

      Returns this fraction rounded toward zero.
      Specified by:
        `intValue` in class `Number`
      Returns:
        `numerator` / `denominator` rounded toward zero.
      See Also:
        `round()`, `floor()`, `ceil()`

    - #### shortValue

          public short shortValue()

      Returns this fraction rounded toward zero, if the result can be represented as a short integer.
      Overrides:
        `shortValue` in class `Number`
      Returns:
        this fraction rounded toward zero.
      Throws:
        `ArithmeticException` - if the result can not be represented as a short integer.

    - #### byteValue

          public byte byteValue()

      Returns this fraction rounded toward zero, if the result can be represented as a signed byte.
      Overrides:
        `byteValue` in class `Number`
      Returns:
        this fraction rounded toward zero.
      Throws:
        `ArithmeticException` - if the result can not be represented as a signed byte.

    - #### compareTo

          public int compareTo(Fraction other)

      Compares this fraction with the given one for order.
      Specified by:
        `compareTo` 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 an other fraction with the same numerator and denominator values.

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this fraction.
      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Returns a string representation of this fraction. This method returns Unicode symbol if possible.
      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of this fraction.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.