com.rubecula.jquantity
Class Rational

java.lang.Object
  |
  +--java.lang.Number
        |
        +--com.rubecula.jquantity.BaseNumber
              |
              +--com.rubecula.jquantity.MutableNumber
                    |
                    +--com.rubecula.jquantity.Rational

All Implemented Interfaces:

Arithmetical, Arithmutable, Auditable, java.lang.Cloneable, java.lang.Comparable, Divisible, Estimable, Fuzzy, FuzzyMutable, Identifiable, Mutable, Normalizable, Presentable, java.io.Serializable, Trigonometrical

Direct Known Subclasses:

Value

public class Rational

extends MutableNumber

implements Divisible, Estimable, FuzzyMutable, Trigonometrical, Normalizable

Public class to represent precise rational numbers. What's wrong with BigDecimal, you might ask? BigDecimal can only represent rational numbers where the denominator is a power of ten. Many numbers are just not like that.
Furthermore, both numerator and denominator can be either exact integers (i.e. Manifests or WholeNumbers) or fuzzy integers (i.e. FuzzInt) so that Rational can itself represent a complete range of potentially fuzzy numbers. Infinity is a legal Rational number.

Version:

$Revision: 1.14 $

Author:

Robin Hillyard

See Also:

Serialized Form

Nested Class Summary

class

Rational.RValueException Title: RValueException

Field Summary

protected BaseNumber	_Denominator _Denominator is the denominator of the rational quantity defined by this.
protected double	_Estimate _Estimate is the best estimate of the value (for debugging purposes)
protected BaseNumber	_Numerator _Numerator is the numerator of the rational quantity defined by this.
(package private) static Rational	$_2Pi
(package private) static Rational	$_c By definition, the velocity of light: 299792458.
(package private) static Rational	$_degF Degrees Fahrenheit/Celsius offset: 32.
(package private) static Rational	$_degR Degrees Rankine/Kelvin conversion: 5/9.
(package private) static Rational	$_Degree2Radian
(package private) static Rational	$_Pi_12
(package private) static Rational	$_Pi_2
(package private) static Rational	$_Pi_4
(package private) static Rational	$_Tan15Deg 2 - $Rt3.
(package private) static Rational	$_Tan30Deg 1/$Rt3.
static Rational	$0 $0 is the Rational representation of the exact value 0.
static Rational	$1 $1 is the Rational representation of the exact value 1.
static Rational	$1_2 $1_2 is the Rational representation of the exact value 1/2.
static Rational	$10 $10 is the Rational representation of the exact value 10.
(package private) static Rational	$12
static Rational	$2 $2 is the Rational representation of the exact value 2.
(package private) static Rational	$3
(package private) static Rational	$6
static Rational	$E Value of E as a Rational.
static Rational	$Infinity $Infinity is the Rational representation of the (exact) value of infinity, i.e.
(package private) static java.math.BigInteger	$MaxInt Integer.MAX_VALUE.
(package private) static Rational	$NaN
static Rational	$Pi Value of Pi as a Rational.
(package private) static Rational	$Rt2 InitialValueOf($S_Rt2).
(package private) static Rational	$Rt3 InitialValueOf($S_Rt3).
(package private) static Rational	$Rt5 InitialValueOf($S_Rt5).
(package private) static java.lang.String	$S_Rt2 1.414213562373095048801688724209698078569671875377
(package private) static java.lang.String	$S_Rt3 1.732050807568877293527446341505872366942805253810
(package private) static java.lang.String	$S_Rt5 2.2360679774997896964091736687312762354406183596

Fields inherited from class com.rubecula.jquantity.MutableNumber

$__1

Fields inherited from interface com.rubecula.jquantity.Fuzzy

$DistGaussian, $DistInvalid, $DistNone, $DistUniform, $Names

Constructor Summary

	Rational() Empty constructor to make an undefined Rational object.
	Rational(Integral value) Constructs a non-explicitly identified Rational representing the ratio of value divided by unity.
	Rational(Integral numerator, Integral denominator) Constructs a non-explicitly identified, normalized Rational representing the ratio of numerator divided by denominator.
protected	Rational(Integral numerator, Integral denominator, boolean normalize) Constructs a non-explicitly identified Rational representing the ratio of numerator divided by denominator, with optional normalization.
protected	Rational(Integral numerator, Integral denominator, boolean normalize, java.lang.String identifier) Constructs an identified Rational representing the ratio of numerator divided by denominator, with optional normalization.
	Rational(Integral numerator, Integral denominator, java.lang.String identifier) Constructs an identified Rational representing the ratio of numerator divided by denominator.
	Rational(Integral numerator, java.lang.String identifier) Constructs an identified Rational representing the ratio of numerator divided by denominator, with optional normalization.
	Rational(java.lang.String string) Secondary constructor to create a Rational from a String.

Method Summary

