CDouble (josef 3.2.5 API)

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

All Implemented Interfaces:

Serializable, Comparable<CDouble>
```
@Status(stage=PRODUCTION,
        unitTests=COMPLETE)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
 @ThreadSafety(level=IMMUTABLE)
public final class CDouble
extends Number
implements Comparable<CDouble>
```
This class wraps a primitive double value.
The main difference between this class and class Double is that this class has (limited) support for arithmetic operations that protect against both underflow and overflow.
Note: The support for underflow/overflow checks is limited since for example Double.MAX_VALUE + 1 equals Double.MAX_VALUE. After an operation, a check for infinity is performed but as explained before, this won't catch all underflow and overflow conditions.
Design considerations: Class Double 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

Field Summary

Fields
Modifier and Type	Field and Description
`static double`	`FOUR` The constant value 4.0.
`static double`	`HUNDRED_PERCENT` 100%.
`static double`	`ONE_FOURTH` 1/4.
`static double`	`ONE_THIRD` 1/3.
`static double`	`TEN_PERCENT` 10%.
`static double`	`THREE` The constant value 3.0.
`static double`	`THREE_QUARTERS` 3/4.
`static double`	`TWO_THIRDS` 2/3.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CDouble`	`add(double value)` Adds the supplied value to this value.
`static double`	`add(double x, double y)` Adds y to x.
`byte`	`byteValue()` Returns the value of this CDouble as a byte.
`int`	`compareTo(CDouble object)` Compares two CDouble objects numerically.
`CDouble`	`divide(double value)` Divides this value by the supplied value.
`static double`	`divide(double x, double y)` Divides x by y.
`double`	`doubleValue()` Returns the value of this CDouble as a double.
`static boolean`	`equals(double left, double right, double delta)` Determines whether the supplied left and right double are equal to each other within the limit of the supplied delta.
`boolean`	`equals(Object object)` Determines whether this object and the supplied object are the same.
`float`	`floatValue()` Returns the value of this CDouble as a float.
`static int`	`getFractionDigits(double value, int roundTo)` Calculates the number of digits after the decimal point of the supplied value.
`int`	`getFractionDigits(int roundTo)` Calculates the number of digits after the decimal point.
`static int`	`getIntegerDigits(double value, int roundTo)` Calculates the number of digits before the decimal point.
`int`	`getIntegerDigits(int roundTo)` Calculates the number of digits before the decimal point.
`int`	`hashCode()` Computes the hash code value for this object.
`int`	`intValue()` Returns the value of this CDouble as an int.
`long`	`longValue()` Returns the value of this CDouble as a long.
`CDouble`	`multiply(double value)` Multiplies this value by the supplied value.
`static double`	`multiply(double x, double y)` Multiplies x by y.
`static double`	`round(double value, int decimals)` Rounds the supplied value to the supplied number of decimals.
`CDouble`	`round(int decimals)` Rounds this value to the supplied number of decimals.
`static double`	`roundUp(double value, int decimals)` Rounds the supplied value up, to the supplied number of decimals.
`short`	`shortValue()` Returns the value of this CDouble as a short.
`static double`	`subtract(double x, double y)` Subtracts y from x.
`CDouble`	`subtract(long value)` Subtracts the supplied value from this value.
`String`	`toString()` Converts the stored primitive double value to a String.
`static CDouble`	`valueOf(int value)` Returns a CDouble object holding the value of the supplied value.
`static CDouble`	`valueOf(long value)` Returns a CDouble object holding the value of the supplied value.
`static CDouble`	`valueOf(Number value)` Returns a CDouble object holding the value of the supplied value.
`static CDouble`	`valueOf(String value)` Returns a CDouble 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
  - THREE
```
public static final double THREE
```
    The constant value 3.0.
    
    See Also:
    
    Constant Field Values
  - FOUR
```
public static final double FOUR
```
    The constant value 4.0.
    
    See Also:
    
    Constant Field Values
  - ONE_THIRD
```
public static final double ONE_THIRD
```
    1/3.
    
    See Also:
    
    Constant Field Values
  - TWO_THIRDS
```
public static final double TWO_THIRDS
```
    2/3.
    
    See Also:
    
    Constant Field Values
  - ONE_FOURTH
```
public static final double ONE_FOURTH
```
    1/4.
    
    See Also:
    
    Constant Field Values
  - THREE_QUARTERS
```
public static final double THREE_QUARTERS
```
    3/4.
    
    See Also:
    
    Constant Field Values
  - TEN_PERCENT
```
public static final double TEN_PERCENT
```
    10%.
    
    See Also:
    
    Constant Field Values
  - HUNDRED_PERCENT
```
public static final double HUNDRED_PERCENT
```
    100%.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - byteValue
```
public byte byteValue()
```
    Returns the value of this CDouble as a byte.
    
    Overrides:
    
    byteValue in class Number
    
    Returns:
    
    The value of this CDouble as a byte.
  - shortValue
```
public short shortValue()
```
    Returns the value of this CDouble as a short.
    
    Overrides:
    
    shortValue in class Number
    
    Returns:
    
    The value of this CDouble as a short.
  - intValue
```
public int intValue()
```
    Returns the value of this CDouble as an int.
    
    Specified by:
    
    intValue in class Number
    
    Returns:
    
    The value of this CDouble as an int.
  - longValue
```
public long longValue()
```
    Returns the value of this CDouble as a long.
    
    Specified by:
    
    longValue in class Number
    
    Returns:
    
    The value of this CDouble as a long.
  - floatValue
```
public float floatValue()
```
    Returns the value of this CDouble as a float.
    
    Specified by:
    
    floatValue in class Number
    
    Returns:
    
    The value of this CDouble as a float.
  - doubleValue
```
public double doubleValue()
```
    Returns the value of this CDouble as a double.
    
    Specified by:
    
    doubleValue in class Number
    
    Returns:
    
    The value of this CDouble as a double.
  - valueOf
```
public static CDouble valueOf(int value)
```
    Returns a CDouble object holding the value of the supplied value.
    
    Parameters:
    
    value - The int value.
    
    Returns:
    
    A CDouble object holding the value of the supplied value.
  - valueOf
```
public static CDouble valueOf(long value)
```
    Returns a CDouble object holding the value of the supplied value.
    
    Parameters:
    
    value - The long value.
    
    Returns:
    
    A CDouble object holding the value of the supplied value.
    
    Throws:
    
    IllegalArgumentException - When the supplied value could not be converted to a double without losing precision.
  - valueOf
```
public static CDouble valueOf(Number value)
```
    Returns a CDouble 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 CDouble 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 CDouble valueOf(String value)
```
    Returns a CDouble object holding the parsed value of the supplied value.
    
    Parameters:
    
    value - The String that is parsed.
    
    Returns:
    
    A CDouble object holding the value of the supplied value, after parsing.
    
    Throws:
    
    NumberFormatException - When the supplied value does not contain a parsable double (this includes a null or empty value).
    
    See Also:
    
    Double.parseDouble(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 CDouble and the bit pattern of the stored value in both objects is the same. For consequences of comparing the bit pattern see Double.equals(Object).
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    object - The CDouble object to compare with.
    
    Returns:
    
    True if both objects are the same, false otherwise.
  - equals
```
public static boolean equals(double left,
                             double right,
                             double delta)
```
    Determines whether the supplied left and right double are equal to each other within the limit of the supplied delta.
    Both doubles are considered equal when the absolute difference between the two doubles is less than the supplied delta value. Using a delta is often necessary! The following expression for example does not result in 0.0: 7 * 0.1 - 0.7
    Note: This method tries to mimic evaluating: left == right
    See the jls to read about how special values like NaN and infinity are handled.
    
    Parameters:
    
    left - The double on the left of the mathematical equals sign.
    
    right - The double on the right of the mathematical equals sign.
    
    delta - The limit within the two doubles are considered to be equal.
    
    Returns:
    
    True when the left double equals the right double, false otherwise.
  - hashCode
```
public int hashCode()
```
    Computes the hash code value for this object.
    The double is 'treated' as a long and the same algorithm as for a CLong is used to compute this hash code.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    The hash code value for this object.
  - compareTo
```
public int compareTo(CDouble object)
```
    Compares two CDouble objects numerically.
    
    Specified by:
    
    compareTo in interface Comparable<CDouble>
    
    Parameters:
    
    object - CDouble 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, Double.compare(double, double)
  - add
```
public CDouble add(double value)
```
    Adds the supplied value to this value.
    This method allows for expressions like: CDouble value = i.add(x).multiply(y) where i is a CDouble and x and y are primitive doubles.
    
    Parameters:
    
    value - Value to add to the stored value.
    
    Returns:
    
    Result of the addition in a new CDouble.
    When this or the supplied value is NaN the result will be NaN.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs, possibly due to one of the values being infinite.
    
    See Also:
    
    add(double, double)
  - add
```
public static double add(double x,
                         double y)
```
    Adds y to x.
    
    Parameters:
    
    x - Operand one.
    
    y - Operand two.
    
    Returns:
    
    Result of the addition.
    When one of the supplied values is NaN the result will be NaN.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs, possibly due to one of the values being infinite.
  - subtract
```
public CDouble subtract(long value)
```
    Subtracts the supplied value from this value.
    This method allows for expressions like: CDouble value = i.subtract(x).multiply(y) where i is a CDouble and x and y are primitive doubles.
    
    Parameters:
    
    value - Value to subtract from the stored value.
    
    Returns:
    
    Result of the subtraction in a new CDouble.
    When this or the supplied value is NaN the result will be NaN.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs, possibly due to one of the values being infinite.
    
    See Also:
    
    subtract(double, double)
  - subtract
```
public static double subtract(double x,
                              double y)
```
    Subtracts y from x.
    
    Parameters:
    
    x - Operand one.
    
    y - operand two.
    
    Returns:
    
    Result of the subtraction.
    When one of the supplied values is NaN the result will be NaN.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs, possibly due to one of the values being infinite.
  - multiply
```
public CDouble multiply(double value)
```
    Multiplies this value by the supplied value.
    This method allows for expressions like: CDouble value = i.multiply(x).subtract(y) where i is a CDouble and x and y are primitive doubles.
    
    Parameters:
    
    value - Value to multiply by the stored value.
    
    Returns:
    
    Result of the multiplication in a new CDouble.
    When this or the supplied value is NaN the result will be NaN.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs, possibly due to one of the values being infinite.
    
    See Also:
    
    multiply(double, double)
  - multiply
```
public static double multiply(double x,
                              double y)
```
    Multiplies x by y.
    
    Parameters:
    
    x - Operand one.
    
    y - Operand two.
    
    Returns:
    
    Result of the multiplication.
    When one of the supplied values is NaN the result will be NaN.
    
    Throws:
    
    ArithmeticException - When an arithmetic underflow or overflow occurs, possibly due to one of the values being infinite.
  - divide
```
public CDouble divide(double value)
```
    Divides this value by the supplied value.
    This method allows for expressions like: CDouble value = i.divide(x).add(y) where i is a CDouble and x and y are primitive doubles.
    
    Parameters:
    
    value - Value by which this value will be divided.
    
    Returns:
    
    Result of the division in a new CDouble.
    When this or the supplied value is NaN the result will be NaN.
    
    Throws:
    
    ArithmeticException - When an arithmetic overflow occurs or when this value is infinite or when the supplied value is 0.
    
    See Also:
    
    divide(double, double)
  - divide
```
public static double divide(double x,
                            double y)
```
    Divides x by y.
    
    Parameters:
    
    x - Operand one.
    
    y - Operand two.
    
    Returns:
    
    Result of the division.
    When one of the supplied values is NaN the result will be NaN.
    
    Throws:
    
    ArithmeticException - When an arithmetic overflow occurs or when the supplied x value is infinite or when the supplied value is 0.
  - round
```
public CDouble round(int decimals)
```
    Rounds this value to the supplied number of decimals.
    See: round(double, int) for details.
    
    Parameters:
    
    decimals - The number of decimal places to which this value should be rounded.
    
    Returns:
    
    Result of the rounding in a new CDouble.
    
    See Also:
    
    round(double, int)
  - round
```
public static double round(double value,
                           int decimals)
```
    Rounds the supplied value to the supplied number of decimals.
    The value is rounded to the nearest neighbor unless both neighbors are equidistant, in which case the value is rounded up. Here are some examples:
    
    Value Decimals Result
    
    12.5 0 13 Equidistant, round up
    
    -12.5 0 -12 Equidistant, -12 > -13
    
    17.457 2 17.46
    
    17.457 1 17.5
    
    17.457 0 17
    
    17.457 -1 20 Rounds to tens
    
    Note that just like some values can't be properly expressed in decimal notation (1/3=0.333333333...), a correct binary representation is not always possible. So rounding to n decimal places is no guarantee that the resulting value actually contains n decimals!
    Note that this method has no protection against overflow.
    
    Parameters:
    
    value - The value to round.
    
    decimals - The number of decimal places to which this value should be rounded.
    The number of decimals may be negative to round to a position before the decimal point.
    
    Returns:
    
    Supplied value rounded to the supplied number of decimals.
  - roundUp
```
public static double roundUp(double value,
                             int decimals)
```
    Rounds the supplied value up, to the supplied number of decimals. For example:
    CDouble.roundUp(12.34, 1) => 12.4
    CLong.round(-12.34, 1) => -12.3.
    The same notes apply as for round(double, int).
    
    Parameters:
    
    value - The value to round up.
    
    decimals - The number of decimal places to which this value should be rounded.
    The number of decimals may be negative to round to a position before the decimal point.
    
    Returns:
    
    Supplied value rounded up to the supplied number of decimals.
  - getIntegerDigits
```
public int getIntegerDigits(int roundTo)
```
    Calculates the number of digits before the decimal point.
    Note: This method has no protection against arithmetic overflow!
    
    Parameters:
    
    roundTo - Number of decimal places to round to.
    This parameter is necessary since a double value can be stored as 6.99999999999998 for example, instead of 7. Rounding solves this problem.
    
    Returns:
    
    Number of digits before the decimal point in this value.
    
    Throws:
    
    IllegalArgumentException - When the supplied roundTo value is negative.
    
    See Also:
    
    getIntegerDigits(double, int)
  - getIntegerDigits
```
public static int getIntegerDigits(double value,
                                   int roundTo)
```
    Calculates the number of digits before the decimal point.
    Note: This method has no protection against arithmetic overflow!
    
    Parameters:
    
    value - Value for which the number of integer digits is calculated.
    
    roundTo - Number of decimal places to round to.
    This parameter is necessary since a double value can be stored as 6.99999999999998 for example, instead of 7. Rounding solves this problem. Here are some examples:
    
    Value Round to Result
    
    0.3333 2 0
    99.95 1 3
    99.95 2 2
    
    Returns:
    
    Number of digits before the decimal point.
    
    Throws:
    
    IllegalArgumentException - When the supplied roundTo value is negative.
  - getFractionDigits
```
public int getFractionDigits(int roundTo)
```
    Calculates the number of digits after the decimal point.
    
    Parameters:
    
    roundTo - Number of decimal places to round to.
    This parameter is necessary since a double value can be stored as 0.099999999999998 for example, instead of 0.1. Rounding solves this problem.
    
    Returns:
    
    Number of digits after the decimal point.
    
    Throws:
    
    IllegalArgumentException - When the supplied roundTo value is negative.
    
    See Also:
    
    getFractionDigits(double, int)
  - getFractionDigits
```
public static int getFractionDigits(double value,
                                    int roundTo)
```
    Calculates the number of digits after the decimal point of the supplied value.
    
    Parameters:
    
    value - The value to get the number of fraction digits of.
    
    roundTo - Number of decimal places to round to.
    This parameter is necessary since a double value can be stored as 0.099999999999998 for example, instead of 0.1. Rounding solves this problem.
    
    Returns:
    
    Number of digits after the decimal point.
    
    Throws:
    
    IllegalArgumentException - When the supplied roundTo value is negative.
  - toString
```
public String toString()
```
    Converts the stored primitive double value to a String.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    String representation of the stored value.

Value	Decimals	Result
12.5	0	13 Equidistant, round up
-12.5	0	-12 Equidistant, -12 > -13
17.457	2	17.46
17.457	1	17.5
17.457	0	17
17.457	-1	20 Rounds to tens

Value	Round to	Result
0.3333	2	0
99.95	1	3
99.95	2	2

Class CDouble

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

THREE

FOUR

ONE_THIRD

TWO_THIRDS

ONE_FOURTH

THREE_QUARTERS

TEN_PERCENT

HUNDRED_PERCENT

Method Detail

byteValue

shortValue

intValue

longValue

floatValue

doubleValue

valueOf

valueOf

valueOf

valueOf

equals

equals

hashCode

compareTo

add

add

subtract

subtract

multiply

multiply

divide

divide

round

round

roundUp

getIntegerDigits

getIntegerDigits

getFractionDigits

getFractionDigits

toString