Money (OpenXLS Java Spreadsheet SDK 11.0.4 API)

java.lang.Object
- io.starter.toolkit.Money

All Implemented Interfaces:

Serializable, Cloneable
```
public class Money
extends Object
implements Cloneable, Serializable
```
Class Money
The Money class represents a United States monetary value, expressed in dollars and cents. Internally, the value is represented using Java's BigDecimal class.

Methods are provided to perform all the usual arithmetic manipulations required when dealing with monetary data, including add, subtract, multiply, and divide.

Rounding

Rounding does not occur during intermediate computations; maximum precision (and accuracy) is thus preserved throughout all computations. Round-off to an integral cent occurs only when the monetary value is externalized (when formatted for display as a String or converted to a long integer). One of several different rounding modes can be specified. The default rounding mode is to discard any fractional cent and truncate the monetary value to 2 decimal places.

Currency Format

A Currency Format (an instance of DecimalFormat) is used to control formatting of monetary values for display as well as the parsing of strings which represent monetary values. By default, the Currency Format for the current locale is used. For the United States, the default Currency Symbol is the Dollar Sign ("$"). Negative amounts are enclosed in parentheses. A Decimal Point (".") separates the dollars and cents, and a comma (",") separates each group of 3 consecutive digits in the dollar amount.

Examples: $1,234.56 ($1,234.56)

Immutability

Money objects, like String objects, are immutable. An operation on a Money object (such as add, subtract, etc.) does not alter the object in any way. Rather, a new Money object is returned whose state reflects the result of the operation. Thus, a statement like

money1.add(money2);

has no effect; it does not modify money1 in any way, and the result is effectively discarded. If the intent is to modify money1, then you should code

money1 = money1.add(money2);

which effectively replaces money1 with the result.

See Also:

BigDecimal, DecimalFormat, Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Money.InvalidRoundingModeException` Class InvalidRoundingModeException
`static class`	`Money.InvalidScaleFactorException` Class InvalidScaleFactorException

Field Summary

Fields
Modifier and Type	Field and Description
`protected DecimalFormat`	`currencyFormat` The Currency Format, used for formatting and parsing a monetary value.
`protected int`	`roundingMode` The Rounding Mode.
`protected BigDecimal`	`value` The monetary value.
`protected static BigDecimal`	`ZERO` The special monetary value of zero ($0.00).

Constructor Summary

Constructors
Constructor and Description
`Money()` Default Constructor for a Money object; creates an object whose value is $0.00.
`Money(BigDecimal amount)` Constructs a Money object from a BigDecimal object.
`Money(double amount)` Constructs a Money object from a double-precision, floating-point value.
`Money(long amount)` Constructs a Money object from a long integer value.
`Money(long amount, int scale)` Constructs a Money object from a long integer value with a specified scale factor.
`Money(Money amount)` Copy Constructor; constructs a Money object from another Money object.
`Money(String string)` Constructs a Money object from a string representation of a monetary value.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Money`	`abs()` Returns the absolute monetary value.
`Money`	`add(Money money)` Adds a specified monetary value to this monetary value.
`Object`	`clone()` Clones a Money object.
`Money`	`divide(double div)` Divides this monetary value by a specified value.
`Money`	`divide(long div)` Divides this monetary value by a specified value.
`boolean`	`equals(Object object)` Compares this object with the specified object.
`DecimalFormat`	`getCurrencyFormat()` Returns the Currency Format, used to format and parse monetary values.
`int`	`getRoundingMode()` Returns the Rounding Mode.
`BigDecimal`	`getValue()` Returns the monetary value as a BigDecimal object.
`int`	`hashCode()` Returns a hashcode for this object.
`boolean`	`isEqual(Money other)` Returns an indication of whether or not this monetary value is equal to another monetary value.
`boolean`	`isGreaterThan(Money other)` Returns an indication of whether or not this monetary value is greater than another monetary value.
`boolean`	`isGreaterThanOrEqual(Money other)` Returns an indication of whether or not this monetary value is greater than or equal to another monetary value.
`boolean`	`isLessThan(Money other)` Returns an indication of whether or not this monetary value is less than another monetary value.
`boolean`	`isLessThanOrEqual(Money other)` Returns an indication of whether or not this monetary value is less than or equal to another monetary value.
`boolean`	`isNegative()` Returns an indication of whether or not this monetary value is negative (less than $0.00).
`boolean`	`isPositive()` Returns an indication of whether or not this monetary value is positive (greater than or equal to $0.00).
`boolean`	`isZero()` Returns an indication of whether or not this monetary value is zero (equal to $0.00).
`Money`	`multiply(double mult)` Multiplies this monetary value by a specified value.
`Money`	`multiply(long mult)` Multiplies this monetary value by a specified value.
`Money`	`negate()` Negates this monetary value.
`Money`	`parse(String string)` Parses a string representation of a monetary value, returning a new Money object with the specified value.
`Money`	`setCurrencyFormat(DecimalFormat format)` Sets the Currency Format, used for formatting and parsing monetary values.
`Money`	`setRoundingMode(int mode)` Sets the Rounding Mode.
`Money`	`subtract(Money money)` Subtracts a specified monetary value from this monetary value.
`double`	`toDouble()` Returns the monetary value as a double-precision, floating-point value.
`long`	`toLong()` Returns the monetary value as a long integer with 2 decimal digits to the right of an implicit decimal point.
`String`	`toString()` Returns a formatted string representation of the monetary value.

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

