CInteger (josef 3.2.5 API)

java.lang.Object
- java.lang.Number
- - org.josef.science.math.CInteger

All Implemented Interfaces:

Serializable, Comparable<CInteger>
```
@Status(stage=PRODUCTION,
        unitTests=COMPLETE)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
 @ThreadSafety(level=IMMUTABLE)
public final class CInteger
extends Number
implements Comparable<CInteger>
```
This class wraps a primitive integer value.
The main difference between this class and class Integer is that this class has support for arithmetic operations that protect against both underflow and overflow.
Design considerations: Class Integer is final so this class extends class Number instead. This class is immutable and contains private constructors in combination with static factory methods as suggested by Joshua Bloch (Effective Java, Second Edition, item 15).

Version:

2.0 $Revision: 6488 $

Author:

Kees Schotanus

See Also:

Serialized Form

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CInteger`	`add(int value)` Adds the supplied value to this value.
`static int`	`add(int x, int y)` Adds y to x.
`byte`	`byteValue()` Returns the value of this CInteger as a byte.
`int`	`compareTo(CInteger object)` Compares two CInteger objects numerically.
`CInteger`	`divide(int value)` Divides this value by the supplied value.
`static int`	`divide(int x, int y)` Divides x by y.
`CInteger`	`divideAndFloor(int value)` Divides this value by the supplied value and floors the result.
`static int`	`divideAndFloor(int x, int y)` Divides x by y and floors the result.
`double`	`doubleValue()` Returns the value of this CInteger as a double.
`boolean`	`equals(Object object)` Determines whether this object and the supplied object are the same.
`float`	`floatValue()` Returns the value of this CInteger as a float.
`int`	`hashCode()` Computes the hash code value for this object.
`int`	`intValue()` Returns the value of this CInteger as an integer.
`long`	`longValue()` Returns the value of this CInteger as a long.
`CInteger`	`multiply(int value)` Multiplies this value by the supplied value.
`static int`	`multiply(int x, int y)` Multiplies x by y.
`static int`	`random0(int maximum)` Computes a zero based random integer up to but not including the supplied maximum.
`static int`	`random1(int maximum)` Computes a one based random integer up to and including the supplied maximum.
`short`	`shortValue()` Returns the value of this CInteger as a short.
`CInteger`	`subtract(int value)` Subtracts the supplied value from this value.
`static int`	`subtract(int x, int y)` Subtracts y from x.
`String`	`toString()` Converts the stored primitive integer value to a String.
`static CInteger`	`valueOf(int value)` Returns a CInteger object holding the value of the supplied value.
`static CInteger`	`valueOf(long value)` Returns a CInteger object holding the value of the supplied value.
`static CInteger`	`valueOf(Number value)` Returns a CInteger object holding the value of the supplied value.
`static CInteger`	`valueOf(String value)` Returns a CInteger object holding the parsed value of the supplied value.

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

- Method Detail
  - byteValue
```
public byte byteValue()
```
    Returns the value of this CInteger as a byte.
    
    Overrides:
    
    byteValue in class Number
    
    Returns:
    
    The value of this CInteger as a byte.
  - shortValue
```
public short shortValue()
```
    Returns the value of this CInteger as a short.
    
    Overrides:
    
    shortValue in class Number
    
    Returns:
    
    The value of this CInteger as a short.
  - intValue
```
public int intValue()
```
    Returns the value of this CInteger as an integer.
    
    Specified by:
    
    intValue in class Number
    
    Returns:
    
    The value of this CInteger as an integer.
  - longValue
```
public long longValue()
```
    Returns the value of this CInteger as a long.
    
    Specified by:
    
    longValue in class Number
    
    Returns:
    
    The value of this CInteger as a long.
  - floatValue
```
public float floatValue()
```
    Returns the value of this CInteger as a float.
    
    Specified by:
    
    floatValue in class Number
    
    Returns:
    
    The value of this CInteger as a float.
  - doubleValue
```
public double doubleValue()
```
    Returns the value of this CInteger as a double.
    
    Specified by:
    
    doubleValue in class Number
    
    Returns:
    
    The value of this CInteger as a double.
  - valueOf
```
public static CInteger valueOf(int value)
```
    Returns a CInteger object holding the value of the supplied value.
    
    Parameters:
    
    value - The integer value.
    
    Returns:
    
    A CInteger object holding the value of the supplied value.
  - valueOf
```
public static CInteger valueOf(long value)
```
    Returns a CInteger object holding the value of the supplied value.
    
    Parameters:
    
    value - The long value.
    
    Returns:
    
    A CInteger object holding the value of the supplied value.
    
    Throws:
    
    IllegalArgumentException - When the supplied value is not in the range: [Integer.MIN_VALUE to Integer.MAX_VALUE].
  - valueOf
```
public static CInteger valueOf(Number value)
```
    Returns a CInteger object holding the value of the supplied value.
    Depending on the type of the supplied value this may involve rounding.
    
    Parameters:
    
    value - The Number that holds the value.
    
    Returns:
    
    A CInteger object holding the value of the supplied value.
    When the supplied value is Not A Number, 0 is returned.
    
    Throws:
    
    NullPointerException - When the supplied value is null.
    
    IllegalArgumentException - When the supplied value is not in the range: [Integer.MIN_VALUE to Integer.MAX_VALUE].
  - valueOf
```
public static CInteger valueOf(String value)
```
    Returns a CInteger object holding the parsed value of the supplied value.
    
    Parameters:
    
    value - The String that is parsed.
    
    Returns:
    
    A CInteger object holding the value of the supplied value, after parsing.
    
    Throws:
    
    IllegalArgumentException - When the supplied value (after parsing) is not in the range: [Integer.MIN_VALUE to Integer.MAX_VALUE].
    
    NumberFormatException - When the supplied value does not contain a parsable int (this includes a null or empty value).
    
    See Also:
    
    Integer.parseInt(String)
  - equals
```
public boolean equals(Object object)
```
    Determines whether this object and the supplied object are the same.
    The two objects are the same if the supplied object is not null and the supplied object is a CInteger and the stored value in both objects is the same.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    object - The CInteger object to compare with.
    
    Returns:
    
    True if both objects are the same, false otherwise.
  - hashCode
```
public int hashCode()
```
    Computes the hash code value for this object.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    Primitive integer value of the stored integer value.
  - compareTo
```
public int compareTo(CInteger object)
```
    Compares two CInteger objects numerically.
    
    Specified by:
    
    compareTo in interface Comparable<CInteger>
    
    Parameters:
    
    object - CInteger object to compare with this object.
    
    Returns:
    
    a negative number when this value < other value, 0 when both values are equal and a positive number when this value > other value.
    
    Throws:
    
    NullPointerException - When the supplied object is null.
    
    See Also:
    
    Comparable
  - add
```
public CInteger add(int value)
```
    Adds the supplied value to this value.
    This method allows for expressions like: CInteger value = i.add(x).multiply(y) where i is a CInteger and x and y are primitive integers.
    
    Parameters:
    
    value - Value to add to the stored value.
    
    Returns:
    
    Result of the addition in a new CInteger.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs.
    
    See Also:
    
    add(int, int)
  - add
```
public static int add(int x,
                      int y)
