# Class Aprational

java.lang.Object
java.lang.Number
org.apfloat.Apcomplex
org.apfloat.Apfloat
org.apfloat.Aprational

All Implemented Interfaces:
  `Serializable, Comparable<Apfloat>, Formattable`

Direct Known Subclasses:
  `Apint`

public class Aprational extends Apfloat
Arbitrary precision rational number class. An aprational consists of a numerator and a denominator of type `Apint`.

Version:
  1.15.0
Author:
  Mikko Tommila
See Also:
  - `Apint`
  - `AprationalMath`
  - Serialized Form

- ## Field Summary

  ### Fields inherited from class Apcomplex

  `DEFAULT, I, INFINITE, ONE, REAL_ABS_IMAG_ORDER, REAL_IMAG_ORDER, ZERO`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Aprational()`
  Default constructor.
  ``
  `Aprational(double value)`
  Constructs an aprational from a `double`.
  ``
  `Aprational(double value, int radix)`
  Constructs an aprational from a `double` using the specified radix.
  ``
  `Aprational(PushbackReader in)`
  Reads an aprational from a reader.
  ``
  `Aprational(PushbackReader in, int radix)`
  Reads an aprational from a reader.
  ``
  `Aprational(String value)`
  Constructs an aprational from a string.
  ``
  `Aprational(String value, int radix)`
  Constructs an aprational from a string with the specified radix.
  ``
  `Aprational(BigInteger value)`
  Constructs an aprational from a `BigInteger`.
  ``
  `Aprational(BigInteger value, int radix)`
  Constructs an aprational from a `BigInteger` using the specified radix.
  ``
  `Aprational(Apint value)`
  Construct an integer aprational whose denominator is one.
  ``
  `Aprational(Apint numerator, Apint denominator)`
  Construct an aprational with the specified numerator and denominator.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Aprational`
  `add(Aprational x)`
  Adds two aprational numbers.
  `Apint`
  `ceil()`
  Ceiling function.
  `int`
  `compareTo(Apfloat x)`
  Compare this aprational to the specified apfloat.
  `int`
  `compareTo(Aprational x)`
  Compare this aprational to the specified aprational.
  `Apint`
  `denominator()`
  Denominator of this aprational.
  `Aprational`
  `divide(Aprational x)`
  Divides two aprational numbers.
  `boolean`
  `equals(Object obj)`
  Compares this object to the specified object.
  `Apint`
  `floor()`
  Floor function.
  `void`
  `formatTo(Formatter formatter, int flags, int width, int precision)`
  Formats the object using the provided formatter.
  `Aprational`
  `frac()`
  Returns the fractional part.
  `protected ApfloatImpl`
  `getImpl(long precision)`
  Returns an `ApfloatImpl` representing the approximation of this aprational up to the requested precision.
  `int`
  `hashCode()`
  Returns a hash code for this aprational.
  `boolean`
  `isInteger()`
  Returns if this number has an integer value.
  `boolean`
  `isShort()`
  Returns if this aprational is "short".
  `Aprational`
  `mod(Aprational x)`
  Calculates the remainder when divided by an aprational.
  `Aprational`
  `multiply(Aprational x)`
  Multiplies two aprational numbers.
  `Aprational`
  `negate()`
  Negative value.
  `Apint`
  `numerator()`
  Numerator of this aprational.
  `long`
  `precision()`
  Returns the precision of this aprational.
  `boolean`
  `preferCompare(Apfloat x)`
  Tests if the comparison with `equals` and `compareTo` should be done in the opposite order.
  `int`
  `radix()`
  Radix of this aprational.
  `long`
  `scale()`
  Returns the scale of this aprational.
  `int`
  `signum()`
  Returns the signum function of this aprational.
  `long`
  `size()`
  Returns the size of this aprational.
  `Aprational`
  `subtract(Aprational x)`
  Subtracts two aprational numbers.
  `boolean`
  `test(Apfloat x)`
  Tests two apfloat numbers for equality.
  `boolean`
  `test(Aprational x)`
  Tests two aprational numbers for equality.
  `Aprational`
  `toRadix(int radix)`
  Convert this aprational to the specified radix.
  `String`
  `toString()`
  Returns a string representation of this aprational.
  `String`
  `toString(boolean pretty)`
  Returns a string representation of this aprational.
  `Apint`
  `truncate()`
  Truncates fractional part.
  `void`
  `writeTo(Writer out)`
  Write a string representation of this aprational to a `Writer`.
  `void`
  `writeTo(Writer out, boolean pretty)`
  Write a string representation of this aprational to a `Writer`.

  ### Methods inherited from class Apfloat

  `add, byteValue, divide, doubleValue, equalDigits, floatValue, imag, intValue, longValue, longValueExact, mod, multiply, precision, real, shortValue, subtract`

  ### Methods inherited from class Apcomplex

  `add, byteValueExact, conj, divide, equalDigits, intValueExact, isZero, multiply, shortValueExact, subtract, test`

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### Aprational

    protected Aprational()
    Default constructor. To be used only by subclasses that overload all needed methods.

  - ### Aprational

    public Aprational(Apint value) throws ApfloatRuntimeException
    Construct an integer aprational whose denominator is one.
    Parameters:
      `value` - The numerator of the number.
    Throws:
      `ApfloatRuntimeException`

  - ### Aprational

    public Aprational(Apint numerator, Apint denominator) throws IllegalArgumentException, ApfloatRuntimeException
    Construct an aprational with the specified numerator and denominator.
    Parameters:
      `numerator` - The numerator.
      `denominator` - The denominator.
    Throws:
      `IllegalArgumentException` - In case the denominator is zero, or if the denominator is not one or the numerator is not zero, and the radix of the numerator and denominator are different.
      `ApfloatRuntimeException`

  - ### Aprational

    public Aprational(String value) throws NumberFormatException, IllegalArgumentException, ApfloatRuntimeException
    Constructs an aprational from a string. The default radix is used.

    The input must be of one of the formats

    `integer`
    `numerator [whitespace] "/" [whitespace] denominator`

    Parameters:
      `value` - The input string.
    Throws:
      `NumberFormatException` - In case the number is invalid.
      `IllegalArgumentException` - In case the denominator is zero.
      `ApfloatRuntimeException`

  - ### Aprational

    public Aprational(String value, int radix) throws NumberFormatException, IllegalArgumentException, ApfloatRuntimeException
    Constructs an aprational from a string with the specified radix.

    The input must be of one of the formats

    `integer`
    `numerator [whitespace] "/" [whitespace] denominator`

    Parameters:
      `value` - The input string.
      `radix` - The radix to be used.
    Throws:
      `NumberFormatException` - In case the number is invalid.
      `IllegalArgumentException` - In case the denominator is zero.
      `ApfloatRuntimeException`

  - ### Aprational

    public Aprational(PushbackReader in) throws IOException, NumberFormatException, IllegalArgumentException, ApfloatRuntimeException
    Reads an aprational from a reader. The default radix is used. The constructor stops reading at the first character it doesn't understand. The reader must thus be a `PushbackReader` so that the invalid character can be returned back to the stream.

    The input must be of one of the formats

    `integer [whitespace]`
    `numerator [whitespace] "/" [whitespace] denominator`

    Parameters:
      `in` - The input stream.
    Throws:
      `IOException` - In case of I/O error reading the stream.
      `NumberFormatException` - In case the number is invalid.
      `IllegalArgumentException` - In case the denominator is zero.
      `ApfloatRuntimeException`

  - ### Aprational

    public Aprational(PushbackReader in, int radix) throws IOException, NumberFormatException, IllegalArgumentException, ApfloatRuntimeException
    Reads an aprational from a reader. The specified radix is used.
    Parameters:
      `in` - The input stream.
      `radix` - The radix to be used.
    Throws:
      `IOException` - In case of I/O error reading the stream.
      `NumberFormatException` - In case the number is invalid.
      `IllegalArgumentException` - In case the denominator is zero.
      `ApfloatRuntimeException`
    See Also:
      - `Aprational(PushbackReader)`

  - ### Aprational

    public Aprational(BigInteger value) throws ApfloatRuntimeException
    Constructs an aprational from a `BigInteger`. The default radix is used.
    Parameters:
      `value` - The numerator of the number.
    Throws:
      `ApfloatRuntimeException`

  - ### Aprational

    public Aprational(BigInteger value, int radix) throws ApfloatRuntimeException
    Constructs an aprational from a `BigInteger` using the specified radix.
    Parameters:
      `value` - The numerator of the number.
      `radix` - The radix of the number.
    Throws:
      `ApfloatRuntimeException`

  - ### Aprational

    public Aprational(double value) throws ApfloatRuntimeException
    Constructs an aprational from a `double`. The exact value represented by the `double` is used. The default radix is used.

    Note that `double`s are presented as an integer multiplied by a power of two (positive or negative). Many numbers can't be represented exactly this way, e.g. `new Aprational(0.1)` won't result in `1/10` but in `3602879701896397/36028797018963968`.

    Parameters:
      `value` - The numerator of the number.
    Throws:
      `ApfloatRuntimeException`

  - ### Aprational

    public Aprational(double value, int radix) throws ApfloatRuntimeException
    Constructs an aprational from a `double` using the specified radix. The exact value represented by the `double` is used.

    Note that `double`s are presented as an integer multiplied by a power of two (positive or negative). Many numbers can't be represented exactly this way, e.g. `new Aprational(0.1)` won't result in `1/10` but in `3602879701896397/36028797018963968`.

    Parameters:
      `value` - The numerator of the number.
      `radix` - The radix of the number.
    Throws:
      `ApfloatRuntimeException`

