org.znerd.math
Class IntegerNumber

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

Direct Known Subclasses:

BigIntegerNumber, SmallIntegerNumber

public abstract class IntegerNumber

extends RationalNumber

An immutable integer number. The base for all integer numbers. It extends RationalNumber by offering narrowed numeric computations for integer numbers.

Some IntegerNumber numeric computations are narrowed compared to their more general RationalNumber equivalents. For instance, adding two integer numbers will result in a integer number. The computations concerned are:

add(IntegerNumber)

adding two integer numbers will result in another integer number

subtract(RationalNumber)

subtracting one rational number from another will result in an integer number

multiply(RationalNumber)

multiplying two integer numbers will result in another integer number

Concrete subclasses must at least provide implementations for the following methods:

getSign()

Determines the sign of this number

negate()

Computes -this

add(IntegerNumber)

Computes this+n, where n is an integer number

multiply(IntegerNumber)

Computes this*n, where n is an integer number

integerDivide(IntegerNumber)

Computes the integer result of a division

longValue()

Converts the value of this number to a long

doubleValue()

Converts the value of this number to a double

toByteArray()

Converts the value of this number to a set of bytes that represent the two's complement of this number

Subclasses are encouraged to override as many methods as they can in order to optimize the implementation. Those methods marked as final need no further optimization.

Version:

$Revision: 1.12 $ $Date: 2002/08/16 21:54:40 $

Author:

Ernst de Haan (znerd@FreeBSD.org)

See Also:

Serialized Form

Fields inherited from class org.znerd.math.RealNumber

MAXIMUM_RADIX

Constructor Summary

protected

IntegerNumber(int sign, String asString) Creates a new IntegerNumber with the specified sign and the specified textual representation.

Method Summary

RealNumber	abs() Computes |this|.
IntegerNumber	absInteger() Computes |this| and returns an IntegerNumber.
abstract IntegerNumber	add(IntegerNumber n) Computes this + n, where n is an integer number.
RationalNumber	add(RationalNumber n) Computes this+n, where n is a rational number.
protected int	compareTo(IntegerNumber n) Compares this number with the specified integer number, first level.
protected int	compareToImpl(IntegerNumber n) Compares this number with the specified integer number, second level.
protected int	compareToImpl(RationalNumber n) Compares this number with the specified rational number, second level.
IntegerNumber	dec() Computes this-1.
RationalNumber	divide(RationalNumber n) Computes this/n, where n is a rational number.
IntegerNumber	fac() Computes this!.
IntegerNumber	gcd(IntegerNumber n) Computes the greatest common divisor of this and n.
IntegerNumber	inc() Computes this+1.
abstract IntegerNumber	integerDivide(IntegerNumber n) Computes the integer result of this/n, where n is an integer number.
RealNumber	invert() Computes 1/this.
boolean	isRelativePrime(IntegerNumber n) Determines if this and n are relative primes.
abstract IntegerNumber	multiply(IntegerNumber n) Computes this * n, where n is an integer number.
RationalNumber	multiply(RationalNumber n) Computes this*n, where n is a rational number.
RealNumber	negate() Computes -this.
IntegerNumber	negateInteger() Computes -this and returns an IntegerNumber.
RationalNumber	pow(IntegerNumber n) Computes this**n, where n is an integer number.
IntegerNumber	remainder(IntegerNumber n) Computes the remainder of this/n, where n is an integer number.
IntegerNumber	subtract(IntegerNumber n) Computes this - n, where n is an integer number.
RationalNumber	subtract(RationalNumber n) Computes this-n, where n is a rational number.
BigDecimal	toBigDecimal() Converts the value of this number to a BigDecimal.
BigDecimal	toBigDecimal(int precision) Converts the value of this number to a BigDecimal with the specified precision.
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.
abstract byte[]	toByteArray() Returns the two's-complement representation of this integer number.
IntegerNumber	trunc() Rounds to an integer number towards 0.

Methods inherited from class org.znerd.math.RationalNumber

add, compareTo, compareToImpl, compareToImpl2, divide, doubleValue, getDenominator, getNumerator, multiply, pow, subtract

Methods inherited from class org.znerd.math.RealNumber

byteValue, compareTo, compareTo, equals, fitsByte, fitsDouble, fitsFloat, fitsInt, fitsLong, fitsShort, floatValue, getSign, intValue, longValue, round, shortValue, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

IntegerNumber

protected IntegerNumber(int sign,
                        String asString)