```
    Adds y to x.
    
    Parameters:
    
    x - Operand one.
    
    y - Operand two.
    
    Returns:
    
    Result of the addition.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs.
  - subtract
```
public CInteger subtract(int value)
```
    Subtracts the supplied value from this value.
    This method allows for expressions like: CInteger value = i.subtract(x).multiply(y) where i is a CInteger and x and y are primitive integers.
    
    Parameters:
    
    value - Value to subtract from the stored value.
    
    Returns:
    
    Result of the subtraction in a new CInteger.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs.
    
    See Also:
    
    subtract(int, int)
  - subtract
```
public static int subtract(int x,
                           int y)
```
    Subtracts y from x.
    
    Parameters:
    
    x - Operand one.
    
    y - operand two.
    
    Returns:
    
    Result of the subtraction.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs.
  - multiply
```
public CInteger multiply(int value)
```
    Multiplies this value by the supplied value.
    This method allows for expressions like: CInteger value = i.multiply(x).subtract(y) where i is a CInteger and x and y are primitive integers.
    
    Parameters:
    
    value - Value to multiply by the stored value.
    
    Returns:
    
    Result of the multiplication in a new CInteger.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs.
    
    See Also:
    
    multiply(int, int)
  - multiply
```
public static int multiply(int x,
                           int y)
