org.znerd.math
Class RealNumber

java.lang.Object
  |
  +--java.lang.Number
        |
        +--org.znerd.math.RealNumber

Direct Known Subclasses:

CompositeNumber, RationalNumber

public abstract class RealNumber

extends Number

implements Comparable, RoundingModes

An immutable real number. A number of basic numeric operations are defined, like:

negate()

Computes -this

invert()

Computes 1/this

add(RealNumber)

Computes this + n

subtract(RealNumber)

Computes this - n

multiply(RealNumber)

Computes this * n

divide(RealNumber)

Computes this / n

pow(RealNumber)

Computes thisn

Examples of real numbers are 3, -1.68, the square root of 3, 2/3, pi, 18.2^2.3 and e.

Real numbers can be cast to native Java numbers with these conversion methods:

longValue()

Converts this number to a long. Use fitsLong() to make sure the conversion will succeed

intValue()

Converts this number to an int. Use fitsInt() to make sure the conversion will succeed

shortValue()

Converts this number to a short. Use fitsShort() to make sure the conversion will succeed

byteValue()

Converts this number to a byte. Use fitsByte() to make sure the conversion will succeed

doubleValue()

Converts this number to a double. Use fitsDouble() to make sure the conversion will succeed

floatValue()

Converts this number to a float. Use fitsFloat() to make sure the conversion will succeed

Use the NumberCentral to obtain RealNumber instances. For instance:

RealNumber n = NumberCentral.valueOf(0.399);

PENDING: The names of the following methods may be changed in the future to reflect the expected change in the syntax of the Java language syntax to include operator overloading based on method names (see the section Operator Overloading in The Evolution of Numerical Computing in Java by James Gosling.)

• negate() --> uminus
• add(RealNumber) --> plus
• subtract(RealNumber) --> minus
• multiply(RealNumber) --> times

Concrete subclasses should provide implementations for the following methods:

toBigDecimal(int,int)

Converts the value of this number to a BigDecimal with the specified precision, using the specified rounding mode.

trunc()

Truncates the value of this number to an IntegerNumber.

Version:

$Revision: 1.16 $ $Date: 2002/08/19 18:05:40 $

Author:

Ernst de Haan (znerd@FreeBSD.org)

See Also:

NumberCentral, Serialized Form

Field Summary

static int

MAXIMUM_RADIX The maximum value for a radix.

Fields inherited from interface org.znerd.math.RoundingModes

ROUND_CEILING, ROUND_DOWN, ROUND_FLOOR, ROUND_UP

Constructor Summary

protected

RealNumber(int sign, String asString) Constructs a new RealNumber object.

Method Summary

RealNumber	abs() Computes |this|.
RealNumber	add(RealNumber n) Computes this + n, where n is a real number.
byte	byteValue() Returns the value of this number as a byte.
int	compareTo(Object o) Compares this object with the specified object.
int	compareTo(RealNumber n) Compares this number with the specified number.
protected int	compareToImpl(RealNumber n) Compares this number with the specified number, second level.
RealNumber	divide(RealNumber n) Computes this/n, where n is a real number.
double	doubleValue() Returns the value of this number as a double.
boolean	equals(Object o)
boolean	fitsByte() Determines if the truncated value of this number fits in a byte.
boolean	fitsDouble() Determines if the rounded value of this number fits in a double.
boolean	fitsFloat() Determines if the rounded value of this number fits in a float.
boolean	fitsInt() Determines if the truncated value of this number fits in an int.
boolean	fitsLong() Determines if the truncated value of this number fits in a long.
boolean	fitsShort() Determines if the truncated value of this number fits in a short.
float	floatValue() Returns the value of this number as a float.
int	getSign() Determines the sign of this number.
int	intValue() Returns the value of this number as an int.
RealNumber	invert() Computes 1/this.
long	longValue() Returns the value of this number as a long.
RealNumber	multiply(RealNumber n) Computes this * n, where n is a real number.
RealNumber	negate() Computes -this.
RealNumber	pow(RealNumber n) Computes thisn, where n is a real number.
DigitSet	round(int radix, int precision, RoundingMode roundingMode) Rounds to the specified radix, using the specified precision and rounding mode.
short	shortValue() Returns the value of this number as a short.
RealNumber	subtract(RealNumber n) Computes this - n, where n is a real number.
BigDecimal	toBigDecimal(int precision) Converts the value of this number to a BigDecimal with the specified precision.
abstract BigDecimal	toBigDecimal(int precision, int roundingMode) Converts the value of this number to a BigDecimal with the specified precision and rounding mode.
BigInteger	toBigInteger() Converts the value of this number to a BigInteger.
String	toString()
IntegerNumber	trunc() Rounds to an integer number towards 0.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MAXIMUM_RADIX