- ## Method Details

  - ### numerator

    public Apint numerator()
    Numerator of this aprational.
    Returns:
      `n` where `this = n / m`.

  - ### denominator

    public Apint denominator()
    Denominator of this aprational.
    Returns:
      `m` where `this = n / m`.

  - ### radix

    public int radix()
    Radix of this aprational.
    Overrides:
      `radix` in class `Apfloat`
    Returns:
      Radix of this aprational.

  - ### precision

    public long precision() throws ApfloatRuntimeException
    Returns the precision of this aprational.
    Overrides:
      `precision` in class `Apfloat`
    Returns:
      `INFINITE`
    Throws:
      `ApfloatRuntimeException`

  - ### scale

    public long scale() throws ApfloatRuntimeException
    Returns the scale of this aprational. Scale is equal to the number of digits in the aprational's truncated value.

    Zero has a scale of `-INFINITE`.

    Overrides:
      `scale` in class `Apfloat`
    Returns:
      Number of digits in the truncated value of this aprational in the radix in which it's presented.
    Throws:
      `ApfloatRuntimeException`
    See Also:
      - `Apfloat.scale()`

  - ### size

    public long size() throws ApfloatRuntimeException
    Returns the size of this aprational. Size is equal to the number of significant digits in the aprational's floating-point expansion. If the expansion is infinite then this method returns `INFINITE`.

    Zero has a size of `0`.

    Overrides:
      `size` in class `Apfloat`
    Returns:
      Number of significant digits in the floating-point expansion of this aprational in the radix in which it's presented.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.6
    See Also:
      - `Apfloat.size()`

  - ### signum

    public int signum()
    Returns the signum function of this aprational.
    Overrides:
      `signum` in class `Apfloat`
    Returns:
      -1, 0 or 1 as the value of this aprational is negative, zero or positive.

  - ### isShort

    public boolean isShort() throws ApfloatRuntimeException
    Returns if this aprational is "short".
    Overrides:
      `isShort` in class `Apfloat`
    Returns:
      `true` if the aprational is "short", `false` if not.
    Throws:
      `ApfloatRuntimeException`
    See Also:
      - `Apfloat.isShort()`

  - ### isInteger

    public boolean isInteger() throws ApfloatRuntimeException
    Returns if this number has an integer value. Note that this does not necessarily mean that this object is an instance of `Apint`.

    A rational number is an integer if the denominator is one.

    Overrides:
      `isInteger` in class `Apfloat`
    Returns:
      If this number's value is an integer.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.9.0

  - ### negate

    public Aprational negate() throws ApfloatRuntimeException
    Negative value.
    Overrides:
      `negate` in class `Apfloat`
    Returns:
      `-this`.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.1

  - ### add

    public Aprational add(Aprational x) throws ApfloatRuntimeException
    Adds two aprational numbers.
    Parameters:
      `x` - The number to be added to this number.
    Returns:
      `this + x`.
    Throws:
      `ApfloatRuntimeException`

  - ### subtract

    public Aprational subtract(Aprational x) throws ApfloatRuntimeException
    Subtracts two aprational numbers.
    Parameters:
      `x` - The number to be subtracted from this number.
    Returns:
      `this - x`.
    Throws:
      `ApfloatRuntimeException`

  - ### multiply

    public Aprational multiply(Aprational x) throws ApfloatRuntimeException
    Multiplies two aprational numbers.
    Parameters:
      `x` - The number to be multiplied by this number.
    Returns:
      `this * x`.
    Throws:
      `ApfloatRuntimeException`

  - ### divide

    public Aprational divide(Aprational x) throws ArithmeticException, ApfloatRuntimeException
    Divides two aprational numbers.
    Parameters:
      `x` - The number by which this number is to be divided.
    Returns:
      `this / x`.
    Throws:
      `ArithmeticException` - In case the divisor is zero.
      `ApfloatRuntimeException`

  - ### mod

    public Aprational mod(Aprational x) throws ApfloatRuntimeException
    Calculates the remainder when divided by an aprational. The result has the same sign as this number. If `x` is zero, then zero is returned.
    Parameters:
      `x` - The number that is used as the divisor in the remainder calculation.
    Returns:
      `this % x`.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.2

  - ### floor

    public Apint floor() throws ApfloatRuntimeException
    Floor function. Returns the largest (closest to positive infinity) value that is not greater than this aprational and is equal to a mathematical integer.
    Overrides:
      `floor` in class `Apfloat`
    Returns:
      This aprational rounded towards negative infinity.
    Throws:
      `ApfloatRuntimeException`

  - ### ceil

    public Apint ceil() throws ApfloatRuntimeException
    Ceiling function. Returns the smallest (closest to negative infinity) value that is not less than this aprational and is equal to a mathematical integer.
    Overrides:
      `ceil` in class `Apfloat`
    Returns:
      This aprational rounded towards positive infinity.
    Throws:
      `ApfloatRuntimeException`

  - ### truncate

    public Apint truncate() throws ApfloatRuntimeException
    Truncates fractional part.
    Overrides:
      `truncate` in class `Apfloat`
    Returns:
      This aprational rounded towards zero.
    Throws:
      `ApfloatRuntimeException`

  - ### frac

    public Aprational frac() throws ApfloatRuntimeException
    Returns the fractional part. The fractional part is always `0 <= abs(x.frac()) < 1`. The fractional part has the same sign as the number. For the fractional and integer parts, this always holds:

    `x = x.truncate() + x.frac()`

    Overrides:
      `frac` in class `Apfloat`
    Returns:
      The fractional part of this aprational.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.7.0

  - ### toRadix

    public Aprational toRadix(int radix) throws NumberFormatException, ApfloatRuntimeException
    Convert this aprational to the specified radix.
    Overrides:
      `toRadix` in class `Apfloat`
    Parameters:
      `radix` - The radix.
    Returns:
      This number in the specified radix.
    Throws:
      `NumberFormatException` - If the radix is invalid.
      `ApfloatRuntimeException`
    Since:
      1.2

  - ### compareTo

    public int compareTo(Aprational x)
    Compare this aprational to the specified aprational.

    Parameters:
      `x` - Aprational to which this aprational is to be compared.
    Returns:
      -1, 0 or 1 as this aprational is numerically less than, equal to, or greater than `x`.

  - ### compareTo

    public int compareTo(Apfloat x)
    Compare this aprational to the specified apfloat.

    Specified by:
      `compareTo` in interface `Comparable<Apfloat>`
    Overrides:
      `compareTo` in class `Apfloat`
    Parameters:
      `x` - Apfloat to which this aprational is to be compared.
    Returns:
      -1, 0 or 1 as this aprational is numerically less than, equal to, or greater than `x`.

  - ### preferCompare

    public boolean preferCompare(Apfloat x)
    Description copied from class: `Apfloat`
    Tests if the comparison with `equals` and `compareTo` should be done in the opposite order.

    Implementations should avoid infinite recursion.

    Overrides:
      `preferCompare` in class `Apfloat`
    Parameters:
      `x` - The number to compare to.
    Returns:
      `true` if this object should invoke `x.equals(this)` and `-x.compareTo(this)` instead of comparing normally.

  - ### equals

    public boolean equals(Object obj)
    Compares this object to the specified object.

    Note: if two apfloats are compared where one number doesn't have enough precise digits, the mantissa is assumed to contain zeros. See `Apfloat.compareTo(Apfloat)`.

    Overrides:
      `equals` in class `Apfloat`
    Parameters:
      `obj` - The object to compare with.
    Returns:
      `true` if the objects are the same; `false` otherwise.

  - ### test

    public boolean test(Aprational x)
    Tests two aprational numbers for equality. Returns `false` if the numbers are definitely known to be not equal. If `true` is returned, equality is unknown and should be verified by calling `equals(Object)`. This method is usually significantly faster than calling `equals(Object)`.
    Parameters:
      `x` - The number to test against.
    Returns:
      `false` if the numbers are definitely not equal, `true` if unknown.
    Since:
      1.10.0

  - ### test

    public boolean test(Apfloat x) throws ApfloatRuntimeException
    Description copied from class: `Apfloat`
    Tests two apfloat numbers for equality. Returns `false` if the numbers are definitely known to be not equal. If `true` is returned, equality is unknown and should be verified by calling `Apfloat.equals(Object)`. This method is usually significantly faster than calling `equals(Object)`.
    Overrides:
      `test` in class `Apfloat`
    Parameters:
      `x` - The number to test against.
    Returns:
      `false` if the numbers are definitely not equal, `true` if unknown.
    Throws:
      `ApfloatRuntimeException`

  - ### hashCode

    public int hashCode()
    Returns a hash code for this aprational.
    Overrides:
      `hashCode` in class `Apfloat`
    Returns:
      The hash code value for this object.

  - ### toString

    public String toString()
    Returns a string representation of this aprational.
    Overrides:
      `toString` in class `Apcomplex`
    Returns:
      A string representing this object.

  - ### toString

    public String toString(boolean pretty) throws ApfloatRuntimeException
    Returns a string representation of this aprational.
    Overrides:
      `toString` in class `Apfloat`
    Parameters:
      `pretty` - `true` to use a fixed-point notation, `false` to use an exponential notation.
    Returns:
      A string representing this object.
    Throws:
      `ApfloatRuntimeException`

  - ### writeTo

    public void writeTo(Writer out) throws IOException, ApfloatRuntimeException
    Write a string representation of this aprational to a `Writer`.
    Overrides:
      `writeTo` in class `Apcomplex`
    Parameters:
      `out` - The output `Writer`.
    Throws:
      `IOException` - In case of I/O error writing to the stream.
      `ApfloatRuntimeException`

  - ### writeTo

    public void writeTo(Writer out, boolean pretty) throws IOException, ApfloatRuntimeException
    Write a string representation of this aprational to a `Writer`.
    Overrides:
      `writeTo` in class `Apfloat`
    Parameters:
      `out` - The output `Writer`.
      `pretty` - `true` to use a fixed-point notation, `false` to use an exponential notation.
    Throws:
      `IOException` - In case of I/O error writing to the stream.
      `ApfloatRuntimeException`

  - ### formatTo

    public void formatTo(Formatter formatter, int flags, int width, int precision)
    Formats the object using the provided formatter.
    Specified by:
      `formatTo` in interface `Formattable`
    Overrides:
      `formatTo` in class `Apfloat`
    Parameters:
      `formatter` - The formatter.
      `flags` - The flags to modify the output format.
      `width` - The minimum number of characters to be written to the output, or `-1` for no minimum.
      `precision` - The maximum number of characters to be written to the output, or `-1` for no maximum.
    Since:
      1.3
    See Also:
      - `Apfloat.formatTo(Formatter,int,int,int)`

  - ### getImpl

    protected ApfloatImpl getImpl(long precision) throws ApfloatRuntimeException
    Returns an `ApfloatImpl` representing the approximation of this aprational up to the requested precision.

    Overrides:
      `getImpl` in class `Apfloat`
    Parameters:
      `precision` - Precision of the `ApfloatImpl` that is needed.
    Returns:
      An `ApfloatImpl` representing this object to the requested precision.
    Throws:
      `ApfloatRuntimeException`