```
    Multiplies x by y.
    
    Parameters:
    
    x - Operand one.
    
    y - Operand two.
    
    Returns:
    
    Result of the multiplication.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs.
  - divide
```
public CInteger divide(int value)
```
    Divides this value by the supplied value.
    This method allows for expressions like: CInteger value = i.divide(x).add(y) where i is a CInteger and x and y are primitive integers.
    
    Parameters:
    
    value - Value by which this value will be divided.
    
    Returns:
    
    Result of the division in a new CInteger.
    
    Throws:
    
    ArithmeticException - When an arithmetic overflow occurs or when the supplied value is 0.
    
    See Also:
    
    divide(int, int)
  - divide
```
public static int divide(int x,
                         int y)
```
    Divides x by y.
    
    Parameters:
    
    x - Operand one.
    
    y - Operand two.
    
    Returns:
    
    Result of the division.
    
    Throws:
    
    ArithmeticException - When an arithmetic overflow occurs or when the supplied y value is 0.
  - divideAndFloor
```
public CInteger divideAndFloor(int value)
```
    Divides this value by the supplied value and floors the result.
    This method does not work like integer division in Java. In Java -1 / 4 results in 0 but this method returns a value of -1. It works as if the result of the standard Java division is floored and then returned.
    
    Parameters:
    
    value - Value by which this value will be divided.
    
    Returns:
    
    Result of the division in a new CInteger.
    
    Throws:
    
    ArithmeticException - When an arithmetic overflow occurs or when the supplied value is 0.
    
    See Also:
    
    divideAndFloor(int, int)
  - divideAndFloor
```
public static int divideAndFloor(int x,
                                 int y)
```
    Divides x by y and floors the result.
    This method does not work like integer division in Java. In Java -1 / 4 results in 0 but this method returns a value of -1. It works as if the result of the standard Java division is floored and then returned.
    
    Parameters:
    
    x - Operand one.
    
    y - Operand two.
    
    Returns:
    
    Result of the division.
    
    Throws:
    
    ArithmeticException - When an arithmetic overflow occurs or when the supplied y value is 0.
  - random0
```
public static int random0(int maximum)
```
    Computes a zero based random integer up to but not including the supplied maximum.
    
    Parameters:
    
    maximum - The maximum integer (exclusive) to return.
    
    Returns:
    
    A random integer between 0 (inclusive) and maximum (exclusive).
    
    Throws:
    
    IllegalArgumentException - When the supplied maximum is less than one.
  - random1
```
public static int random1(int maximum)
```
    Computes a one based random integer up to and including the supplied maximum.
    For example: to simulate the throw of a dice use:
    int dice = CInteger.random1(6);
    
    Parameters:
    
    maximum - The maximum integer (inclusive) to return.
    
    Returns:
    
    A random integer between 1 (inclusive) and maximum (inclusive).
    
    Throws:
    
    IllegalArgumentException - When the supplied maximum is less than two.
  - toString
```
public String toString()
```
    Converts the stored primitive integer value to a String.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    String representation of the stored integer value.

Class CInteger

Method Summary

Methods inherited from class java.lang.Object

Method Detail

byteValue

shortValue

intValue

longValue

floatValue

doubleValue

valueOf

valueOf

valueOf

valueOf

equals

hashCode

compareTo

add

add

subtract

subtract

multiply

multiply

divide

divide

divideAndFloor

divideAndFloor

random0

random1

toString