Class Natural

java.lang.Object
  Natural

All Implemented Interfaces:

java.lang.Comparable

public class Natural
extends java.lang.Object
implements java.lang.Comparable

A natural number is a non-negative integer. All operations behave like Java's primitive integer types. Natural provides analogues to most of Java's primitive integer operators, and most relevant methods from java.lang.Math. Additionally, Natural provides operations for modular arithmetic.

Semantics of arithmetic operations exactly mimic those of Java's integer arithmetic operators, as defined in The Java Language Specification. For example, division by zero throws an ArithmeticException, and division of a negative by a positive yields a negative (or zero) remainder.

Comparison operations perform signed integer comparisons, analogous to those performed by Java's relational and equality operators.

For the sake of brevity and clarity, pseudo-code is used throughout the descriptions of Natural methods. The pseudo-code expression (i + j) is shorthand for "a Natural whose value is that of the Natural i plus that of the Natural j." The pseudo-code expression (i == j) is shorthand for "true if and only if the Natural i represents the same value as the the Natural j." Other pseudo-code expressions are interpreted similarly.

Version:

1.5 3/20/2006 Enhanced to include a maxvalue. 3/9/05 modified equals() to not consider maxvalue. 3/12/05 removed named constants zero and one. 3/20/06 added compareTo(int) method.

Author:

John Dalbey, edited by Sean Dinsmore, Thomas Bouldin

Natural

public Natural(java.lang.String val)

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

Parameters:

val - decimal String representation of Natural.

Throws:

java.lang.NumberFormatException - val is not a valid representation of a Natural.

See Also:

Character.digit(char, int)

Natural

public Natural(int val)

Constructs a Natural with the specified int value.

Parameters:

val - int representation of Natural.

Throws:

java.lang.NumberFormatException - if val is negative

Natural

public Natural(int val,
               int max)

Constructs a Natural with the specified int value and maximum.

Parameters:

val - int representation of Natural.

max - int value that is the max this number can take.

Throws:

java.lang.NumberFormatException - if val is negative

java.lang.NumberFormatException - if max is negative

add

public Natural add(Natural val)

Returns a Natural whose value is (this + val).

Parameters:

val - value to be added to this Natural.

Returns:

this + val

increment

public void increment()

Adds one to this Natural.

subtract

public Natural subtract(Natural val)

Returns a Natural whose value is (this - val).

Parameters:

val - value to be subtracted from this Natural.

Returns:

this - val

Throws:

java.lang.ArithmeticException - if result would be negative.

decrement

public void decrement()

Subtracts one from this Natural.

Throws:

java.lang.ArithmeticException - if result would be negative.

multiply

public Natural multiply(Natural val)

Returns a Natural whose value is (this * val).

Parameters:

val - value to be multiplied by this Natural.

Returns:

this * val

square

public Natural square()

Returns a Natural whose value is (this²).

Returns:

this²

divide

public Natural divide(Natural val)

Returns a Natural whose value is (this / val).

Parameters:

val - value by which this Natural is to be divided.

Returns:

this / val

Throws:

java.lang.ArithmeticException - val==0

remainder

public Natural remainder(Natural val)

Returns a Natural whose value is (this % val).

Parameters:

val - value by which this Natural is to be divided, and the remainder computed.

Returns:

this % val

Throws:

java.lang.ArithmeticException - val==0

pow

public Natural pow(int exponent)

Returns a Natural whose value is (this^exponent). Note that exponent is an integer rather than a Natural.

Parameters:

exponent - exponent to which this Natural is to be raised.

Returns:

this^exponent

Throws:

java.lang.ArithmeticException - exponent is negative. (This would cause the operation to yield a non-integer value.)

compareTo

public int compareTo(Natural val)

Compares this Natural with the specified Natural. 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 - Natural to which this Natural is to be compared.

Returns:

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

compareTo

public int compareTo(int val)

Compares this Natural with the specified integer.

Parameters:

val - int to which this Natural is to be compared.

Returns:

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

Precondition:

val >= 0

compareTo

public int compareTo(java.lang.Object x)

Same as compareTo() above, just taking an object as parameter.

Specified by:

compareTo in interface java.lang.Comparable

equals

public boolean equals(java.lang.Object x)

Compares this Natural with the specified Object for equality.

Overrides:

equals in class java.lang.Object

Parameters:

x - Object to which this Natural is to be compared.

Returns:

true if and only if the specified Object is a Natural whose value is numerically equal to this Natural.

min

public Natural min(Natural val)

Returns the minimum of this Natural and val.

Parameters:

val - value with with the minimum is to be computed.

Returns:

the Natural whose value is the lesser of this Natural and val. If they are equal, either may be returned.

max

public Natural max(Natural val)

Returns the maximum of this Natural and val.

Parameters:

val - value with with the maximum is to be computed.

Returns:

the Natural whose value is the greater of this and val. If they are equal, either may be returned.

toString

public java.lang.String toString()

Returns the decimal String representation of this Natural. The digit-to-character mapping provided by Character.forDigit is used, and a minus sign is prepended if appropriate. (This representation is compatible with the (String) constructor, and allows for String concatenation with Java's + operator.)

Overrides:

toString in class java.lang.Object

Returns:

decimal String representation of this Natural.

See Also:

Character.forDigit(int, int)

intValue

public int intValue()

Converts this Natural to an int.

Returns:

this Natural converted to an int.

longValue

public long longValue()

Converts this Natural to a long.

Returns:

this Natural converted to a long.

floatValue

public float floatValue()

Converts this Natural to a float.

Returns:

this Natural converted to a float.

doubleValue

public double doubleValue()

Converts this Natural to a double.

Returns:

this Natural converted to a double.

getMax

public int getMax()

Returns the max value of the natural number (-1 means no max)

Returns:

-1

if there is no max, otherwise the max

main

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

A local test driver