Module org.tquadrat.foundation.value
Package org.tquadrat.foundation.value

Class CurrencyValue

java.lang.Object
org.tquadrat.foundation.value.CurrencyValue
All Implemented Interfaces:
Serializable, Cloneable, Comparable<CurrencyValue>, Formattable
@ClassVersion(sourceVersion="$Id: CurrencyValue.java 1135 2024-05-28 21:32:48Z tquadrat $") @API(status=STABLE, since="0.0.4") public final class CurrencyValue extends Object implements Cloneable, Comparable<CurrencyValue>, Formattable, Serializable

A value type for currency values.

As there is no constant conversion between currencies, this value type is not implementing the interface DimensionedValue.

Author:
Thomas Thrien (thomas.thrien@tquadrat.org)
Version:
$Id: CurrencyValue.java 1135 2024-05-28 21:32:48Z tquadrat $
Since:
0.0.4
See Also:
UML Diagram
UML Diagram for "org.tquadrat.foundation.value.CurrencyValue"⁠

UML Diagram for "org.tquadrat.foundation.value.CurrencyValue"

UML Diagram for "org.tquadrat.foundation.value.CurrencyValue"⁠

  • Field Details

  • Constructor Details

    • CurrencyValue

      public CurrencyValue(Currency unit, BigDecimal value)
      Creates a new CurrencyValue instance.
      Parameters:
      unit - The unit.
      value - The value; only absolute (positive) values are allowed, a sign will be stripped.

    • CurrencyValue

      public CurrencyValue(Currency unit, String value) throws NumberFormatException
      Creates a new CurrencyValue instance.
      Parameters:
      unit - The unit.
      value - The value; it must be possible to parse the given String into a BigDecimal.
      Throws:
      NumberFormatException - The provided value cannot be converted into a BigDecimal.

    • CurrencyValue

      public CurrencyValue(Currency unit, N value)
      Creates a new CurrencyValue instance.
      Type Parameters:
      N - The type of value.
      Parameters:
      unit - The unit.
      value - The value.

  • Method Details

    • baseValue

      public final BigDecimal baseValue()

      Returns the amount.

      Returns:
      The numerical value for this instance of CurrencyValue.

    • clone

      public final CurrencyValue clone()
      Overrides:
      clone in class Object

    • compareTo

      public final int compareTo(CurrencyValue other)
      Specified by:
      compareTo in interface Comparable<CurrencyValue>
      Throws:
      IllegalArgumentException - The currencies for both values are different.

    • copy

      public final CurrencyValue copy()
      Creates a new copy of this value.
      Returns:
      The copy.
      See Also:

    • copy

      public final CurrencyValue copy(Currency unit, BigDecimal conversionFactor)
      Creates a new instance of CurrencyValue for a different Currency.
      Parameters:
      unit - The Currency for the new value.
      conversionFactor - The value for this instance multiplied with the given factor results in the value for the instance.
      Returns:
      The new instance.

    • equals

      public final boolean equals(Object obj)
      Overrides:
      equals in class Object

    • formatTo

      public final void formatTo(Formatter formatter, int flags, int width, int precision)

      The precision is applied to the numerical part only. The width includes the currency symbol, too.

      Specified by:
      formatTo in interface Formattable
      Note:
      • In case the formatter argument is null, this method throws a NullPointerException and not the usual NullArgumentException, because this method is usually called by instances of java.util.Formatter, and those do not know about our special exceptions.
      Throws:
      NullPointerException - The formatter argument is null.
      See Also:

    • getUnit

      public final Currency getUnit()
      Returns the unit for the value.
      Returns:
      The unit.

    • hashCode

      public final int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public final String toString(int width, int precision)

      Provides a String representation of this value, in the format

      <numerical value> <currency symbol>

      and for the default Locale, like "4.50 €", where the Locale determines the decimal separator.

      The precision is applied to the numerical part only. The width includes the currency symbol, too.

      Parameters:
      width - The minimum number of characters to be written to the output. If the length of the converted value is less than the width then the output will be padded by ' ' until the total number of characters equals width. The padding is at the beginning, as numerical values are usually right justified. If width is -1 then there is no minimum.
      precision - – The number of digits for the mantissa of the value. If precision is -1 then there is no explicit limit on the size of the mantissa.
      Returns:
      The String representation for this value.

    • toString

      public final String toString(int width)

      Provides a String representation of this value, in the format

      <numerical value> <currency symbol>

      and for the default Locale, like "4.50 €", where the Locale determines the decimal separator.

      The precision is taken from the currency and applied to the numerical part only. The width includes the currency symbol, too.

      Parameters:
      width - The minimum number of characters to be written to the output. If the length of the converted value is less than the width then the output will be padded by ' ' until the total number of characters equals width. The padding is at the beginning, as numerical values are usually right justified. If width is -1 then there is no minimum.
      Returns:
      The String representation for this value.

    • toString

      public final String toString(Locale locale, int width, int precision)

      Provides a String representation of this value, in the format

      <numerical value> <currency symbol>

      for the given Locale that determines the decimal separator, like "4.50 €" vs. "4,50 €".

      The precision is applied to the numerical part only. The width includes the currency symbol, too.

      Parameters:
      locale - The locale to use.
      width - The minimum number of characters to be written to the output. If the length of the converted value is less than the width then the output will be padded by ' ' until the total number of characters equals width. The padding is at the beginning, as numerical values are usually right justified. If width is -1 then there is no minimum.
      precision - – The number of digits for the mantissa of the value. If precision is -1 then there is no explicit limit on the size of the mantissa.
      Returns:
      The String representation for this value.

    • toString

      public final String toString(Locale locale, int width)

      Provides a String representation of this value, in the format

      <numerical value> <currency symbol>

      for the given Locale that determines the decimal separator, like "4.50 €" vs. "4,50 €".

      The precision is taken from the currency and applied to the numerical part only. The width includes the currency symbol, too.

      Parameters:
      locale - The locale to use.
      width - The minimum number of characters to be written to the output. If the length of the converted value is less than the width then the output will be padded by ' ' until the total number of characters equals width. The padding is at the beginning, as numerical values are usually right justified. If width is -1 then there is no minimum.
      Returns:
      The String representation for this value.

    • toString

      public final String toString(Locale locale, int width, int precision, boolean useNiceUnit)

      Provides a String representation of this value, in the format

      <numerical value> <currency symbol>

      for the given Locale that determines the decimal separator, like "4.50 €" vs. "4,50 €".

      The precision is applied to the numerical part only. The width includes the unit symbol, too.

      Parameters:
      locale - The locale to use.
      width - The minimum number of characters to be written to the output. If the length of the converted value is less than the width then the output will be padded by ' ' until the total number of characters equals width. The padding is at the beginning, as numerical values are usually right justified. If width is -1 then there is no minimum.
      precision - – The number of digits for the mantissa of the value. If precision is -1 then there is no explicit limit on the size of the mantissa.
      useNiceUnit - true if the method unitSymbolForPrinting() should be used to retrieve the unit symbol, false if the usual one is sufficient.
      Returns:
      The String representation for this value.

    • toString

      public final String toString(Locale locale, String format, boolean useNiceUnit) throws IllegalFormatException

      Provides a String representation of this value, in the format that is defined by the provided format String.

      That format String must contain exactly one '%f' tag and one '%s' tag; the first takes the numerical value, the second the unit.

      The provided Locale determines the decimal separator and the optional thousands separator.

      Parameters:
      locale - The locale to use.
      format - The format String.
      useNiceUnit - true if the method unitSymbolForPrinting() should be used to retrieve the unit symbol, false if the usual one is sufficient.
      Returns:
      The String representation for this value.
      Throws:
      IllegalFormatException - The provided format String is invalid.
      See Also:

    • toString

      public final String toString()
      Overrides:
      toString in class Object