Amount - corda

corda / net.corda.core.contracts / Amount

# Amount

`data class Amount<T : Any> : Comparable<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.

### Constructors

#### <init> | Automatic conversion constructor from number of tokens to an Amount using getDisplayTokenSize to determine the displayTokenSize. `Amount(tokenQuantity: Long, token: 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. `Amount(quantity: Long, displayTokenSize: BigDecimal, token: T)`

### Properties

#### displayTokenSize | the nominal display unit size of a single token, potentially with trailing decimal display places if the scale parameter is non-zero. `val displayTokenSize: BigDecimal`
#### quantity | the number of tokens as a long value. `val quantity: Long`
#### token | the type of token this is an amount of. This is usually a singleton. `val token: T`

### Functions

#### minus | A checked subtraction operator is supported to simplify netting of Amounts. `operator fun minus(other: Amount<T>): Amount<T>`
#### plus | A checked addition operator is supported to simplify aggregation of Amounts. Mixing non-identical token types will throw IllegalArgumentException. `operator fun plus(other: Amount<T>): Amount<T>`
#### splitEvenly | This method provides a token conserving divide mechanism. `fun splitEvenly(partitions: Int): List<Amount<T>>`
#### times | 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. `operator fun times(other: Long): Amount<T>` `operator fun times(other: Int): Amount<T>`
#### toDecimal | Convert a currency 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. `fun toDecimal(): BigDecimal`
#### toString | Convert a currency Amount to a display string representation. `fun toString(): String`

### Companion Object Functions

#### fromDecimal | 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. `fun <T : Any> fromDecimal(displayQuantity: BigDecimal, token: T, rounding: RoundingMode = RoundingMode.FLOOR): Amount<T>`
#### getDisplayTokenSize | 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. `fun getDisplayTokenSize(token: Any): BigDecimal`
#### parseCurrency | Returns an amount that is equal to the given currency amount in text. Examples of what is supported: `fun parseCurrency(input: String): Amount<Currency>`
#### sumOrNull | If the given iterable of Amounts yields any elements, sum them, throwing an IllegalArgumentException if any of the token types are mismatched; if the iterator yields no elements, return null. `fun <T : Any> Iterable<Amount<T>>.sumOrNull(): Amount<T>?`
#### sumOrThrow | Sums the amounts yielded by the given iterable, throwing an IllegalArgumentException if any of the token types are mismatched. `fun <T : Any> Iterable<Amount<T>>.sumOrThrow(): Amount<T>`
#### sumOrZero | If the given iterable of Amounts 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. `fun <T : Any> Iterable<Amount<T>>.sumOrZero(token: T): Amount<T>`
#### zero | For a particular token returns a zero sized Amount `fun <T : Any> zero(token: T): Amount<T>`

### Extension Properties

#### CASH | An extension property that lets you write 100.DOLLARS.CASH `val Amount<Currency>.CASH: State`
#### STATE | An extension property that lets you get a cash state from an issued token, under the NULL_PARTY `val Amount<Issued<Currency>>.STATE: State`

### Extension Functions

#### issued by | `infix fun Amount<Currency>.issued by(deposit: PartyAndReference): Amount<Issued<Currency>>`
#### issuedBy | `infix fun Amount<Currency>.issuedBy(deposit: PartyAndReference): Amount<Issued<Currency>>`
#### withoutIssuer | Strips the issuer and returns an Amount of the raw token directly. This is useful when you are mixing code that cares about specific issuers with code that will accept any, or which is imposing issuer constraints via some other mechanism and the additional type safety is not wanted. `fun <T : Any> Amount<Issued<T>>.withoutIssuer(): Amount<T>`