(package private) Rational	absRational()
void	add(BaseNumber that) MUTATING Instance method to add another BaseNumber into this object.
protected void	addTops(Rational other)
Trigonometrical	arctanX2() Method to evaluate the arctangent function.
java.lang.String	audit(java.lang.String label) Method to return a detailed string from an arithmetical object for debugging purposes.
(package private) int	characteristic()
(package private) static int	Characteristic(java.math.BigDecimal x)
java.lang.Object	clone() Creates and returns a copy of this object.
int	compareTo(Integral val) Compares this Rational with the specified Rational.
int	compareTo(Rational val) Compares this Rational with the specified Rational.
protected int	compareTo(Rational val, boolean absolute) Compares this Rational with the specified Rational.
(package private) Rational	differenceRational(Rational subtrahend) Method to yield the difference of this less a BaseNumber (subtrahend).
void	divide(BaseNumber that) MUTATING method to replace this by the sum of this and that
double	doubleValue() Returns the value of the specified number as a double.
Trigonometrical	exp() Method to evaluate the exponential function.
(package private) float	expFloat(float factor)
protected void	factor(Integral divisor) MUTATING METHOD: Replaces value with (this / divisor).
float	floatValue() Returns the value of the specified number as a float.
(package private) Rational	fold(Rational range) Method to force this into a specific range.
(package private) long	getBottom()
double	getBound() Method to get the relative bound of this Rational.
double	getBoundAbs() Method to get the absolute bound of non-fuzzy value.
protected BaseNumber	getDenominator() Method to access the denominator of this Rational object.
protected Integral	getDenominatorAsIntegral() Method to access the denominator of this Rational object.
double	getEstimate() Method to get the current estimate of an arithmetical value.
(package private) static int	GetExtraPrecisionDigits(int places, int requiredExtrasLength, Rational value, double tolerance)
int	getModel() Method to get the error distribution model of this non-fuzzy object.
protected BaseNumber	getNumerator() Method to access the numerator of this Rational object.
protected Integral	getNumeratorAsIntegral() Method to access the numerator of this Rational object.
(package private) static int	GetPrecisionPlaces(Rational upperBound, Rational lowerBound, double tolerance, boolean gaussian)
(package private) long	getTop()
Rational	half()
int	hashCode()
int	intValue() Method to yield the equivalent integer value for this object.
Divisible	inverse() Method to yield the reciprocal of this and return it as the result.
(package private) Rational	inverseRational()
void	invert() MUTATING Instance method to invert this (i.e.
boolean	isExact() Method to determine if the quantity represented is non-fuzzy;
boolean	isInfinite() Method to determine if an arithmetical object is infinite.
boolean	isInteger() Method determines if it is safe and appropriate to convert this arithmetical object into BigInteger.
(package private) boolean	isNaN()
boolean	isUnity() Method to determine if this arithmetical object has the exact value of 1.
Trigonometrical	log() Method to evaluate the natural log function.
long	longValue() Method to yield the equivalent integer value for this object.
(package private) long	longValue(double tolerance) Method to yield the integer value of this object.
(package private) double	magnitude()
static void	main(java.lang.String[] args) Main method for testing this class.
Presentable	makePresentableInstance(Presentation presentation) Instance method to convert a Presentation into a Presentable.
protected BaseNumber	minus() Method to yield a copy of this but with the sign changed.
(package private) Rational	minusRational() Method to yield a copy of this but with the sign changed.
(package private) Rational	modulo(long x)
(package private) float	multFloat(float factor)
void	multiply(BaseNumber that) MUTATING Instance method to multiply another Arithmetical into this object.
protected void	multiplyTopAndBottom(BaseNumber factor) MUTATING method to multiply the top and bottom of a rational equally.
void	negate() MUTATING Instance method to negate this
void	normalize() MUTATING instance method to remove any common factors from top and bottom.
(package private) Rational	normalizeToBigDecimal(double tolerance) Normalize this such that the denominator is a power of ten AND the value of the result differs from the value of this by not more than the tolerance.
(package private) Rational	normalizeToInt(double tolerance)
static Rational	Parse(NumberPresentation presentation, java.lang.String identifier) Translates the ValuePresentation representation of a FuzzInt in the specified radix into a FuzzInt.
static Presentable	Parse(Presentation presentation) Create a FuzzInt from a Presentation and return it as a Presentable.
(package private) int	places()
protected BaseNumber	pow(int power) Method to raise this to the power power return the result.
Presentation	present(AttrMap attributes) Convert this Presentable object into a Presentation, according to the set of attributes provided.
(package private) Rational	productRational(Rational multiplicand) Method to multiply multiplicand to this and return their product as the result.
Divisible	quotient(BaseNumber divisor) Method to divide this by multiplicand and return the quotient as the result.
(package private) Rational	quotientRational(Rational that)
void	raiseToPower(int power) MUTATING Instance method to raise this to power power.
(package private) Rational	root(int p) method root: to yield an exact (integer) Rational for the root of a positive integral Rational.
void	scale(double factor) MUTATING Instance method to multiply this by a (double) scale factor
void	scale(long factor) MUTATING Instance method to multiply this by a scale factor.
Divisible	scaled(double multiplicand) Method to multiply multiplicand by this and return their product as the result.
protected BaseNumber	scaled(long multiplicand) Method to multiply multiplicand by this and return their product as the result.
void	setBound(double bound) Method to set the relative bound of fuzzy value.
protected void	setBoundAbs(double bound) Method to set the absolute bound of fuzzy value.
void	setModel(int model) Method to set the error distribution model.
int	signum() Method to find the sign of the magnitude of this arithmetical object.
(package private) Rational	squareRational()
void	subtract(Rational that) MUTATING method to replace this by the difference of this and that
(package private) Rational	sumRational(Rational addend) Method to add addend to this and return their sum as the result.
Trigonometrical	tan_theta_2() Method to evaluate the tangent function.
(package private) static double	TenToPower(int power)
(package private) void	timesTenToPower(int power)
(package private) Approximation	toApproximation() Method to convert this Rational into the appropriate Approximation.
Integral	toIntegral() Method to present a Rational as an Integral number.
java.lang.String	toString() This is the default toString method for all BaseNumbers.
(package private) java.lang.String	toString(double tolerance)
void	updateEstimate() MUTATING method to update the current estimate.
static Rational	valueOf(BaseNumber number) Factory method to create a Rational from a BaseNumber or, if number is Rational, then to make a copy.
(package private) static Rational	valueOf(java.math.BigDecimal x)
protected static Rational	valueOf(java.math.BigDecimal x, java.lang.String identifier) Factory method to create a Rational from a BigDecimal value and an identifier.
(package private) static Rational	valueOf(java.math.BigInteger integer, java.math.BigInteger fraction, int places) Factory method to create a (decimal) Rational from two (big) integers.
static Rational	valueOf(double value)
static Rational	valueOf(double value, boolean exact)
static Rational	valueOf(double value, double bound, int model) Factory method to create a Rational from a double value, given an indication of precision.
static Rational	valueOf(double value, double bound, int model, java.lang.String identifier) Factory method to create a Rational from a double value, given an indication of precision.
static Rational	valueOf(double value, int precision, java.lang.String identifier) Factory method to create a Rational from a double value, given an indication of precision.
static Rational	valueOf(double value, java.lang.String identifier)
static Rational	valueOf(float value)
static Rational	valueOf(float value, java.lang.String identifier)
static Rational	valueOf(Presentation presentation) Convert Presentation presentation into a Rational.
static Rational	valueOf(java.lang.String string) Translates the String representation of a FuzzInt in radix 10 to a FuzzInt.
static Rational	valueOf(java.lang.String string, java.lang.String id) Translates the String representation of a FuzzInt in radix 10 to a FuzzInt.
(package private) static Rational	valueOfExponent(int exponent) Factory method to create a Rational which is equal to 10^exponent.
(package private) static Rational	valueOfExponent(int exponent, int radix) Factory method to create a Rational which is equal to radix^exponent.
(package private) static Rational	valueOfExponent(java.lang.String exponentStr, int radix) Factory method to create a Rational which is equal to the multiplier represented by an exponent string.
(package private) static double	valueOfSquare(double x)

Methods inherited from class com.rubecula.jquantity.MutableNumber

factored, forcePositive, getIdentifier, isLong, product, setIdentifier, setIdentifierPost, setIdentifierPre, sum, test

Methods inherited from class com.rubecula.jquantity.BaseNumber

abs, audit, audit, bestModel, BestModel, Characteristic, compareTo, difference, impartFuzziness, isEqual, isUncertain, isZero, present, test, test, valueOfLog10, Wrap

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

$1

public static final Rational $1

$1 is the Rational representation of the exact value 1.

$0

public static final Rational $0

$0 is the Rational representation of the exact value 0.

$10

public static final Rational $10

$10 is the Rational representation of the exact value 10.

$2

public static final Rational $2

$2 is the Rational representation of the exact value 2.

$1_2

public static final Rational $1_2

$1_2 is the Rational representation of the exact value 1/2.

$Infinity

public static final Rational $Infinity

$Infinity is the Rational representation of the (exact) value of infinity, i.e. 1/0.

$E

public static final Rational $E

Value of E as a Rational. Note that if you want an exact value, then use Value.$E

$Pi

public static final Rational $Pi

Value of Pi as a Rational. Note that if you want an exact value, then use Value.PI

_Numerator

protected BaseNumber _Numerator

_Numerator is the numerator of the rational quantity defined by this. In practice, the numerator is always an Integral number, by virtue of the available constructors and mutators.

_Denominator

protected BaseNumber _Denominator

_Denominator is the denominator of the rational quantity defined by this. In practice, the denominator is always an Integral number, by virtue of the available constructors and mutators.

_Estimate

protected double _Estimate

_Estimate is the best estimate of the value (for debugging purposes)

$3

static final Rational $3

$6

static final Rational $6

$12

static final Rational $12

$NaN

static final Rational $NaN

$_2Pi

static final Rational $_2Pi

$_Pi_2

static final Rational $_Pi_2

$_Pi_4

static final Rational $_Pi_4

$_Pi_12

static final Rational $_Pi_12

$_Degree2Radian

static final Rational $_Degree2Radian

$S_Rt2

static final java.lang.String $S_Rt2

1.414213562373095048801688724209698078569671875377

See Also:

Constant Field Values

$S_Rt3

static final java.lang.String $S_Rt3

1.732050807568877293527446341505872366942805253810

See Also:

Constant Field Values

$S_Rt5

static final java.lang.String $S_Rt5

2.2360679774997896964091736687312762354406183596

See Also:

Constant Field Values

$Rt2

static final Rational $Rt2

InitialValueOf($S_Rt2).

$Rt3

static final Rational $Rt3

InitialValueOf($S_Rt3).

$Rt5

static final Rational $Rt5

InitialValueOf($S_Rt5).

$_Tan15Deg

static final Rational $_Tan15Deg

2 - $Rt3.

$_Tan30Deg

static final Rational $_Tan30Deg

1/$Rt3.

$MaxInt

static final java.math.BigInteger $MaxInt

Integer.MAX_VALUE.

$_c

static final Rational $_c

By definition, the velocity of light: 299792458.

$_degR

static final Rational $_degR

Degrees Rankine/Kelvin conversion: 5/9.

$_degF

static final Rational $_degF

Degrees Fahrenheit/Celsius offset: 32.

Constructor Detail

Rational

public Rational()

Empty constructor to make an undefined Rational object. The purpose of this is for an instance to be created on which to call the class method Parse(Presentation).

Rational

public Rational(java.lang.String string)
         throws PresentationException

Secondary constructor to create a Rational from a String.

Parameters:

string - the String from which to create a Rationa.

Throws:

PresentationException - if the string cannot be parsed as a Rational object.

Rational

public Rational(Integral numerator,
                Integral denominator,
                java.lang.String identifier)

Constructs an identified Rational representing the ratio of numerator divided by denominator.

Parameters:

numerator - the numerator (top) of the ratio.

denominator - the denominator (bottom) of the ratio.

identifier - the identifier to be used to identify this object.

Rational

public Rational(Integral numerator,
                Integral denominator)

Constructs a non-explicitly identified, normalized Rational representing the ratio of numerator divided by denominator.

Parameters:

numerator - Integral which is the numerator (top) of the ratio

denominator - Integral which is the denominator (bottom) of the ratio

Rational

public Rational(Integral numerator,
                java.lang.String identifier)

Constructs an identified Rational representing the ratio of numerator divided by denominator, with optional normalization.

Parameters:

numerator - the numerator (top) of the ratio

identifier - the identifier to be used to identify this object.

Rational

public Rational(Integral value)

Constructs a non-explicitly identified Rational representing the ratio of value divided by unity.

Parameters:

value - the numerator (top) of the ratio.

Rational

protected Rational(Integral numerator,
                   Integral denominator,
                   boolean normalize,
                   java.lang.String identifier)

Constructs an identified Rational representing the ratio of numerator divided by denominator, with optional normalization. This is protected because non-extenders should not be able to determine if the number be normalized.

Parameters:

numerator - the numerator (top) of the ratio, which must be an instance of either Manifest or WholeNumber.

denominator - the denominator (bottom) of the ratio, which must be an instance of either Manifest or WholeNumber.

normalize - normally true (only set to false if you really know what you're doing).

identifier - the identifier to be used to identify this object (or null).

Throws:

RationalException - if either numerator or denominator is not an instance of either Manifest or WholeNumber.

Rational

protected Rational(Integral numerator,
                   Integral denominator,
                   boolean normalize)

Constructs a non-explicitly identified Rational representing the ratio of numerator divided by denominator, with optional normalization.

Parameters:

numerator - the numerator (top) of the ratio.

denominator - the denominator (bottom) of the ratio.

normalize - normally true (only set to false if you really know what you're doing)

Method Detail

Parse

public static Rational Parse(NumberPresentation presentation,
                             java.lang.String identifier)
                      throws PresentationException

Translates the ValuePresentation representation of a FuzzInt in the specified radix into a FuzzInt. The String representation consists of an optional minus sign followed by a sequence of one or more digits in the specified radix. The character-to-digit mapping is provided by Character.digit. Up to the asterisk, yhe String may not contain any extraneous characters (whitespace, for example).

Parameters:

presentation - ValuePresentation representation of WholeNumber followed by fuzzy information.

identifier - A string with which to identify this Rational.

Returns:

Rational : a new object widened from the decimal string x.

Throws:

java.lang.NumberFormatException - val is not a valid representation of a WholeNumber in the specified radix, or radix is outside the range from Character.MIN_RADIX (2) to Character.MAX_RADIX (36), inclusive.

PresentationException - if the presentation cannot be parsed as a Rational object.

See Also:

Character.digit(char, int)

valueOf

public static Rational valueOf(BaseNumber number)

Factory method to create a Rational from a BaseNumber or, if number is Rational, then to make a copy.

Parameters:

number - an integer (either WholeNumber or Manifest) for which we require the (widened) Rational.

Returns:

the Rational, widened from number.

valueOf

public static Rational valueOf(java.lang.String string,
                               java.lang.String id)
                        throws PresentationException

Translates the String representation of a FuzzInt in radix 10 to a FuzzInt. The String representation consists of an optional minus sign followed by a sequence of one or more digits in the specified radix. The character-to-digit mapping is provided by Character.digit. Up to the asterisk, yhe String may not contain any extraneous characters (whitespace, for example).

Parameters:

string - String representation of WholeNumber followed by fuzzy information.

id - Identifier for new Rational.

Returns:

Rational : a new object widened from the decimal string x.

Throws:

java.lang.NumberFormatException - val is not a valid representation of a WholeNumber in the specified radix, or radix is outside the range from Character.MIN_RADIX (2) to Character.MAX_RADIX (36), inclusive.

PresentationException - if the string cannot be parsed as a Rational object.

See Also:

Character.digit(char, int)

valueOf

public static Rational valueOf(java.lang.String string)
                        throws PresentationException

Translates the String representation of a FuzzInt in radix 10 to a FuzzInt. The String representation consists of an optional minus sign followed by a sequence of one or more digits in the specified radix. The character-to-digit mapping is provided by Character.digit. Up to the asterisk, yhe String may not contain any extraneous characters (whitespace, for example).

Parameters:

string - String representation of WholeNumber followed by fuzzy information.

Returns:

Rational : a new object widened from the decimal string x.

Throws:

java.lang.NumberFormatException - val is not a valid representation of a WholeNumber in the specified radix, or radix is outside the range from Character.MIN_RADIX (2) to Character.MAX_RADIX (36), inclusive.

PresentationException - if the string cannot be parsed as a Rational object.

See Also:

Character.digit(char, int)

makePresentableInstance

public Presentable makePresentableInstance(Presentation presentation)
                                    throws PresentationException

Instance method to convert a Presentation into a Presentable. Ideally, this would be a class method, but such a method cannot be defined in an interface. Nor can it be defined in an abstract class with the intention of overriding it in a subclass. Polymorphism just doesn't work that way.
Therefore, the present value (as in fields) of the instance is essentially ignored - only the methods are important.

Specified by:

makePresentableInstance in interface Presentable

Parameters:

presentation - of a number to be converted into a Presentable number.

Returns:

a number in the form of a Presentable.

Throws:

PresentationException - if presentation cannot be parsed appropriately.

Parse

public static Presentable Parse(Presentation presentation)
                         throws PresentationException

Create a FuzzInt from a Presentation and return it as a Presentable.

Parameters:

presentation - A presentation which should be parsed to form a Presentable.

Returns:

A FuzzInt which corresponds to the x.

Throws:

PresentationException - if the presentation cannot be parsed as a Presentable object.

clone

public java.lang.Object clone()

Creates and returns a copy of this object.

Overrides:

clone in class MutableNumber

Returns:

a clone of this instance.

Throws:

RationalException - : Rational not Cloneable (should be impossible)

See Also:

Cloneable

getBoundAbs

public double getBoundAbs()

Method to get the absolute bound of non-fuzzy value.

Overrides:

getBoundAbs in class BaseNumber

Returns:

the absolute bound of this.

getBound

public double getBound()

Method to get the relative bound of this Rational.

Specified by:

getBound in interface Fuzzy

Overrides:

getBound in class BaseNumber

Returns:

rel. bound of numerator less rel. bound of denominator.

getModel

public int getModel()

Method to get the error distribution model of this non-fuzzy object.

Specified by:

getModel in interface Fuzzy

Overrides:

getModel in class BaseNumber

Returns:

Fuzzy.$DistNone int: non-fuzzy distribution.

isExact

public boolean isExact()

Method to determine if the quantity represented is non-fuzzy;

Specified by:

isExact in interface Fuzzy

Overrides:

isExact in class BaseNumber

Returns:

true boolean: always

intValue

public int intValue()

Method to yield the equivalent integer value for this object. Objects which are infinite or non=integral throw exceptions.

Specified by:

intValue in class java.lang.Number

Returns:

int : the integer value of this.

longValue

public long longValue()

Method to yield the equivalent integer value for this object. Objects which are infinite or non-integral throw exceptions.

Specified by:

longValue in class java.lang.Number

Returns:

int : the integer value of this.

floatValue

public float floatValue()

Returns the value of the specified number as a float. This may involve rounding.

Specified by:

floatValue in class java.lang.Number

Returns:

the numeric value represented by this object after conversion to type float.

doubleValue

public double doubleValue()

Returns the value of the specified number as a double. This may involve rounding.

Specified by:

doubleValue in class java.lang.Number

Returns:

the numeric value represented by this object after conversion to type double.

signum

public int signum()

Method to find the sign of the magnitude of this arithmetical object.

Specified by:

signum in interface Arithmetical

Returns:

0 if value is 0; 1 if value is positive; -1 if value is negative.

isInteger

public boolean isInteger()

Method determines if it is safe and appropriate to convert this arithmetical object into BigInteger.

Specified by:

isInteger in interface Arithmetical

Returns:

true if isExact() and denominator is equal to 1.

isUnity

public boolean isUnity()

Method to determine if this arithmetical object has the exact value of 1.

Specified by:

isUnity in interface Arithmetical

Returns:

true if value is 1 and isExact().

isInfinite

public boolean isInfinite()

Method to determine if an arithmetical object is infinite.

Specified by:

isInfinite in interface Arithmetical

Returns:

true if object is infinite in value.

raiseToPower

public void raiseToPower(int power)

MUTATING Instance method to raise this to power power.

Specified by:

raiseToPower in interface Arithmutable

Parameters:

power - int the number of times this should be multiplied by itself.

scale

public void scale(long factor)

MUTATING Instance method to multiply this by a scale factor. Note that under this operation, the scaling (multiplication) is always directly on the value in this regardless of type. So for example, if this is an instance of Value of type Log, then the effect of a scale by rwo will be to square the effective value.

Specified by:

scale in interface Arithmutable

Parameters:

factor - the scale factor.

negate

public void negate()

MUTATING Instance method to negate this

Specified by:

negate in interface Arithmutable

add

public void add(BaseNumber that)

MUTATING Instance method to add another BaseNumber into this object.

Specified by:

add in interface Arithmutable

Parameters:

that - the addend.

multiply

public void multiply(BaseNumber that)
              throws InvalidOperandException

MUTATING Instance method to multiply another Arithmetical into this object.

Specified by:

multiply in interface Arithmutable

Parameters:

that - Arithmetical : the multiplicand.

Throws:

InvalidOperandException - if that is not compatible with the multiply operation.

scale

public void scale(double factor)

MUTATING Instance method to multiply this by a (double) scale factor

Parameters:

factor - double the scale factor

invert

public void invert()

MUTATING Instance method to invert this (i.e. replace this by its reciprocal)

divide

public void divide(BaseNumber that)
            throws InvalidOperandException

MUTATING method to replace this by the sum of this and that

Parameters:

that - the value to be divided into this

Throws:

InvalidOperandException - if that is not compatible with the multiply operation.

inverse

public Divisible inverse()

Method to yield the reciprocal of this and return it as the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

inverse in interface Divisible

Returns:

the reciprocal of this.

quotient

public Divisible quotient(BaseNumber divisor)
                   throws InvalidOperandException

Method to divide this by multiplicand and return the quotient as the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

quotient in interface Divisible

Parameters:

divisor - the number to multiply by this.

Returns:

the quotient of this divided by divisor.

Throws:

InvalidOperandException - if that is not compatible with the multiply operation.

exp

public Trigonometrical exp()

Method to evaluate the exponential function. This method is the inverse of @{link #log()}.

Specified by:

exp in interface Trigonometrical

Returns:

e(this) in the form of a Rational.

log

public Trigonometrical log()

Method to evaluate the natural log function. This method is the inverse of @{link #exp()}.

Specified by:

log in interface Trigonometrical

Returns:

log(this) in the form of a Rational or an Approximation.

arctanX2

public Trigonometrical arctanX2()

Method to evaluate the arctangent function. This method is the inverse of @{link #tan_theta_2()}.

Specified by:

arctanX2 in interface Trigonometrical

Returns:

2 * atan(this) in the form of a Rational.

tan_theta_2

public Trigonometrical tan_theta_2()

Method to evaluate the tangent function. This method is the inverse of @{link #arctanX2()}.

Specified by:

tan_theta_2 in interface Trigonometrical

Returns:

tan(this/2) in the form of a Rational.

setBoundAbs

protected void setBoundAbs(double bound)

Method to set the absolute bound of fuzzy value.

Parameters:

bound - the absolute bound

setBound

public void setBound(double bound)

Method to set the relative bound of fuzzy value.

Specified by:

setBound in interface FuzzyMutable

Parameters:

bound - the relative bound

setModel

public void setModel(int model)

Method to set the error distribution model.

Specified by:

setModel in interface FuzzyMutable

Parameters:

model - the distribution model: $DistNone, $DistUniform or $DistGaussian

updateEstimate

public void updateEstimate()

MUTATING method to update the current estimate.

Specified by:

updateEstimate in interface Estimable

getEstimate

public double getEstimate()

Method to get the current estimate of an arithmetical value.

Specified by:

getEstimate in interface Estimable

Returns:

double: the current estimate.

toIntegral

public Integral toIntegral()

Method to present a Rational as an Integral number. If this is already of class Integral then just return this, else return the value of the superclass method.

Overrides:

toIntegral in class MutableNumber

Returns:

an instance of Integral with value equivalent to this.

minusRational

final Rational minusRational()

Method to yield a copy of this but with the sign changed.

Returns:

negative version of this.

sumRational

final Rational sumRational(Rational addend)

Method to add addend to this and return their sum as the result.

Parameters:

addend - the number to add to this.

Returns:

the sum of this and addend.

differenceRational

final Rational differenceRational(Rational subtrahend)

Method to yield the difference of this less a BaseNumber (subtrahend).

Parameters:

subtrahend - the number to subtract from this.

Returns:

the difference of this less subtrahend.

productRational

final Rational productRational(Rational multiplicand)

Method to multiply multiplicand to this and return their product as the result.

Parameters:

multiplicand - the number to add to this.

Returns:

the product of this and multiplicand.

quotientRational

final Rational quotientRational(Rational that)

inverseRational

final Rational inverseRational()

valueOf

protected static Rational valueOf(java.math.BigDecimal x,
                                  java.lang.String identifier)

Factory method to create a Rational from a BigDecimal value and an identifier.

Parameters:

x - a BigDecimal number which is to be widened into a Rationa.

identifier - the identifier for the new instance.

Returns:

a new instance of Rational with same value as x and with bounds determined from the scale of x and uniform error distribution.

getDenominator

protected final BaseNumber getDenominator()

Method to access the denominator of this Rational object.

Returns:

the value of field _Denominator.

getNumerator

protected final BaseNumber getNumerator()

Method to access the numerator of this Rational object.

Returns:

the value of field _Numerator.

getDenominatorAsIntegral

protected final Integral getDenominatorAsIntegral()

Method to access the denominator of this Rational object.

Returns:

the value of field _Denominator cast as an Integral.

getNumeratorAsIntegral

protected final Integral getNumeratorAsIntegral()

Method to access the numerator of this Rational object.

Returns:

the value of field _Numerator cast as an Integral.

minus

protected BaseNumber minus()

Method to yield a copy of this but with the sign changed.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

minus in class BaseNumber

Returns:

negative version of this.

scaled

protected BaseNumber scaled(long multiplicand)

Method to multiply multiplicand by this and return their product as the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

scaled in class BaseNumber

Parameters:

multiplicand - the number to multiply this by.

Returns:

the product of this and multiplicand.

scaled

public Divisible scaled(double multiplicand)

Method to multiply multiplicand by this and return their product as the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

scaled in interface Divisible

Parameters:

multiplicand - the number to multiply this by.

Returns:

the product of this and multiplicand.

pow

protected BaseNumber pow(int power)

Method to raise this to the power power return the result.
NOTE: it is a requirement of this method that the class of the result is the same as the class of this so that the result can be safely cast to the original class.

Specified by:

pow in class BaseNumber

Parameters:

power - the exponent for this.

Returns:

the value of this rraised to the power power.

factor

protected void factor(Integral divisor)

MUTATING METHOD: Replaces value with (this / divisor).
This method allows for division by a non-Divisible divisor. Since a Rational object can represent all rational numbers, no exception will be thrown if the quotient cannot be expressed as a pure integer.

Specified by:

factor in class MutableNumber

Parameters:

divisor - value by which this WholeNumber is to be divided.

See Also:

BaseNumber.factor(Integral)

valueOfExponent

static Rational valueOfExponent(int exponent,
                                int radix)

Factory method to create a Rational which is equal to radix^exponent.

Parameters:

exponent - the power to which radix is to be raised.

radix - the base of the number system.

Returns:

radix^exponent.

valueOfExponent

static Rational valueOfExponent(int exponent)

Factory method to create a Rational which is equal to 10^exponent.

Parameters:

exponent - the power to which radix is to be raised.

Returns:

10^exponent.

valueOfExponent

static Rational valueOfExponent(java.lang.String exponentStr,
                                int radix)

Factory method to create a Rational which is equal to the multiplier represented by an exponent string.

Parameters:

exponentStr - the power to which radix is to be raised, as a string.

radix - the base of the number system in which exponentStr is to be interpreted and also the number to be raised by the appropriate power.

Returns:

exponentStr as a multiplier.

valueOf

static Rational valueOf(java.math.BigDecimal x)

valueOf

public static Rational valueOf(double value,
                               int precision,
                               java.lang.String identifier)

Factory method to create a Rational from a double value, given an indication of precision.

Parameters:

value - double: the value to convert to Rational.

precision - int: the number of significant figures (approx.).

identifier - String: the identifier to be used to identify this object (or null).

Returns:

Rational: a value whose doubleValue() should be very close to value.

valueOf

public static Rational valueOf(double value,
                               double bound,
                               int model,
                               java.lang.String identifier)

Factory method to create a Rational from a double value, given an indication of precision.

Parameters:

value - the value to convert to Rational.

bound - an explicit value for the absolute error bound.

model - the error bound model to be used.

identifier - String: the identifier to be used to identify this object (or null).

Returns:

a value whose doubleValue() should be very close to value.

valueOf

public static Rational valueOf(double value,
                               double bound,
                               int model)

Factory method to create a Rational from a double value, given an indication of precision.

Parameters:

value - the value to convert to Rational.

bound - an explicit value for the error bound.

model - the error bound model to be used.

Returns:

a value whose doubleValue() should be very close to value.

valueOf

public static Rational valueOf(double value,
                               java.lang.String identifier)

valueOf

public static Rational valueOf(double value,
                               boolean exact)

valueOf

public static Rational valueOf(double value)

valueOf

public static Rational valueOf(float value,
                               java.lang.String identifier)

valueOf

public static Rational valueOf(float value)

valueOf

static Rational valueOf(java.math.BigInteger integer,
                        java.math.BigInteger fraction,
                        int places)

Factory method to create a (decimal) Rational from two (big) integers.

Parameters:

integer - BigInteger : the integer part.

fraction - BigInteger : the fractional part.

places - int : the number of decimal places for fractional part.

Returns:

Rational : integer + fraction/10**places.

multiplyTopAndBottom

protected void multiplyTopAndBottom(BaseNumber factor)

MUTATING method to multiply the top and bottom of a rational equally. Clearly this does not change the effective value of the Rational, but the individual numerator and denominator values do change.

Parameters:

factor - the number by which top and bottom will be multiplied.

addTops

protected void addTops(Rational other)

subtract

public void subtract(Rational that)

MUTATING method to replace this by the difference of this and that

Parameters:

that - Rational the value to be subtracted from this

absRational

Rational absRational()

audit

public java.lang.String audit(java.lang.String label)

Method to return a detailed string from an arithmetical object for debugging purposes.

Specified by:

audit in interface Auditable

Parameters:

label - String: the label to associate with the data

Returns:

the detailed string.

half

public Rational half()

modulo

Rational modulo(long x)

fold

Rational fold(Rational range)

Method to force this into a specific range. This can therefore be in radians, angles, right-angles, whatever.

Parameters:

range - defines the range (-limit < magnitude <= +limit).

Returns:

a copy of this, incremented appropriately so that magnitude is in range.

getTop

long getTop()

getBottom

final long getBottom()

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

isNaN

boolean isNaN()

normalizeToInt

Rational normalizeToInt(double tolerance)
                  throws com.rubecula.jquantity.Rational.RationalException

com.rubecula.jquantity.Rational.RationalException

normalizeToBigDecimal

Rational normalizeToBigDecimal(double tolerance)
                         throws com.rubecula.jquantity.Rational.RationalException

Normalize this such that the denominator is a power of ten AND the value of the result differs from the value of this by not more than the tolerance.

Parameters:

tolerance - the acceptable discrepancy in values (may be zero).

Returns:

the "equivalent" Rational, or this.

Throws:

RationalException - An "equivalent" instance cannot be created.

com.rubecula.jquantity.Rational.RationalException

normalize

public void normalize()

MUTATING instance method to remove any common factors from top and bottom. Also ensures that denominator is not negative. Furthermore, it updates the value of the estimate. Repeated applications of this method on an object should have no effect. The effective value of this object before and after normalization must be the same.

Specified by:

normalize in interface Normalizable

places

int places()
     throws com.rubecula.jquantity.Rational.RationalException

com.rubecula.jquantity.Rational.RationalException

root

Rational root(int p)
        throws com.rubecula.jquantity.Rational.RationalException

method root: to yield an exact (integer) Rational for the root of a positive integral Rational. Throws an exception if this is not a positive integer or cannot otherwise yield an exact result.

Parameters:

p - the inverse of the power to which this will be raised.

Returns:

the pth root of this.

Throws:

RationalException

com.rubecula.jquantity.Rational.RationalException

multFloat

float multFloat(float factor)

expFloat

float expFloat(float factor)
         throws com.rubecula.jquantity.Rational.RationalException

com.rubecula.jquantity.Rational.RationalException

squareRational

Rational squareRational()

toString

public java.lang.String toString()

Description copied from class: BaseNumber

This is the default toString method for all BaseNumbers. Specific classes will override as appropriate.

Overrides:

toString in class BaseNumber

Returns:

a String representing this BaseNumber

toString

final java.lang.String toString(double tolerance)

present

public Presentation present(AttrMap attributes)
                     throws PresentationException

Convert this Presentable object into a Presentation, according to the set of attributes provided.

Specified by:

present in interface Presentable

Parameters:

attributes - a map of the required attributes for the presentation. Supported attributes include:

Normalize

String On / Off*;

Tolerance

Double/String value (def: 0);

NYI: Places

Integer/String the number of decimal places to show

NYI: Round

String On * / Off

NYI: Radix

Integer/String the value of the radix

NYI: Zero

String On * / Off where to show 0.x or just .x

NYI: Decimal

String "." or ","

Returns:

an appropriate instance of Presentation.

Throws:

PresentationException - if this object cannot be presented with the given attributes.

valueOf

public static Rational valueOf(Presentation presentation)
                        throws PresentationException

Convert Presentation presentation into a Rational.

Parameters:

presentation - a Presentation.

Returns:

a new instance of Rational.

Throws:

PresentationException - if presentation presentation cannot be parsed as a Rational object.

toApproximation

Approximation toApproximation()

Method to convert this Rational into the appropriate Approximation. Note that precision will generally be lost in this operation.

Returns:

a Approximation which is exactly equivalent to this.

longValue

long longValue(double tolerance)
         throws com.rubecula.jquantity.Rational.RationalException

Method to yield the integer value of this object.

Parameters:

tolerance - The tolerance within which we don't mind losing precision as we perform this conversion.

Returns:

an integer which is equal to doubleValue(), within tolerance.

Throws:

RationalException

com.rubecula.jquantity.Rational.RationalException

timesTenToPower

void timesTenToPower(int power)

valueOfSquare

static double valueOfSquare(double x)

magnitude

final double magnitude()

TenToPower

static double TenToPower(int power)

characteristic

int characteristic()
             throws com.rubecula.jquantity.Rational.RationalException

com.rubecula.jquantity.Rational.RationalException

Characteristic

static int Characteristic(java.math.BigDecimal x)
                   throws com.rubecula.jquantity.Rational.RationalException

com.rubecula.jquantity.Rational.RationalException

GetPrecisionPlaces

static int GetPrecisionPlaces(Rational upperBound,
                              Rational lowerBound,
                              double tolerance,
                              boolean gaussian)
                       throws com.rubecula.jquantity.Rational.RationalException

com.rubecula.jquantity.Rational.RationalException

GetExtraPrecisionDigits

static int GetExtraPrecisionDigits(int places,
                                   int requiredExtrasLength,
                                   Rational value,
                                   double tolerance)
                            throws com.rubecula.jquantity.Rational.RationalException

com.rubecula.jquantity.Rational.RationalException

compareTo

protected int compareTo(Rational val,
                        boolean absolute)

Compares this Rational with the specified Rational. This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=). The suggested idiom for performing these comparisons is: (x.compareTo(y) <op> 0), where <op> is one of the six comparison operators.

Parameters:

val - Rational to which this Rational is to be compared.

absolute - Whether to take the difference (if true) or the quotient (if false) when comparing the values.

Returns:

-1, 0 or 1 as this Rational is numerically less than, equal to, or greater than val.

compareTo

public int compareTo(Rational val)

Compares this Rational with the specified Rational. This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=). The suggested idiom for performing these comparisons is: (x.compareTo(y) <op> 0), where <op> is one of the six comparison operators.

Parameters:

val - Rational to which this Rational is to be compared.

Returns:

-1, 0 or 1 as this Rational is numerically less than, equal to, or greater than val.

compareTo

public int compareTo(Integral val)

Compares this Rational with the specified Rational. This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=). The suggested idiom for performing these comparisons is: (x.compareTo(y) <op> 0), where <op> is one of the six comparison operators.

Parameters:

val - Rational to which this Rational is to be compared.

Returns:

-1, 0 or 1 as this Rational is numerically less than, equal to, or greater than val.

main

public static void main(java.lang.String[] args)

Main method for testing this class.

Parameters:

args - String[] : the command line options.