- Field Detail
  - value
```
protected BigDecimal value
```
    The monetary value.
  - roundingMode
```
protected int roundingMode
```
    The Rounding Mode. Specifies if and how the monetary value is to be rounded off to an integral cent.
  - currencyFormat
```
protected DecimalFormat currencyFormat
```
    The Currency Format, used for formatting and parsing a monetary value. Refer to the Java API documentation for the DecimalFormat class for information on formats.
  - ZERO
```
protected static final BigDecimal ZERO
```
    The special monetary value of zero ($0.00).
- Constructor Detail
  - Money
```
public Money()
```
    Default Constructor for a Money object; creates an object whose value is $0.00.
  - Money
```
public Money(double amount)
```
    Constructs a Money object from a double-precision, floating-point value. The Currency Format is set to the default format for the current locale.
    The integral part of the value represents whole dollars, and the fractional part of the value represents fractional dollars (cents). As an example, the value 19.95 would represent $19.95.
    
    Parameters:
    
    amount - The monetary amount, in dollars and cents
  - Money
```
public Money(long amount)
```
    Constructs a Money object from a long integer value. The specified value represents whole dollars only (that is, cents are implicity assumed to be 00). For example, the integer 25 would represent a monetary value of $25.00.
    
    Parameters:
    
    amount - The monetary amount, in whole dollars (no cents)
  - Money
```
public Money(long amount,
             int scale)
      throws Money.InvalidScaleFactorException
```
    Constructs a Money object from a long integer value with a specified scale factor. The scale factor (0, 1, or 2) specifies the number of digits to the right of an implied decimal point.
    For example, the value 1995 would be interpreted as a monetary value of $1995.00, $199.50, and $19.95 for scale factors of 0, 1, or 2, respectively.
    
    Parameters:
    
    amount - The monetary amount, in dollars and cents
    
    scale - Scale factor (must be 0, 1, or 2)
    
    Throws:
    
    Money.InvalidScaleFactorException - The scale factor specified is not valid (must be 0, 1, or 2)
  - Money
```
public Money(String string)
      throws ParseException
```
    Constructs a Money object from a string representation of a monetary value. The format of the string must be consistent with the Currency Format; otherwise, a ParseException is recognized. Refer to the Java API documentation for the DecimalFormat class for information on Decimal Formats in general, and Currency Formats in particular.
    
    Parameters:
    
    string - A String representing a monetary value
    
    Throws:
    
    ParseException - The string is inconsistent with the Currency Format
    
    See Also:
    
    DecimalFormat, setCurrencyFormat(java.text.DecimalFormat)
  - Money
```
public Money(BigDecimal amount)
```
    Constructs a Money object from a BigDecimal object.
    
    Parameters:
    
    amount - A BigDecimal value representing a monetary amount, in dollars and cents
  - Money
```
public Money(Money amount)
```
    Copy Constructor; constructs a Money object from another Money object.
    
    Parameters:
    
    amount - A Money object
- Method Detail
  - add
```
public Money add(Money money)
```
    Adds a specified monetary value to this monetary value.
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Parameters:
    
    money - The monetary value to be added
    
    Returns:
    
    A new Money object representing the result
  - subtract
```
public Money subtract(Money money)
```
    Subtracts a specified monetary value from this monetary value.
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Parameters:
    
    money - The monetary value to be subtracted
    
    Returns:
    
    A new Money object representing the result
  - multiply
```
public Money multiply(double mult)
```
    Multiplies this monetary value by a specified value.
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Parameters:
    
    mult - The multiplier value
    
    Returns:
    
    A new Money object representing the result
  - multiply
