Amount
Keywords: net.corda.core.contracts.Amount class
Date: 2023-09-18

net.corda.core.contracts

## Class Amount<T>

- net.corda.core.contracts.Amount<T>

- Type Parameters:
    `T` -

    the type of the token, for example Currency. T should implement `interface TokenizableAssetInfo` if automatic conversion to/from a display format is required.

      public class Amount<T>

  Amount represents a positive quantity of some token (currency, asset, etc.), measured in quantity of the smallest representable units. The nominal quantity represented by each individual token is equal to the displayTokenSize. The scale property of the displayTokenSize should correctly reflect the displayed decimal places and is used when rounding conversions from indicative/displayed amounts in BigDecimal to Amount occur via the `Amount.fromDecimal` method.

  Amounts of different tokens do not mix and attempting to add or subtract two amounts of different currencies will throw IllegalArgumentException. Amounts may not be negative. Amounts are represented internally using a signed 64 bit value, therefore, the maximum expressable amount is 2^63 - 1 == Long.MAX_VALUE. Addition, subtraction and multiplication are overflow checked and will throw ArithmeticException if the operation would have caused integer overflow.

  See Also:
    BigDecimal, `Amount.fromDecimal`, IllegalArgumentException, ArithmeticException

- - ### Field Detail

    - #### Companion

          public static net.corda.core.contracts.Amount.Companion Companion

  - ### Constructor Detail

    - #### Amount

          public Amount(long quantity,
                        @NotNull
                        java.math.BigDecimal displayTokenSize,
                        @NotNull
                        T token)

      Amount represents a positive quantity of some token (currency, asset, etc.), measured in quantity of the smallest representable units. The nominal quantity represented by each individual token is equal to the displayTokenSize. The scale property of the displayTokenSize should correctly reflect the displayed decimal places and is used when rounding conversions from indicative/displayed amounts in BigDecimal to Amount occur via the `Amount.fromDecimal` method.

      Amounts of different tokens do not mix and attempting to add or subtract two amounts of different currencies will throw IllegalArgumentException. Amounts may not be negative. Amounts are represented internally using a signed 64 bit value, therefore, the maximum expressable amount is 2^63 - 1 == Long.MAX_VALUE. Addition, subtraction and multiplication are overflow checked and will throw ArithmeticException if the operation would have caused integer overflow.

      Parameters:
        `quantity` - the number of tokens as a long value.
        `displayTokenSize` - the nominal display unit size of a single token, potentially with trailing decimal displayplaces if the scale parameter is non-zero.
        `token` - the type of token this is an amount of. This is usually a singleton.
      See Also:
        BigDecimal, `Amount.fromDecimal`, IllegalArgumentException, ArithmeticException

    - #### Amount

          public Amount(long tokenQuantity,
                        @NotNull
                        T token)

      Automatic conversion constructor from number of tokens to an Amount using getDisplayTokenSize to determine the displayTokenSize.

      Parameters:
        `tokenQuantity` - the number of tokens represented.
        `token` - the type of the token, for example a Currency object.

  - ### Method Detail

    - #### plus

          @NotNull
          public Amount<T> plus(@NotNull
                                         Amount<T> other)

      A checked addition operator is supported to simplify aggregation of Amounts. Mixing non-identical token types will throw IllegalArgumentException.

      Throws:
        `ArithmeticException` - if there is overflow of Amount tokens during the summation
        `IllegalArgumentException` - if mixing non-identical token types.
      See Also:
        IllegalArgumentException

    - #### minus

          @NotNull
          public Amount<T> minus(@NotNull
                                          Amount<T> other)

      A checked subtraction operator is supported to simplify netting of Amounts.

      Throws:
        `ArithmeticException` - if there is numeric underflow.
        `IllegalArgumentException` - if this leads to the amount going negative, or would mix non-identical token types.

    - #### times

          @NotNull
          public Amount<T> times(long other)

      The multiplication operator is supported to allow easy calculation for multiples of a primitive Amount. Note this is not a conserving operation, so it may not always be correct modelling of proper token behaviour. N.B. Division is not supported as fractional tokens are not representable by an Amount.

      Throws:
        `ArithmeticException` - if there is overflow of Amount tokens during the multiplication.

    - #### times

          @NotNull
          public Amount<T> times(int other)

      The multiplication operator is supported to allow easy calculation for multiples of a primitive Amount. Note this is not a conserving operation, so it may not always be correct modelling of proper token behaviour. N.B. Division is not supported as fractional tokens are not representable by an Amount.

      Throws:
        `ArithmeticException` - if there is overflow of Amount tokens during the multiplication.

    - #### splitEvenly

          @NotNull
          public java.util.List<net.corda.core.contracts.Amount> splitEvenly(int partitions)

      This method provides a token conserving divide mechanism.

      Parameters:
        `partitions` - the number of amounts to divide the current quantity into.
      Returns:
        'partitions' separate Amount objects which sum to the same quantity as this Amount and differ by no more than a single token in size.

    - #### toDecimal

          @NotNull
          public java.math.BigDecimal toDecimal()

      Convert a currency `class Amount` to a decimal representation. For example, with an amount with a quantity of "1234" GBP, returns "12.34". The precise representation is controlled by the display token size ( from `getDisplayTokenSize`), which determines the size of a single token and controls the trailing decimal places via its scale property. Note that currencies such as the Bahraini Dinar use 3 decimal places, and it must not be presumed that this converts amounts to 2 decimal places.

      See Also:
        `class Amount`, `getDisplayTokenSize`, `Amount.fromDecimal`

    - #### toString

          @NotNull
          public java.lang.String toString()

      Convert a currency `class Amount` to a display string representation.

      For example, with an amount with a quantity of "1234" GBP, returns "12.34 GBP". The result of fromDecimal is used to control the numerical formatting and the token specifier appended is taken from token.toString.

      See Also:
        `class Amount`, `Amount.fromDecimal`

    - #### getQuantity

          public long getQuantity()

      the number of tokens as a long value.

    - #### getDisplayTokenSize

          @NotNull
          public java.math.BigDecimal getDisplayTokenSize()

      the nominal display unit size of a single token,

      potentially with trailing decimal displayplaces if the scale parameter is non-zero.

    - #### getToken

          @NotNull
          public T getToken()

      the type of token this is an amount of.

      This is usually a singleton.

    - #### component1

          public long component1()

      the number of tokens as a long value.

    - #### component2

          @NotNull
          public java.math.BigDecimal component2()

      the nominal display unit size of a single token,

      potentially with trailing decimal displayplaces if the scale parameter is non-zero.

    - #### component3

          @NotNull
          public T component3()

      the type of token this is an amount of.

      This is usually a singleton.

    - #### copy

          @NotNull
          public Amount<T> copy(long quantity,
                                         @NotNull
                                         java.math.BigDecimal displayTokenSize,
                                         @NotNull
                                         T token)

      Amount represents a positive quantity of some token (currency, asset, etc.), measured in quantity of the smallest representable units. The nominal quantity represented by each individual token is equal to the displayTokenSize. The scale property of the displayTokenSize should correctly reflect the displayed decimal places and is used when rounding conversions from indicative/displayed amounts in BigDecimal to Amount occur via the `Amount.fromDecimal` method.

      Amounts of different tokens do not mix and attempting to add or subtract two amounts of different currencies will throw IllegalArgumentException. Amounts may not be negative. Amounts are represented internally using a signed 64 bit value, therefore, the maximum expressable amount is 2^63 - 1 == Long.MAX_VALUE. Addition, subtraction and multiplication are overflow checked and will throw ArithmeticException if the operation would have caused integer overflow.

      See Also:
        BigDecimal, `Amount.fromDecimal`, IllegalArgumentException, ArithmeticException

    - #### hashCode

          public int hashCode()

      Amount represents a positive quantity of some token (currency, asset, etc.), measured in quantity of the smallest representable units. The nominal quantity represented by each individual token is equal to the displayTokenSize. The scale property of the displayTokenSize should correctly reflect the displayed decimal places and is used when rounding conversions from indicative/displayed amounts in BigDecimal to Amount occur via the `Amount.fromDecimal` method.

      Amounts of different tokens do not mix and attempting to add or subtract two amounts of different currencies will throw IllegalArgumentException. Amounts may not be negative. Amounts are represented internally using a signed 64 bit value, therefore, the maximum expressable amount is 2^63 - 1 == Long.MAX_VALUE. Addition, subtraction and multiplication are overflow checked and will throw ArithmeticException if the operation would have caused integer overflow.

      See Also:
        BigDecimal, `Amount.fromDecimal`, IllegalArgumentException, ArithmeticException

    - #### equals

          public boolean equals(@Nullable
                                java.lang.Object p)

      Amount represents a positive quantity of some token (currency, asset, etc.), measured in quantity of the smallest representable units. The nominal quantity represented by each individual token is equal to the displayTokenSize. The scale property of the displayTokenSize should correctly reflect the displayed decimal places and is used when rounding conversions from indicative/displayed amounts in BigDecimal to Amount occur via the `Amount.fromDecimal` method.

      Amounts of different tokens do not mix and attempting to add or subtract two amounts of different currencies will throw IllegalArgumentException. Amounts may not be negative. Amounts are represented internally using a signed 64 bit value, therefore, the maximum expressable amount is 2^63 - 1 == Long.MAX_VALUE. Addition, subtraction and multiplication are overflow checked and will throw ArithmeticException if the operation would have caused integer overflow.

      See Also:
        BigDecimal, `Amount.fromDecimal`, IllegalArgumentException, ArithmeticException

    - #### fromDecimal

          @JvmStatic
           @JvmOverloads
           @NotNull
          public static <T> Amount<T> fromDecimal(@NotNull
                                                                                      java.math.BigDecimal displayQuantity,
                                                                                      @NotNull
                                                                                      T token,
                                                                                      @NotNull
                                                                                      java.math.RoundingMode rounding)

      Build an Amount from a decimal representation. For example, with an input of "12.34 GBP", returns an amount with a quantity of "1234" tokens. The function `getDisplayTokenSize` is used to determine the conversion scaling, for example bonds might be in nominal amounts of 100, currencies in 0.01 penny units.

      Throws:
        `ArithmeticException` - if the intermediate calculations cannot be converted to an unsigned 63-bit token amount.
      See Also:
        `getDisplayTokenSize`, `Amount.toDecimal`

    - #### fromDecimal

          @JvmStatic
           @JvmOverloads
           @NotNull
          public static <T> Amount<T> fromDecimal(@NotNull
                                                                                      java.math.BigDecimal displayQuantity,
                                                                                      @NotNull
                                                                                      T token)

      Build an Amount from a decimal representation. For example, with an input of "12.34 GBP", returns an amount with a quantity of "1234" tokens. The function `getDisplayTokenSize` is used to determine the conversion scaling, for example bonds might be in nominal amounts of 100, currencies in 0.01 penny units.

      Throws:
        `ArithmeticException` - if the intermediate calculations cannot be converted to an unsigned 63-bit token amount.
      See Also:
        `getDisplayTokenSize`, `Amount.toDecimal`

    - #### zero

          @JvmStatic
           @NotNull
          public static <T> Amount<T> zero(@NotNull
                                                                T token)

      For a particular token returns a zero sized Amount

    - #### getDisplayTokenSize

          @JvmStatic
           @NotNull
          public static java.math.BigDecimal getDisplayTokenSize(@NotNull
                                                                                      java.lang.Object token)

      Determines the representation of one Token quantity in BigDecimal. For Currency and Issued the definitions is taken from Currency defaultFractionDigits property e.g. 2 for USD, or 0 for JPY so that the automatic token size is the conventional minimum penny amount. For other possible token types the asset token should implement TokenizableAssetInfo to correctly report the designed nominal amount.

    - #### sumOrNull

          @JvmStatic
           @Nullable
          public static <T> Amount<T> sumOrNull(@NotNull
                                                                      java.lang.Iterable<net.corda.core.contracts.Amount> $this$sumOrNull)

      If the given iterable of `class Amount`s yields any elements, sum them, throwing an IllegalArgumentException if any of the token types are mismatched; if the iterator yields no elements, return null.

      See Also:
        `class Amount`, IllegalArgumentException

    - #### sumOrThrow

          @JvmStatic
           @NotNull
          public static <T> Amount<T> sumOrThrow(@NotNull
                                                                      java.lang.Iterable<net.corda.core.contracts.Amount> $this$sumOrThrow)

      Sums the amounts yielded by the given iterable, throwing an IllegalArgumentException if any of the token types are mismatched.

      See Also:
        IllegalArgumentException

    - #### sumOrZero

          @JvmStatic
           @NotNull
          public static <T> Amount<T> sumOrZero(@NotNull
                                                                     java.lang.Iterable<net.corda.core.contracts.Amount> $this$sumOrZero,
                                                                     @NotNull
                                                                     T token)

      If the given iterable of `class Amount`s yields any elements, sum them, throwing an IllegalArgumentException if any of the token types are mismatched; if the iterator yields no elements, return a zero amount of the given token type.

      See Also:
        `class Amount`, IllegalArgumentException

    - #### parseCurrency

          @JvmStatic
           @NotNull
          public static Amount<java.util.Currency> parseCurrency(@NotNull
                                                                                      java.lang.String input)

      Returns an amount that is equal to the given currency amount in text. Examples of what is supported:

      - 12 USD

      - 14.50 USD

      - 10 USD

      - 30 CHF

      - $10.24

      - £13

      - €5000

      Note this method does NOT respect internationalisation rules: it ignores commas and uses . as the decimal point separator, always. It also ignores the users locale:

      - $ is always USD,

      - £ is always GBP

      - € is always the Euro

      - ¥ is always Japanese Yen.

      - ₽ is always the Russian ruble.

      Thus an input of $12 expecting some other countries dollar will not work. Do your own parsing if you need correct handling of currency amounts with locale-sensitive handling.

      Throws:
        `IllegalArgumentException` - if the input string was not understood.