public static final int MAXIMUM_RADIX

The maximum value for a radix. The value of this field is 255.

Constructor Detail

RealNumber

protected RealNumber(int sign,
                     String asString)
              throws IllegalArgumentException

Constructs a new RealNumber object.

The sign of the value needs to be specified. Any negative value is interpreted as meaning that the value of this number is negative. Any positive value is interpreted as meaning that the value of this number is positive.

Parameters:

sign - the sign of this number; -1 if this number is smaller than zero, 0 is this number is 0 or 1 if this number is greater than zero.

asString - textual presentation of this number, not null.

Throws:

IllegalArgumentException - if asString == null.

Method Detail

toString

public final String toString()

Overrides:

toString in class Object

equals

public final boolean equals(Object o)

Overrides:

equals in class Object

getSign

public final int getSign()

Determines the sign of this number. This method returns -1, 0, or 1 as this number is negative, zero, or positive.

Returns:

the sign of this number, either -1, 0 or 1.

compareTo

public final int compareTo(Object o)
                    throws NullPointerException,
                           ClassCastException

Compares this object with the specified object.

This method calls compareTo(RealNumber).

Specified by:

compareTo in interface Comparable

Parameters:

o - the object to compare to, not null.

Returns:

-1 if this object is considered less than o, 0 if this object is considered equal n, 1 if this object is greater than n.

Throws:

NullPointerException - if n == null.

ClassCastException - if (n instanceof RealNumber) == false.

compareTo

public final int compareTo(RealNumber n)
                    throws NullPointerException

Compares this number with the specified number.

This method attempts to compare this number with the specified number based on the sign. If the signs are equal, compareToImpl(RealNumber) is called. If that method throws a CanNotCompareException, then it is attempted to return the negated result of n.compareToImpl(RealNumber). If that method throws an exception as well, then it is thrown up to the caller of this method.

Parameters:

n - the number to compare to, not null.

Returns:

-1 if this < n, 0 if this == n, 1 if this > n.

Throws:

NullPointerException - if n == null.

compareToImpl

protected int compareToImpl(RealNumber n)
                     throws CanNotCompareException

Compares this number with the specified number, second level.

The implementation of this method in class RealNumber throws a CanNotCompareException. Concrete subclasses are encouraged to improve this behaviour by overriding this method.

Note that this method does not check if n == null. This is already done in compareTo(RealNumber).

Parameters:

n - the number to compare to, guaranteed to be not null.

Returns:

-1 if this < n, 0 if this == n, 1 if this > n.

Throws:

CanNotCompareException - if the comparison failed.

round

public DigitSet round(int radix,
                      int precision,
                      RoundingMode roundingMode)
               throws IllegalArgumentException,
                      UnsupportedOperationException

Rounds to the specified radix, using the specified precision and rounding mode.

If rounding is not supported by this class, then an UnsupportedOperationException is thrown. The implementation of this method in class RealNumber throws such an exception.

Parameters:

radix - the radix, always >= 2 and <= MAXIMUM_RADIX.

precision - the precision, always >= 1.

roundingMode - the rounding mode, never null.

Returns:

the rounded number, never null.

Throws:

IllegalArgumentException - if radix < 2 || radix > MAXIMUM_RADIX || precision < 1 || roundingMode == null.

UnsupportedOperationException - if rounding is not supported by this class.

abs

public RealNumber abs()

Computes |this|. The returned value is always >= 0.

Returns:

the absolute of this, not null and always with a value >= 0.

negate

public RealNumber negate()

Computes -this.

Returns:

the negative of this, not null.

invert

public RealNumber invert()
                  throws ArithmeticException

Computes 1/this.

Returns:

the inverse of this, not null.

Throws:

ArithmeticException - if the value of this is zero.

add

public RealNumber add(RealNumber n)
               throws IllegalArgumentException

Computes this + n, where n is a real number.

Parameters:

n - the number to add to this, not null.

Returns:

the sum of this and n, not null.

Throws:

IllegalArgumentException - if n == null.

subtract

public RealNumber subtract(RealNumber n)
                    throws IllegalArgumentException

Computes this - n, where n is a real number.

The implementation of this method in class RealNumber calls add(RealNumber) with n.negate() as the argument.

Parameters:

n - the number to subtract from this, not null.

Returns:

this minus n, not null.

Throws:

IllegalArgumentException - if n == null.

multiply

public RealNumber multiply(RealNumber n)
                    throws IllegalArgumentException

Computes this * n, where n is a real number.

Parameters:

n - the factor, the number to multiply this by, not null.

Returns:

the product of this and n.

Throws:

IllegalArgumentException - if n == null.

divide

public RealNumber divide(RealNumber n)
                  throws IllegalArgumentException,
                         ArithmeticException

Computes this/n, where n is a real number.

The implementation of this method in class RealNumber calls multiply(RealNumber) with n.invert() as the argument.

Parameters:

n - the number to divide this by, not null.

Returns:

this divided by n, not null.

Throws:

IllegalArgumentException - if n == null.

ArithmeticException - if the value of n is zero.

pow

public RealNumber pow(RealNumber n)
               throws IllegalArgumentException

Computes thisⁿ, where n is a real number.

The implementation of this method in class RealNumber calls NumberCentral.pow(RealNumber,RealNumber).

Parameters:

n - the exponent, not null.

Returns:

this raised to the power of n.

Throws:

IllegalArgumentException - if n == null.

fitsLong

public boolean fitsLong()

Determines if the truncated value of this number fits in a long.

Returns:

true iff this value fits in a long.

fitsInt

public boolean fitsInt()

Determines if the truncated value of this number fits in an int.

Returns:

true iff this value fits in an int.

fitsShort

public boolean fitsShort()

Determines if the truncated value of this number fits in a short.

Returns:

true iff this value fits in a short.

fitsByte

public boolean fitsByte()

Determines if the truncated value of this number fits in a byte.

Returns:

true iff this value fits in a byte.

fitsDouble

public boolean fitsDouble()

Determines if the rounded value of this number fits in a double.

Returns:

true iff this value fits in a double.

fitsFloat

public boolean fitsFloat()

Determines if the rounded value of this number fits in a float.

Returns:

true iff this value fits in a float.

longValue

public long longValue()

Returns the value of this number as a long. This may involve rounding.

Overrides:

longValue in class Number

Returns:

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

intValue

public int intValue()

Returns the value of this number as an int. This may involve rounding.

Overrides:

intValue in class Number

Returns:

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

shortValue

public short shortValue()

Returns the value of this number as a short. This may involve rounding.

Overrides:

shortValue in class Number

Returns:

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

byteValue

public byte byteValue()

Returns the value of this number as a byte. This may involve rounding.

Overrides:

byteValue in class Number

Returns:

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

doubleValue

public double doubleValue()

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

Overrides:

doubleValue in class Number

Returns:

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

floatValue

public float floatValue()

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

Overrides:

floatValue in class Number

Returns:

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

toBigDecimal

public BigDecimal toBigDecimal(int precision)
                        throws IllegalArgumentException

Converts the value of this number to a BigDecimal with the specified precision. This method uses the ROUND_HALF_UP rounding mode as defined in BigDecimal.

Parameters:

precision - the number of digits behind the decimal point.

Returns:

a BigDecimal with the rounded value of this.

Throws:

IllegalArgumentException - if precision < 0.

toBigDecimal

public abstract BigDecimal toBigDecimal(int precision,
                                        int roundingMode)
                                 throws IllegalArgumentException

Converts the value of this number to a BigDecimal with the specified precision and rounding mode.

Parameters:

precision - the number of digits behind the decimal point, >= 0.

roundingMode - the rounding mode to use, one of the modes defined in class BigDecimal.

Returns:

a BigDecimal with the rounded value of this, never null.

Throws:

IllegalArgumentException - if one of the following applies:

1. precision < 0
2. roundingMode is not one of the valid rounding modes defined in class BigDecimal

toBigInteger

public BigInteger toBigInteger()

Converts the value of this number to a BigInteger. This may involve rounding.

Returns:

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

trunc

public IntegerNumber trunc()

Rounds to an integer number towards 0.

Returns:

this real number truncated to an integer, never null.