CLong (josef 3.2.5 API)

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

All Implemented Interfaces:

Serializable, Comparable<CLong>
```
@Status(stage=PRODUCTION,
        unitTests=ABSENT)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
 @ThreadSafety(level=IMMUTABLE)
public final class CLong
extends Number
implements Comparable<CLong>
```
This class wraps a primitive long value.
The main difference between this class and class Long is that this class has support for arithmetic operations that protect against both underflow and overflow.
Design considerations: Class Long 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

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class CLong.FibonacciIterator
Iterator suitable for iterating over all the Fibonacci numbers in sequence.

Nested Classes
Modifier and Type	Class and Description
`static class`	`CLong.FibonacciIterator` Iterator suitable for iterating over all the Fibonacci numbers in sequence.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`MAX_FACTORIAL_ORDINAL` The maximum ordinal for which the factorial can be calculated.
`static int`	`MAX_FIBONACCI_ORDINAL` The maximum ordinal for which the Fibonacci number can be calculated.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CLong`	`add(long value)` Adds the supplied value to this value.
`static long`	`add(long x, long y)` Adds y to x.
`byte`	`byteValue()` Returns the value of this CLong as a byte.
`int`	`compareTo(CLong object)` Compares two CLong objects numerically.
`CLong`	`divide(long value)` Divides this value by the supplied value.
`static long`	`divide(long x, long y)` Divides x by y.
`CLong`	`divideAndFloor(long value)` Divides this value by the supplied value and floors the result.
`static long`	`divideAndFloor(long x, long y)` Divides x by y and floors the result.
`double`	`doubleValue()` Returns the value of this CLong as a double.
`boolean`	`equals(Object object)` Determines whether this object and the supplied object are the same.
`static long`	`factorial(int value)` Computes the factorial of the supplied value.
`static long`	`fibonacci(int x)` Computes fibonacci number x.
`static CLong.FibonacciIterator`	`fibonacciIterator()` Creates a Fibonacci Iterator that allows you to iterate over all the Fibonacci numbers in sequence.
`float`	`floatValue()` Returns the value of this CLong as a float.
`static long`	`greatestCommonDivisor(long first, long second)` Computes the greatest common divisor of two long values.
`int`	`hashCode()` Computes a hash code for this object using the same algorithm as `Long.hashCode()` does.
`int`	`intValue()` Returns the value of this CLong as an integer.
`static boolean`	`isPrime(long value)` Determines whether the supplied value is a prime.
`static long`	`leastCommonMultiple(long a, long b)` Computes the least common multiple of two long values.
`long`	`longValue()` Returns the value of this CLong as a long.
`CLong`	`multiply(long value)` Multiplies this value by the supplied value.
`static long`	`multiply(long x, long y)` Multiplies x by y.
`static long`	`round(long value, int position)` Rounds the supplied value to the supplied position.
`static long`	`roundUp(long value, int position)` Rounds the supplied value up to the supplied position.
`short`	`shortValue()` Returns the value of this CLong as a short.
`CLong`	`subtract(long value)` Subtracts the supplied value from this value.
`static long`	`subtract(long x, long y)` Subtracts y from x.
`String`	`toString()` Converts the stored primitive long value to a String.
`static CLong`	`valueOf(int value)` Returns a CLong object holding the value of the supplied value.
`static CLong`	`valueOf(long value)` Returns a CLong object holding the value of the supplied value.
`static CLong`	`valueOf(Number value)` Returns a CLong object holding the value of the supplied value.
`static CLong`	`valueOf(String value)` Returns a CLong object holding the parsed value of the supplied value.

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

- Field Detail
  - MAX_FACTORIAL_ORDINAL
```
public static final int MAX_FACTORIAL_ORDINAL
```
    The maximum ordinal for which the factorial can be calculated.
    
    See Also:
    
    Constant Field Values
  - MAX_FIBONACCI_ORDINAL
```
public static final int MAX_FIBONACCI_ORDINAL
```
    The maximum ordinal for which the Fibonacci number can be calculated.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - byteValue
```
public byte byteValue()
```
    Returns the value of this CLong as a byte.
    
    Overrides:
    
    byteValue in class Number
    
    Returns:
    
    The value of this CLong as a byte.
  - shortValue
```
public short shortValue()
```
    Returns the value of this CLong as a short.
    
    Overrides:
    
    shortValue in class Number
    
    Returns:
    
    The value of this CLong as a short.
  - intValue
```
public int intValue()
```
    Returns the value of this CLong as an integer.
    
    Specified by:
    
    intValue in class Number
    
    Returns:
    
    The value of this CLong as an integer.
  - longValue
```
public long longValue()
```
    Returns the value of this CLong as a long.
    
    Specified by:
    
    longValue in class Number
    
    Returns:
    
    The value of this CLong as a long.
  - floatValue
```
public float floatValue()
```
    Returns the value of this CLong as a float.
    
    Specified by:
    
    floatValue in class Number
    
    Returns:
    
    The value of this CLong as a float.
  - doubleValue
```
public double doubleValue()
```
    Returns the value of this CLong as a double.
    
    Specified by:
    
    doubleValue in class Number
    
    Returns:
    
    The value of this CLong as a double.
  - valueOf
```
public static CLong valueOf(int value)
```
    Returns a CLong object holding the value of the supplied value.
    
    Parameters:
    
    value - The long value.
    
    Returns:
    
    A CLong object holding the value of the supplied value.
  - valueOf
```
public static CLong valueOf(long value)
```
    Returns a CLong object holding the value of the supplied value.
    
    Parameters:
    
    value - The long value.
    
    Returns:
    
    A CLong object holding the value of the supplied value.
  - valueOf
```
public static CLong valueOf(Number value)
```
    Returns a CLong object holding the value of the supplied value.
    Depending on the type of the supplied value this may involve rounding. Technically the method Number.longValue() is used to perform the conversion.
    
    Parameters:
    
    value - The Number that holds the value.
    
    Returns:
    
    A CLong 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.
  - valueOf
```
public static CLong valueOf(String value)
```
    Returns a CLong object holding the parsed value of the supplied value.
    
    Parameters:
    
    value - The String that is parsed.
    
    Returns:
    
    A CLong object holding the value of the supplied value, after parsing.
    
    Throws:
    
    IllegalArgumentException - When the supplied value (after parsing) is not in the range: [Long.MIN_VALUE to Long.MAX_VALUE].
    
    NumberFormatException - When the supplied value does not contain a parsable long (this includes a null or empty value).
    
    See Also:
    
    Long.parseLong(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 CLong and the stored value in both objects is the same.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    object - The CLong object to compare with.
    
    Returns:
    
    True if both objects are the same, false otherwise.
  - hashCode
```
public int hashCode()
```
    Computes a hash code for this object using the same algorithm as Long.hashCode() does.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    A hash code value for this object.
  - compareTo
```
public int compareTo(CLong object)
```
    Compares two CLong objects numerically.
    
    Specified by:
    
    compareTo in interface Comparable<CLong>
    
    Parameters:
    
    object - CLong object to compare with this object.
    
    Returns:
    
    -1 when this < object, 0 when this == object, 1 when this > object.
    
    Throws:
    
    NullPointerException - When the supplied object is null.
    
    See Also:
    
    Comparable
  - add
```
public CLong add(long value)
```
    Adds the supplied value to this value.
    This method allows for expressions like: CLong value = i.add(x).multiply(y) where i is a CLong and x and y are primitive longs.
    
    Parameters:
    
    value - Value to add to the stored value.
    
    Returns:
    
    Result of the addition in a new CLong.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs.
    
    See Also:
    
    add(long, long)
  - add
```
public static long add(long x,
                       long 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 CLong subtract(long value)
```
    Subtracts the supplied value from this value.
    This method allows for expressions like: CLong value = i.subtract(x).multiply(y) where i is a CLong and x and y are primitive integers.
    
    Parameters:
    
    value - Value to subtract from the stored value.
    
    Returns:
    
    Result of the subtraction in a new CLong.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs.
    
    See Also:
    
    subtract(long, long)
  - subtract
```
public static long subtract(long x,
                            long 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 CLong multiply(long value)
```
    Multiplies this value by the supplied value.
    This method allows for expressions like: CLong value = i.multiply(x).subtract(y) where i is a CLong and x and y are primitive longs.
    
    Parameters:
    
    value - Value to multiply by the stored value.
    
    Returns:
    
    Result of the multiplication in a new CLong.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs.
    
    See Also:
    
    multiply(long, long)
  - multiply
```
public static long multiply(long x,
                            long 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 CLong divide(long value)
```
    Divides this value by the supplied value.
    This method allows for expressions like: CLong value = i.divide(x).add(y) where i is a CLong and x and y are primitive longs.
    
    Parameters:
    
    value - Value by which this value will be divided.
    
    Returns:
    
    Result of the division in a new CLong.
    
    Throws:
    
    ArithmeticException - When an arithmetic overflow occurs or when the supplied value is 0.
    
    See Also:
    
    divide(long, long)
  - divide
```
public static long divide(long x,
                          long 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 CLong divideAndFloor(long 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 CLong.
    
    Throws:
    
    ArithmeticException - When an arithmetic overflow occurs or when the supplied value is 0.
    
    See Also:
    
    divideAndFloor(long, long)
  - divideAndFloor
```
public static long divideAndFloor(long x,
                                  long 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.
  - greatestCommonDivisor
```
public static long greatestCommonDivisor(long first,
                                         long second)
```
    Computes the greatest common divisor of two long values.
    Given two integers a and b, a common divisor of a and b is an integer which divides both numbers, and the greatest common divisor is the largest such integer.
    The algorithm used is the one by Euclid found in Book VII of Euclid's 'Elements'.
    Source: Sourcebook for programmable calculators. ISBN: 0-89512-025-9
    
    Parameters:
    
    first - The first value.
    
    second - The second value.
    
    Returns:
    
    Greatest common divisor of the supplied values.
    
    Throws:
    
    IllegalArgumentException - When the supplied second parameter is 0.
  - leastCommonMultiple
```
public static long leastCommonMultiple(long a,
                                       long b)
```
    Computes the least common multiple of two long values.
    The least common multiple of a and b is the smallest integer that is divisible by both a and b. The least common multiple (lcm) can easily be computed if the greatest common divisor (gcd) of a and b is known (lcm = a*b/gcd).
    
    Parameters:
    
    a - The first long value.
    
    b - The second long value.
    
    Returns:
    
    Least common multiple of the supplied values a and b.
  - isPrime
```
public static boolean isPrime(long value)
```
    Determines whether the supplied value is a prime.
    A number is a prime if the number can only be divided by 1 and by itself. By definition 0 and 1 are not primes.
    You can check whether a number is a prime by dividing the number by all values from 2 up to and including the square root of the number. If none of these divisions results in an integer the number is a prime.
    The only optimization made here is that the number is only divided by odd numbers from 3 up. In theory this would be twice as fast compared to having no optimization at all but still this method is quite slow for large long values!
    Did you know that for every n >= 2 at least one prime exists between n and 2 times n?
    
    Parameters:
    
    value - Value to check whether it is a prime number or not.
    
    Returns:
    
    True when the supplied value is a prime, false otherwise.
  - factorial
```
public static long factorial(int value)
```
    Computes the factorial of the supplied value.
    The factorial of 0 is 1 and for all other positive numbers n it is defined as: 1x2x3x...n
    This method is often implemented using recursion:
```
 public static long factorialRecursive(final long value) {
     if (value <= 1) {
         return 1;
     } else {
         return value * factorialRecursive(value - 1);
     }
 }
 
```
    If you check out the actual implementation you will see that not using recursion is better in this case. The current implementation does not have the overhead of method calls and only has to check for a wrong supplied value, once (the implementation above does not check for errors, but if it did, it would do so on every recursive call).
    Parameters:
    
    value - Value for which the factorial is calculated.
    
    Returns:
    
    Factorial of the supplied value.
    
    Throws:
    
    IllegalArgumentException - When supplied value is not in range: 0 <= value <= MAX_FIBONACCI_ORDINAL.
  - fibonacci
```
public static long fibonacci(int x)
```
    Computes fibonacci number x.
    The sequence of fibonacci numbers goes like this:
```
 #0:  0 By definition
 #1:  1 By definition
 #2:  1 For all others it is the sum of the previous two numbers.
 #3:  2
 #4:  3
 #5:  5
 #6:  8
 #7: 13
 #8: 21
 #9: 34
 
```
    Parameters:
    
    x - The fibonacci number to compute.
    
    Returns:
    
    Fibonacci number x.
    
    Throws:
    
    IllegalArgumentException - When the supplied x value is < 0.
    
    ArithmeticException - When the supplied x value is larger than MAX_FIBONACCI_ORDINAL since the result would not fit into a long.
  - fibonacciIterator
```
public static CLong.FibonacciIterator fibonacciIterator()
```
    Creates a Fibonacci Iterator that allows you to iterate over all the Fibonacci numbers in sequence.
    
    Returns:
    
    A Fibonacci Iterator.
  - round
```
public static long round(long value,
                         int position)
```
    Rounds the supplied value to the supplied position.
    The value is rounded to the nearest neighbor unless both neighbors are equidistant, in which case the value is rounded up.
    For example:
    CLong.round( 55, 1) => 60 since value is rounded up.
    CLong.round(-55, 1) => -50 since value is rounded up.
    
    Parameters:
    
    value - The value to round.
    
    position - The position to which this value should be rounded.
    1 rounds to tens.
    2 rounds to hundreds.
    3 rounds to thousands.
    
    Returns:
    
    Supplied value rounded to the supplied position.
    
    Throws:
    
    IllegalArgumentException - When the supplied position is negative.
  - roundUp
```
public static long roundUp(long value,
                           int position)
```
    Rounds the supplied value up to the supplied position. CLong.round( 54, 1) => 60 since value is rounded up.
    CLong.round(-55, 1) => -50 since value is rounded up.
    
    Parameters:
    
    value - The value to round.
    
    position - The position to which this value should be rounded.
    1 rounds to tens.
    2 rounds to hundreds.
    3 rounds to thousands.
    
    Returns:
    
    Supplied value rounded to the supplied position.
    
    Throws:
    
    IllegalArgumentException - When the supplied position is negative.
  - toString
```
public String toString()
```
    Converts the stored primitive long value to a String.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    String representation of the stored long value.

Class CLong

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MAX_FACTORIAL_ORDINAL

MAX_FIBONACCI_ORDINAL

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

greatestCommonDivisor

leastCommonMultiple

isPrime

factorial

fibonacci

fibonacciIterator

round

roundUp

toString