Rational (humble-video-noarch 0.3.0 API)

java.lang.Object
- io.humble.ferry.RefCounted
- - io.humble.video.Rational

```
public class Rational
extends RefCounted
```
This class wraps represents a Rational number.

Video formats often use rational numbers, and converting between
them willy nilly can lead to rounding errors, and eventually, out
of sync problems. Therefore we use IRational objects to pass
around Rational Numbers and avoid conversion until the very last moment.

Note: There are some static convenience methods
in this class that start with s*. They start with s
(as opposed to overloading methods (e.g. sAdd(...) vs. add(...)).

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Rational.Rounding
A type to specify how rounding should be done.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Rational.Rounding` A type to specify how rounding should be done.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Rational`	`add(Rational arg)` Adds arg to this rational
`int`	`compareTo(Rational other)` Compare a rational to this rational
`Rational`	`copy()` Creates a new IRational object by copying (by value) this object.
`Rational`	`copyReference()` Create a new Rational object that is actually referring to the exact same underlying native object.
`Rational`	`divide(Rational arg)` Divides this rational by arg.
`boolean`	`equals(Object obj)` Compares two values, returning true if the underlying objects in native code are the same object.
`int`	`getDenominator()` Get the denominator for this rational.
`double`	`getDouble()` Rational to double conversion.
`int`	`getNumerator()` Get the numerator for this rational.
`double`	`getValue()` An alias for #getDouble() but matching JavaBean conventions.
`int`	`hashCode()` Get a hashable value for this object.
`void`	`init()` Marks this object as finalized and immutable.
`boolean`	`isFinalized()` Returns true if #init() has been called and this object is now considered finalized and immutable.
`boolean`	`isNegative()` Is this number negative?
`boolean`	`isPositive()` Is this number positive?
`static Rational`	`make()` Get a new rational that will be set to 0/1. The rational will not have #init() called and hence will be modifiable by #setValue(double) until #init() is called.
`static Rational`	`make(double d)` Converts a double precision floating point number to a rational.
`static Rational`	`make(int num, int den)` Create a rational from a numerator and denominator. We will always reduce this to the lowest num/den pair we can, but never having den exceed what was passed in.
`static Rational`	`make(Rational src)` Creates deep copy of a Rational from another Rational.
`Rational`	`multiply(Rational arg)` Multiplies this number by arg
`static boolean`	`negative(Rational num)` Is this number not null and negative.
`static boolean`	`positive(Rational num)` Is this number not null and positive.
`int`	`reduce(long num, long den, long max)` Reduce a fraction to it's lowest common denominators. This is useful for framerate calculations.
`static long`	`rescale(long srcValue, int dstNumerator, int dstDenominator, int srcNumerator, int srcDenominator, Rational.Rounding rounding)` Rescales a long value to another long value.
`long`	`rescale(long origValue, Rational origBase)` Takes a value scaled in increments of origBase and gives the equivalent value scaled in terms of this Rational.
`long`	`rescale(long origValue, Rational origBase, Rational.Rounding rounding)` Takes a value scaled in increments of origBase and gives the equivalent value scaled in terms of this Rational.
`static Rational`	`sAdd(Rational a, Rational b)` Adds a to b.
`static int`	`sCompareTo(Rational a, Rational b)` Compare two rationals
`static Rational`	`sDivide(Rational a, Rational b)` Divides a by b.
`void`	`setDenominator(int value)` Sets the denominator on this object.
`void`	`setNumerator(int value)` Sets the numerator on this object.
`void`	`setValue(double value)` Sets the numerator and denominator on this object by reducing the double to the closest integer numerator and denominator.
`static Rational`	`sMultiply(Rational a, Rational b)` Multiples a by b.
`static int`	`sReduce(Rational dst, long num, long den, long max)` Reduce a fraction to it's lowest common denominators. This is useful for framerate calculations.
`static long`	`sRescale(long origValue, Rational origBase, Rational newBase)` Takes a value scaled in increments of origBase and gives the equivalent value scaled in terms of this Rational.
`static long`	`sRescale(long origValue, Rational origBase, Rational newBase, Rational.Rounding rounding)` Takes a value scaled in increments of origBase and gives the equivalent value scaled in terms of this Rational.
`static Rational`	`sSubtract(Rational a, Rational b)` Subtracts a from b.
`Rational`	`subtract(Rational arg)` Subtracts arg from this rational
`String`	`toString()` Prints the contents of this object as a fraction.

Methods inherited from class io.humble.ferry.RefCounted
delete, getCurrentRefCount

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - copyReference
```
public Rational copyReference()
```
    Create a new Rational object that is actually referring to the exact same underlying native object.
    
    Overrides:
    
    copyReference in class RefCounted
    
    Returns:
    
    the new Java object.
  - equals
```
public boolean equals(Object obj)
```
    Compares two values, returning true if the underlying objects in native code are the same object. That means you can have two different Java objects, but when you do a comparison, you'll find out they are the EXACT same object.
    
    Overrides:
    
    equals in class Object
    
    Returns:
    
    True if the underlying native object is the same. False otherwise.
  - hashCode
```
public int hashCode()
```
    Get a hashable value for this object.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    the hashable value.
  - toString
```
public String toString()
```
    Prints the contents of this object as a fraction.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    "getNumerator()/getDenominator()"
  - isPositive
```
public boolean isPositive()
```
    Is this number positive?
    
    Returns:
    
    true if > 0; false if not.
  - positive
```
public static boolean positive(Rational num)
```
    Is this number not null and positive.
    
    Parameters:
    
    num - the number; may be null
    
    Returns:
    
    true if not-null and > 0; else false;
  - isNegative
```
public boolean isNegative()
```
    Is this number negative?
    
    Returns:
    
    true if < 0; false if not.
  - negative
```
public static boolean negative(Rational num)
```
    Is this number not null and negative.
    
    Parameters:
    
    num - the number; may be null
    
    Returns:
    
    true if not-null and < 0; else false;
  - getNumerator
```
public int getNumerator()
```
    Get the numerator for this rational.
    
    Returns:
    
    the numerator.
  - getDenominator
```
public int getDenominator()
```
    Get the denominator for this rational.
    
    Returns:
    
    the denominator.
  - copy
```
public Rational copy()
```
    Creates a new IRational object by copying (by value) this object.
    
    Returns:
    
    the new object
  - compareTo
```
public int compareTo(Rational other)
```
    Compare a rational to this rational
    
    Parameters:
    
    other - second rational
    
    Returns:
    
    0 if this==other, 1 if this>other and -1 if this<other.
  - sCompareTo
```
public static int sCompareTo(Rational a,
                             Rational b)
```
    Compare two rationals
    
    Parameters:
    
    a - the first rational
    
    b - the second rational
    
    Returns:
    
    0 if a==b, 1 if a>b and -1 if b<a.
  - getDouble
```
public double getDouble()
```
    Rational to double conversion.
    
    Returns:
    
    (double) a
  - reduce
```
public int reduce(long num,
                  long den,
                  long max)
```
    Reduce a fraction to it's lowest common denominators.
    This is useful for framerate calculations.
    
    Parameters:
    
    num - the src numerator.
    
    den - the src denominator.
    
    max - the maximum allowed for nom & den in the reduced fraction.
    
    Returns:
    
    1 if exact, 0 otherwise
  - sReduce
```
public static int sReduce(Rational dst,
                          long num,
                          long den,
                          long max)
```
    Reduce a fraction to it's lowest common denominators.
    This is useful for framerate calculations.
    
    Parameters:
    
    dst - The destination rational
    
    num - the src numerator.
    
    den - the src denominator.
    
    max - the maximum allowed for nom & den in the reduced fraction.
    
    Returns:
    
    1 if exact, 0 otherwise
  - multiply
```
public Rational multiply(Rational arg)
```
    Multiplies this number by arg
    
    Parameters:
    
    arg - number to mulitply by.
    
    Returns:
    
    this*arg.
  - sMultiply
```
public static Rational sMultiply(Rational a,
                                 Rational b)
```
    Multiples a by b.
    
    Parameters:
    
    a - the first number
    
    b - the second number.
    
    Returns:
    
    a*b
  - divide
```
public Rational divide(Rational arg)
```
    Divides this rational by arg.
    
    Parameters:
    
    arg - The divisor to use.
    
    Returns:
    
    this/arg.
  - sDivide
```
public static Rational sDivide(Rational a,
                               Rational b)
```
    Divides a by b.
    
    Parameters:
    
    a - The first number.
    b The second number.
    
    Returns:
    
    a/b.
  - subtract
```
public Rational subtract(Rational arg)
```
    Subtracts arg from this rational
    
    Parameters:
    
    arg - The amount to subtract from this.
    
    Returns:
    
    this-arg.
  - sSubtract
```
public static Rational sSubtract(Rational a,
                                 Rational b)
```
    Subtracts a from b.
    
    Parameters:
    
    a - The first number.
    b The second number.
    
    Returns:
    
    a-b.
  - add
```
public Rational add(Rational arg)
```
    Adds arg to this rational
    
    Parameters:
    
    arg - The amount to add to this.
    
    Returns:
    
    this+arg.
  - sAdd
```
public static Rational sAdd(Rational a,
                            Rational b)
```
    Adds a to b.
    
    Parameters:
    
    a - The first number.
    b The second number.
    
    Returns:
    
    a+b.
  - rescale
```
public long rescale(long origValue,
                    Rational origBase)
```
    Takes a value scaled in increments of origBase and gives the
    equivalent value scaled in terms of this Rational.
    
    Parameters:
    
    origValue - The original int64_t value you care about.
    
    origBase - The original base Rational that origValue is scaled with.
    
    Returns:
    
    The new integer value, scaled in units of this IRational.
  - sRescale
```
public static long sRescale(long origValue,
                            Rational origBase,
                            Rational newBase)
```
    Takes a value scaled in increments of origBase and gives the
    equivalent value scaled in terms of this Rational.
    
    Parameters:
    
    origValue - The original int64_t value you care about.
    
    origBase - The original base Rational that origValue is scaled with.
    
    newBase - The rational you want to rescale origValue into.
    
    Returns:
    
    The new integer value, scaled in units of this IRational.
  - make
```
public static Rational make()
```
    Get a new rational that will be set to 0/1.
    The rational will not have #init() called
    and hence will be modifiable by #setValue(double)
    until #init() is called.
    
    Returns:
    
    a rational number object
  - make
```
public static Rational make(double d)
```
    Converts a double precision floating point number to a rational.
    
    Parameters:
    
    d - double to convert
    
    Returns:
    
    A new Rational; caller must release() when done.
  - make
```
public static Rational make(Rational src)
```
    Creates deep copy of a Rational from another Rational.
    
    Parameters:
    
    src - The source Rational to copy.
    
    Returns:
    
    A new Rational; Returns null
    if src is null.
  - make
```
public static Rational make(int num,
                            int den)
```
    Create a rational from a numerator and denominator.
    
    We will always reduce this to the lowest num/den pair
    we can, but never having den exceed what was passed in.
    
    Parameters:
    
    num - The numerator of the resulting Rational
    
    den - The denominator of the resulting Rational
    
    Returns:
    
    A new Rational;
  - rescale
```
public long rescale(long origValue,
                    Rational origBase,
                    Rational.Rounding rounding)
```
    Takes a value scaled in increments of origBase and gives the
    equivalent value scaled in terms of this Rational.
    
    Parameters:
    
    origValue - The original int64_t value you care about.
    
    origBase - The original base Rational that origValue is scaled with.
    
    rounding - How you want rounding to occur
    
    Returns:
    
    The new integer value, scaled in units of this IRational.
  - sRescale
```
public static long sRescale(long origValue,
                            Rational origBase,
                            Rational newBase,
                            Rational.Rounding rounding)
```
    Takes a value scaled in increments of origBase and gives the
    equivalent value scaled in terms of this Rational.
    
    Parameters:
    
    origValue - The original int64_t value you care about.
    
    origBase - The original base Rational that origValue is scaled with.
    
    newBase - The rational you want to rescale origValue into.
    
    rounding - How you want rounding to occur
    
    Returns:
    
    The new integer value, scaled in units of this IRational.
  - rescale
```
public static long rescale(long srcValue,
                           int dstNumerator,
                           int dstDenominator,
                           int srcNumerator,
                           int srcDenominator,
                           Rational.Rounding rounding)
```
    Rescales a long value to another long value.
    
    This method doesn't use IRational values, but
    instead uses numerators and denominators
    passed in by the caller. It will not result
    in any memory allocations.
    
    Parameters:
    
    srcValue - The value to rescale.
    
    dstNumerator - The numerator of the units
    you want to scale to. Must be non-zero.
    
    dstDenominator - The denominator of the units
    you want to scale to. Must be non-zero.
    
    srcNumerator - The numerator of the units
    srcValue is expressed in.
    Must be non-zero.
    
    srcDenominator - The denominator of the units
    srcValue is expressed in.
    Must be non-zero.
    
    rounding - How you want rounding to occur
    
    Returns:
    
    The new integer value, scaled in units of
    dstNumerator/dstNumerator, or 0 if there
    is a parameter error.
  - setNumerator
```
public void setNumerator(int value)
```
    Sets the numerator on this object.
    
    If #isFinalized is true, then this method is ignored.
  - setDenominator
```
public void setDenominator(int value)
```
    Sets the denominator on this object.
    
    If #isFinalized is true, then this method is ignored.
  - setValue
```
public void setValue(double value)
```
    Sets the numerator and denominator on this object by
    reducing the double to the closest integer numerator
    and denominator.
    
    If #isFinalized is true, then this method is ignored.
  - getValue
```
public double getValue()
```
    An alias for #getDouble() but matching JavaBean
    conventions.
  - isFinalized
```
public boolean isFinalized()
```
    Returns true if #init() has been called and
    this object is now considered finalized and immutable.
  - init
```
public void init()
```
    Marks this object as finalized and immutable. Any
    setters called after the first #init() call
    will be ignored.
    
    Most make methods will call this method
    automatically, with the exception of the blank factory
    method #make().

Class Rational

Nested Class Summary

Method Summary

Methods inherited from class io.humble.ferry.RefCounted

Methods inherited from class java.lang.Object

Method Detail

copyReference

equals

hashCode

toString

isPositive

positive

isNegative

negative

getNumerator

getDenominator

copy

compareTo

sCompareTo

getDouble

reduce

sReduce

multiply

sMultiply

divide

sDivide

subtract

sSubtract

add

sAdd

rescale

sRescale

make

make

make

make

rescale

sRescale

rescale

setNumerator

setDenominator

setValue

getValue

isFinalized

init