RationalImpl (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.record.impl

## Class RationalImpl

- java.lang.Object
- - java.lang.Number
  - - tv.amwa.maj.record.impl.RationalImpl

- All Implemented Interfaces:
    Serializable, Cloneable, Comparable<Rational>, XMLSerializable, Rational

      public final class RationalImpl
      extends Number
      implements Rational, Serializable, XMLSerializable, Cloneable, Comparable<Rational>

  Implements a rational number by means of a Java integer numerator (`Int32`) and a Java integer (`Int32`) denominator.

  This implementation of the AAF rational number interface extends Java's `Number` class so that its integer and floating point value can be found, by methods such as `intValue()` and `doubleValue()`. Numerical comparison with other numbers can take place using the `compareToNumber(Number)` method.

  See Also:
    `TypeDefinitions.Rational`, `TimelineTrack.getEditRate()`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `MYSQL_COLUMN_DEFINITION`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RationalImpl()` Create a rational number with a numerator of 0 and a denominator of 1.
    `RationalImpl(int numerator, int denominator)` Create a rational number from its numerator and denominator.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendXMLChildren(Node parent)` Append extra child elements to the given parent node to serialize the value of an object to an XML fragment.
    `Rational` | `clone()` Create a cloned copy of this rational value.
    `int` | `compareTo(Rational o)` Numerically compare this rational with the given rational value.
    `int` | `compareToNumber(Number n)` Numerically compare this value with another number.
    `double` | `doubleValue()` Returns the rational calculated as double value.
    `boolean` | `equals(Object o)` Tests to see if this rational value is equal to the given value.
    `float` | `floatValue()` Returns the rational calculated as float value.
    `static Rational` | `fromPersistentForm(String rational)`
    `String` | `getComment()` Include a comment when serializing a value to XML.
    `int` | `getDenominator()` Returns the denominator of the value represented by this rational number.
    `int` | `getNumerator()` Returns the numerator of the value represented by this rational number.
    `int` | `hashCode()`
    `int` | `intValue()` Calculates the integer value of the numerator divided by the denominator.
    `long` | `longValue()` Calculates the long value corresponding to the numerator devided by the denominator.
    `static RationalImpl` | `parseFactory(String rationalAsString)` Convert a string representation of a rational value into a value of this type.
    `void` | `setDenominator(int denominator)` Sets the denominator of the value represented by this rational number.
    `void` | `setNumerator(int numerator)` Sets the numerator of the value represented by this rational number.
    `void` | `setRational(int numerator, int denominator)` Set the value of this rational number with both its numerator and denominator.
    `static String` | `toPersistentForm(Rational rational)`
    `String` | `toString()` Returns a string representation of this rational value as the numerator, followed by a slash (/), followed by the denominator.

    - ### Methods inherited from class java.lang.Number

      `byteValue, shortValue`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### MYSQL_COLUMN_DEFINITION

          public static final String MYSQL_COLUMN_DEFINITION

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### RationalImpl

          public RationalImpl(@Int32
                              int numerator,
                              @Int32
                              int denominator)

      Create a rational number from its numerator and denominator.

      Parameters:
        `numerator` -
        `denominator` -

    - #### RationalImpl

          public RationalImpl()

      Create a rational number with a numerator of 0 and a denominator of 1.

  - ### Method Detail

    - #### parseFactory

          public static final RationalImpl parseFactory(String rationalAsString)
                                                 throws NullPointerException,
                                                        ParseException

      Convert a string representation of a rational value into a value of this type. The string representation is expected to take the form of the numerator, followed by a slash character ('`/`'), followed by the denominator, e.g. "`-123/4567`".

      Parameters:
        `rationalAsString` - String to use to create a rational value.
      Returns:
        Corresponding rational value.
      Throws:
        `NullPointerException` - The rational as string argument is `null`.
        `PraseException` - The string is not formatted as a rational number representation.
        `ParseException`
      See Also:
        `toString()`

    - #### getDenominator

          @Int32
          public final int getDenominator()

      Description copied from interface: `Rational`

      Returns the denominator of the value represented by this rational number.

      Specified by:
        `getDenominator` in interface `Rational`
      Returns:
        Denominator part of the rational value.

    - #### setDenominator

          public final void setDenominator(@Int32
                                           int denominator)

      Description copied from interface: `Rational`

      Sets the denominator of the value represented by this rational number.

      Specified by:
        `setDenominator` in interface `Rational`
      Parameters:
        `denominator` - Denominator part of the rational value.

    - #### getNumerator

          @Int32
          public final int getNumerator()

      Description copied from interface: `Rational`

      Returns the numerator of the value represented by this rational number.

      Specified by:
        `getNumerator` in interface `Rational`
      Returns:
        Numerator part of the rational value.

    - #### setNumerator

          public final void setNumerator(@Int32
                                         int numerator)

      Description copied from interface: `Rational`

      Sets the numerator of the value represented by this rational number.

      Specified by:
        `setNumerator` in interface `Rational`
      Parameters:
        `numerator` - Numerator part of the rational value.

    - #### setRational

          public final void setRational(@Int32
                                        int numerator,
                                        @Int32
                                        int denominator)

      Description copied from interface: `Rational`

      Set the value of this rational number with both its numerator and denominator.

      Specified by:
        `setRational` in interface `Rational`
      Parameters:
        `numerator` - Numerator part of the rational value.
        `denominator` - Denominator part of the rational value.

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public final boolean equals(Object o)

      Tests to see if this rational value is equal to the given value. Two values are equals if and only if they are both rational values with the same numerator and denominator. For a numerical comparison, use `compareTo(tv.amwa.maj.record.Rational)`.

      Overrides:
        `equals` in class `Object`
      Returns:
        Is the given value equal to this one?
      See Also:
        `Object.equals(java.lang.Object)`

    - #### toString

          public final String toString()

      Returns a string representation of this rational value as the numerator, followed by a slash (/), followed by the denominator. For example, "1/4". The format is the same as that parsed by `parseFactory(String)`.

      Specified by:
        `toString` in interface `Rational`
      Overrides:
        `toString` in class `Object`
      Returns:
        This rational value formatted as a string.
      See Also:
        `parseFactory(String)`

    - #### doubleValue

          public final double doubleValue()

      Returns the rational calculated as double value. In the event of a division by zero, a value of `Double.POSITIVE_INFINITY` is returned.

      Specified by:
        `doubleValue` in interface `Rational`
      Specified by:
        `doubleValue` in class `Number`
      Returns:
        Value of this rational as a Java double.
      See Also:
        `Number.doubleValue()`

    - #### floatValue

          public final float floatValue()

      Returns the rational calculated as float value. In the event of a division by zero, a value of `Float.POSITIVE_INFINITY` is returned.

      Specified by:
        `floatValue` in class `Number`
      See Also:
        `Number.floatValue()`

    - #### intValue

          public final int intValue()
                             throws ArithmeticException

      Calculates the integer value of the numerator divided by the denominator. If the magnitude of the numerator is less than the denominator, a value of `0` is returned.

      Specified by:
        `intValue` in class `Number`
      Throws:
        `ArithmeticException` - The denominator is zero.
      See Also:
        `Number.intValue()`

    - #### longValue

          public final long longValue()
                               throws ArithmeticException

      Calculates the long value corresponding to the numerator devided by the denominator. If the magnitude of the numerator is less than the denominator, a value of `0` is returned.

      Specified by:
        `longValue` in class `Number`
      Throws:
        `ArithmeticException` - The denominator is 0.
      See Also:
        `Number.longValue()`

    - #### compareTo

          public final int compareTo(Rational o)
                              throws NullPointerException

      Numerically compare this rational with the given rational value.

      Specified by:
        `compareTo` in interface `Comparable<Rational>`
      Parameters:
        `o` - Value to compare with this one with.
      Returns:
        A value of `-1` if this value is less than the one given, `1` if this value is greater than the one given and `0` if they are equal.
      Throws:
        `NullPointerException` - Argument is null.
      See Also:
        `Comparable.compareTo(Object)`

    - #### compareToNumber

          public final int compareToNumber(Number n)
                                    throws NullPointerException

      Numerically compare this value with another number.

      Parameters:
        `n` - Number to compare with this one.
      Returns:
        A value of `-1` if this value is less than the one given, `1` if this value is greater than the one given and `0` if they are equal.
      Throws:
        `NullPointerException` - Argument is null.

    - #### clone

          public final Rational clone()

      Description copied from interface: `Rational`

      Create a cloned copy of this rational value.

      Specified by:
        `clone` in interface `Rational`
      Overrides:
        `clone` in class `Object`
      Returns:
        Cloned copy of this rational value.

    - #### appendXMLChildren

          public void appendXMLChildren(Node parent)

      Description copied from interface: `XMLSerializable`

      Append extra child elements to the given parent node to serialize the value of an object to an XML fragment. Methods of the `XMLBuilder` class are provided to help with this process.

      Specified by:
        `appendXMLChildren` in interface `XMLSerializable`
      Parameters:
        `parent` - XML parent element to append child nodes to.

    - #### getComment

          public String getComment()

      Description copied from interface: `XMLSerializable`

      Include a comment when serializing a value to XML. The comment will be inserted as the first child node of the element representing the class.

      Specified by:
        `getComment` in interface `XMLSerializable`
      Returns:
        Comment to add as the first child node of the element representing this class.

    - #### toPersistentForm

          public static final String toPersistentForm(Rational rational)

    - #### fromPersistentForm

          public static final Rational fromPersistentForm(String rational)

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.