Creates a new IntegerNumber with the specified sign and the specified textual representation. This constructor can only be called from subclass constructors, since this class is abstract.

Parameters:

sign - the sign of this number, either -1 if this number is negative, 0 if this number is 0, or 1 is this number is positive.

asString - textual presentation of this number, not null.

Method Detail

compareToImpl

protected int compareToImpl(RationalNumber n)
                     throws CanNotCompareException

Description copied from class: RationalNumber

Compares this number with the specified rational number, second level.

This method is called from RationalNumber.compareTo(RationalNumber). The implementation of this method in class RationalNumber just throws a CanNotCompareException to indicate it does not provide an optimized algorithm for comparing this integer number with the argument integer number. Subclasses are encouraged to override this method.

Overrides:

compareToImpl in class RationalNumber

Tags copied from class: RationalNumber

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.

compareTo

protected final int compareTo(IntegerNumber n)
                       throws CanNotCompareException

Compares this number with the specified integer number, first level.

This method calls compareToImpl(IntegerNumber). If that method throws a CanNotCompareException, then it will attempt to use a fallback comparison algorithm based on toByteArray().

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.

compareToImpl

protected int compareToImpl(IntegerNumber n)
                     throws CanNotCompareException

Compares this number with the specified integer number, second level.

This method is called from compareTo(IntegerNumber). The implementation of this method in class IntegerNumber just throws a CanNotCompareException to indicate it does not provide an optimized algorithm for comparing this integer number with the argument integer number. Subclasses are encouraged to override this method.

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.

abs

public final RealNumber abs()

Description copied from class: RealNumber

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

Overrides:

abs in class RealNumber

Tags copied from class: RealNumber

Returns:

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

absInteger

public final IntegerNumber absInteger()

Computes |this| and returns an IntegerNumber. The returned value is always >= 0.

The only difference between this method and abs() is that this method is explicitly defined to return an IntegerNumber. In fact abs() calls this method.

Returns:

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

negate

public final RealNumber negate()

Description copied from class: RealNumber

Computes -this.

Overrides:

negate in class RationalNumber

Tags copied from class: RealNumber

Returns:

the negative of this, not null.

negateInteger

public IntegerNumber negateInteger()

Computes -this and returns an IntegerNumber.

The only difference between this method and negate() is that this method is explicitly defined to return an IntegerNumber. In fact negate() calls this method.

Returns:

the negative of this, not null.

invert

public RealNumber invert()
                  throws ArithmeticException

Description copied from class: RealNumber

Computes 1/this.

Overrides:

invert in class RationalNumber

Tags copied from class: RealNumber

Returns:

the inverse of this, not null.

Throws:

ArithmeticException - if the value of this is zero.

add

public RationalNumber add(RationalNumber n)
                   throws IllegalArgumentException

Description copied from class: RationalNumber

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

Overrides:

add in class RationalNumber

Tags copied from class: RationalNumber

Parameters:

n - the number to add to this.

Returns:

the sum of this and n.

Throws:

IllegalArgumentException - if n == null.

add

public abstract IntegerNumber add(IntegerNumber n)
                           throws IllegalArgumentException

Computes this + n, where n is an integer number.

Parameters:

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

Returns:

the sum of this and n, never null.

Throws:

IllegalArgumentException - if the argument is null.

subtract

public RationalNumber subtract(RationalNumber n)
                        throws IllegalArgumentException

Description copied from class: RationalNumber

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

Overrides:

subtract in class RationalNumber

Tags copied from class: RationalNumber

Parameters:

n - the number to subtract from this.

Returns:

this minus n.

Throws:

IllegalArgumentException - if n == null.

subtract

public IntegerNumber subtract(IntegerNumber n)
                       throws IllegalArgumentException

Computes this - n, where n is an integer number.

Parameters:

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

Returns:

this minus n, not null.

Throws:

IllegalArgumentException - if n == null.

multiply

public RationalNumber multiply(RationalNumber n)
                        throws IllegalArgumentException

Description copied from class: RationalNumber

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

Overrides:

multiply in class RationalNumber

Tags copied from class: RationalNumber

Parameters:

n - the number to multiply this by.

Returns:

the product of this and n.

Throws:

IllegalArgumentException - if n == null.

multiply

public abstract IntegerNumber multiply(IntegerNumber n)
                                throws IllegalArgumentException

Computes this * n, where n is an integer number.

Parameters:

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

Returns:

the product of this and n, not null.