```
public Money multiply(long mult)
```
    Multiplies this monetary value by a specified value.
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Parameters:
    
    mult - The multiplier value
    
    Returns:
    
    A new Money object representing the result
  - divide
```
public Money divide(double div)
```
    Divides this monetary value by a specified value.
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Parameters:
    
    div - The divisor value
    
    Returns:
    
    A new Money object representing the result
  - divide
```
public Money divide(long div)
```
    Divides this monetary value by a specified value.
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Parameters:
    
    div - The divisor value
    
    Returns:
    
    A new Money object representing the result
  - negate
```
public Money negate()
```
    Negates this monetary value. Positive values become negative, and negative values become positive. The effect is the same as if the monetary value were multiplied by -1.
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Returns:
    
    A new Money object representing the result
  - abs
```
public Money abs()
```
    Returns the absolute monetary value. A positive value is returned, irrespective of whether the monetary value is positive or negative.
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Returns:
    
    A new Money object representing the result
  - toLong
```
public long toLong()
```
    Returns the monetary value as a long integer with 2 decimal digits to the right of an implicit decimal point. For example, if the monetary value were $19.95, a value of 1995 would be returned. Note that the monetary value is rounded, if necessary, according to the specified Rounding Mode.
    
    Returns:
    
    The monetary value
  - toDouble
```
public double toDouble()
```
    Returns the monetary value as a double-precision, floating-point value.
    Note: Exercise care when converting monetary values to floating point values, because floating-point arithmetic is not well-suited for use with monetary data.
    
    Returns:
    
    The monetary value
  - getValue
```
public BigDecimal getValue()
```
    Returns the monetary value as a BigDecimal object.
    
    Returns:
    
    The monetary value
  - getRoundingMode
```
public int getRoundingMode()
```
    Returns the Rounding Mode. Refer to Java's BigDecimal object for a description of the possible rounding modes.
    
    Returns:
    
    The Rounding Mode
    
    See Also:
    
    BigDecimal.ROUND_UP, BigDecimal.ROUND_DOWN, BigDecimal.ROUND_CEILING, BigDecimal.ROUND_FLOOR, BigDecimal.ROUND_HALF_UP, BigDecimal.ROUND_HALF_DOWN, BigDecimal.ROUND_HALF_EVEN
  - setRoundingMode
```
public Money setRoundingMode(int mode)
                      throws Money.InvalidRoundingModeException
```
    Sets the Rounding Mode. Refer to the Java API documentation for the BigDecimal class for a description of the possible Rounding Modes. The default Rounding Mode is BigDecimal.ROUND_DOWN, which effectively discards any fractional cent amount and truncates the monetary value to 2 decimal places. A Rounding Mode of BigDecimal.ROUND_UNNECESSARY is not valid for use with monetary data since certain operations result in a loss of precision and therefore require that a rounding mode be explicitly specified.
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Parameters:
    
    int - The Rounding Mode
    
    Returns:
    
    A new Money object representing the result
    
    Throws:
    
    Money.InvalidRoundingModeException - The Rounding Mode specified is not valid for monetary data
    
    See Also:
    
    BigDecimal.ROUND_UP, BigDecimal.ROUND_DOWN, BigDecimal.ROUND_CEILING, BigDecimal.ROUND_FLOOR, BigDecimal.ROUND_HALF_UP, BigDecimal.ROUND_HALF_DOWN, BigDecimal.ROUND_HALF_EVEN
  - getCurrencyFormat
```
public DecimalFormat getCurrencyFormat()
```
    Returns the Currency Format, used to format and parse monetary values. Refer to the Java API documentation for the DecimalFormat class for information on Decimal Formats in general, and Currency Formats in particular.
    
    Returns:
    
    The Currency Format
    
    See Also:
    
    DecimalFormat
  - setCurrencyFormat
```
public Money setCurrencyFormat(DecimalFormat format)
```
    Sets the Currency Format, used for formatting and parsing monetary values. Refer to the Java API documentation for the DecimalFormat class for information on Decimal Formats in general, and Currency Formats in particular.
    By default, the Currency Format for the current locale is used. For the United States, the default Currency Symbol is the Dollar Sign ("$"). Negative amounts are enclosed in parentheses. A Decimal Point (".") separates the dollars and cents, and a comma (",") separates each group of 3 consecutive digits in the dollar amount.
    
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Parameters:
    
    format - The Currency Format
    
    Returns:
    
    A new Money object representing the result
    
    See Also:
    
    DecimalFormat
  - toString