Throws:

IllegalArgumentException - if n == null.

divide

public RationalNumber divide(RationalNumber n)
                      throws IllegalArgumentException,
                             ArithmeticException

Description copied from class: RationalNumber

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

Overrides:

divide in class RationalNumber

Tags copied from class: RationalNumber

Parameters:

n - the number to divide this by.

Returns:

this divided by n.

Throws:

IllegalArgumentException - if n == null.

ArithmeticException - if the value of n is zero.

pow

public RationalNumber pow(IntegerNumber n)
                   throws IllegalArgumentException

Description copied from class: RationalNumber

Computes this**n, where n is an integer number.

Overrides:

pow in class RationalNumber

Tags copied from class: RationalNumber

Parameters:

n - the exponent.

Returns:

this raised to the power of n.

Throws:

IllegalArgumentException - if n == null.

dec

public IntegerNumber dec()

Computes this-1.

Returns:

this decreased by 1.

inc

public IntegerNumber inc()

Computes this+1.

Returns:

this increased by 1.

fac

public IntegerNumber fac()
                  throws ArithmeticException

Computes this!. The value of this cannot be negative.

Returns:

the faculty of this, not null.

Throws:

ArithmeticException - if the value of this number is < 0.

remainder

public IntegerNumber remainder(IntegerNumber n)
                        throws ArithmeticException,
                               IllegalArgumentException

Computes the remainder of this/n, where n is an integer number.

Parameters:

n - the number to divide this by.

Returns:

the remainder.

Throws:

ArithmeticException - if the value of the argument number is zero.

IllegalArgumentException - if the argument is null.

gcd

public IntegerNumber gcd(IntegerNumber n)
                  throws IllegalArgumentException

Computes the greatest common divisor of this and n.

Parameters:

n - the other integer number.

Returns:

the greatest common divisor.

Throws:

IllegalArgumentException - if n is null.

isRelativePrime

public boolean isRelativePrime(IntegerNumber n)
                        throws IllegalArgumentException

Determines if this and n are relative primes.

Parameters:

n - the other integer number.

Returns:

true if this and n are relative primes, false otherwise.

Throws:

IllegalArgumentException - if n is null.

toBigInteger

public BigInteger toBigInteger()

Converts the value of this number to a BigInteger.

Overrides:

toBigInteger in class RealNumber

Returns:

a BigInteger with the value of this.

toBigDecimal

public BigDecimal toBigDecimal()

Converts the value of this number to a BigDecimal. A precision nor a rounding mode need to be specified for integer numbers.

Returns:

a BigDecimal with the exact value of this.

toBigDecimal

public BigDecimal toBigDecimal(int precision)
                        throws IllegalArgumentException

Converts the value of this number to a BigDecimal with the specified precision. The precision argument is ignored, because no rounding is needed.

Overrides:

toBigDecimal in class RationalNumber

Parameters:

precision - the number of digits behind the decimal point.

Returns:

a BigDecimal with the exact value of this.

Throws:

IllegalArgumentException - if precision < 0

toBigDecimal

public BigDecimal toBigDecimal(int precision,
                               int roundingMode)

Converts the value of this number to a BigDecimal with the specified precision and rounding mode. The precision and roundingMode arguments are ignored, because no rounding is needed.

Overrides:

toBigDecimal in class RationalNumber

Parameters:

precision - the number of digits behind the decimal point.

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

Returns:

a BigDecimal with the rounded value of this.

Throws:

IllegalArgumentException - if one of the following applies:

1. precision < 0
2. roundingMode does not have a valid value

trunc

public final IntegerNumber trunc()

Description copied from class: RealNumber

Rounds to an integer number towards 0.

Overrides:

trunc in class RationalNumber

Tags copied from class: RealNumber

Returns:

this real number truncated to an integer, never null.

toByteArray

public abstract byte[] toByteArray()

Returns the two's-complement representation of this integer number. The array is big-endian (i.e., the most significant byte is in the [0] position). The array contains the minimum number of bytes required to represent the number.

Returns:

a byte array containing the bits of this integer number.

integerDivide

public abstract IntegerNumber integerDivide(IntegerNumber n)
                                     throws ArithmeticException,
                                            IllegalArgumentException

Computes the integer result of this/n, where n is an integer number.

Parameters:

n - the number to divide this by.

Returns:

the integer result of this divided by n.

Throws:

ArithmeticException - if the value of the argument number is zero.

IllegalArgumentException - if the argument is null.