```
public String toString()
```
    Returns a formatted string representation of the monetary value. The format of the string is determined by the Currency Format. Refer to the Java API documentation for the DecimalFormat class for information on Decimal Formats in general, and Currency Formats in particular.
    By default, the Currency Format for the current locale is used.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    A string representation of the monetary value
    
    See Also:
    
    DecimalFormat, setCurrencyFormat(java.text.DecimalFormat)
  - parse
```
public Money parse(String string)
            throws ParseException
```
    Parses a string representation of a monetary value, returning a new Money object with the specified value. The format of the string must be consistent with the Currency Format; otherwise, a ParseException is recognized. Refer to the Java API documentation for the DecimalFormat class for information on Decimal Formats in general, and Currency Formats in particular.
    The value of this object is not affected in any way. A new object is returned reflecting the result of the operation.
    
    Parameters:
    
    string - A String representing a monetary value
    
    Returns:
    
    A new Money object representating the parsed monetary value
    
    Throws:
    
    ParseException - The string is inconsistent with the Currency Format
    
    See Also:
    
    DecimalFormat, setCurrencyFormat(java.text.DecimalFormat)
  - isZero
```
public boolean isZero()
```
    Returns an indication of whether or not this monetary value is zero (equal to $0.00).
    
    Returns:
    
    true The monetary value is zero
    false The monetary value is not zero
  - isNegative
```
public boolean isNegative()
```
    Returns an indication of whether or not this monetary value is negative (less than $0.00).
    
    Returns:
    
    true The monetary value is negative
    false The monetary value is not negative
  - isPositive
```
public boolean isPositive()
```
    Returns an indication of whether or not this monetary value is positive (greater than or equal to $0.00).
    
    Returns:
    
    true The monetary value is positive
    false The monetary value is not positive
  - isEqual
```
public boolean isEqual(Money other)
```
    Returns an indication of whether or not this monetary value is equal to another monetary value.
    
    Parameters:
    
    other - A monetary value with which this monetary value is to be compared
    
    Returns:
    
    true This monetary values are equal
    false This monetary values are not equal
  - isLessThan
```
public boolean isLessThan(Money other)
```
    Returns an indication of whether or not this monetary value is less than another monetary value.
    
    Parameters:
    
    other - A monetary value with which this monetary value is to be compared
    
    Returns:
    
    true This monetary value is less than the specified monetary value
    false This monetary value is not less than the specified monetary value
  - isLessThanOrEqual
```
public boolean isLessThanOrEqual(Money other)
```
    Returns an indication of whether or not this monetary value is less than or equal to another monetary value.
    
    Parameters:
    
    other - A monetary value with which this monetary value is to be compared
    
    Returns:
    
    true This monetary value is less than or equal to the specified monetary value
    false This monetary value is not less than or equal to the specified monetary value
  - isGreaterThan
```
public boolean isGreaterThan(Money other)
```
    Returns an indication of whether or not this monetary value is greater than another monetary value.
    
    Parameters:
    
    other - A monetary value with which this monetary value is to be compared
    
    Returns:
    
    true This monetary value is greater than the specified monetary value
    false This monetary value is not greater than the specified monetary value
  - isGreaterThanOrEqual
```
public boolean isGreaterThanOrEqual(Money other)
```
    Returns an indication of whether or not this monetary value is greater than or equal to another monetary value.
    
    Parameters:
    
    other - A monetary value with which this monetary value is to be compared
    
    Returns:
    
    true This monetary value is greater than or equal to the specified monetary value
    false This monetary value is not greater than or equal to the specified monetary value
  - equals
```
public boolean equals(Object object)
```
    Compares this object with the specified object. The objects are equal if and only if the specified object is not null, is a Money object, and has the same monetary value as this object.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    object - Some object
    
    Returns:
    
    true The objects are equal
    false The objects are not equal
  - hashCode
```
public int hashCode()
```
    Returns a hashcode for this object. The hashcode is identical to that for the BigDecimal object that represents the monetary value.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    The hashcode
  - clone
```
public Object clone()
```
    Clones a Money object. The new object is an exact copy of this object, and inherits the object's monetary value and Currency Format.
    
    Overrides:
    
    clone in class Object
    
    Returns:
    
    Money The cloned object

Class Money

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

value

roundingMode

currencyFormat

ZERO

Constructor Detail

Money

Money

Money

Money

Money

Money

Money

Method Detail

add

subtract

multiply

multiply

divide

divide

negate

abs

toLong

toDouble

getValue

getRoundingMode

setRoundingMode

getCurrencyFormat

setCurrencyFormat

toString

parse

isZero

isNegative

isPositive

isEqual

isLessThan

isLessThanOrEqual

isGreaterThan

isGreaterThanOrEqual

equals

hashCode

clone