Generated with

Money

world.money.Money

See theMoney companion class

object Money

Provides factory methods for creating Money instances

Attributes

Companion: class
Graph
Supertypes: class Object

trait Matchable

class Any
Self type: Money.type

Members list

Value members

Concrete methods

Creates a Money[C] instance from a numeric value in a generic context.

Type parameters

C: The type of the Currency. (e.g Currencies.KES)

Value parameters

value: The numeric value of the amount.

Attributes

Note: The currency C is inferred from the context via a using ValueOf[C] parameter. For creating amounts of a concrete, known currency, the currency-specific syntax (e.g., 100.KES) is preferred as it is more readable.

Using Double for financial calculations is strongly discouraged due to potential precision inaccuracies.

Creates a Money instance from a runtime currency value.

This factory is useful when the currency is not known at compile time (e.g., when deserializing data or creating amounts from user input). The returned type is an existential Money[? <: Currency] because the specific currency type C cannot be known by the compiler.

Value parameters

currency: The runtime currency object.
value: The numeric amount.

Attributes

Returns: A Money instance with an existential currency type.

Creates a Money instance with an amount of zero for the given currency.

Type parameters

C: The type of the currency (e.g Currencies.KES).

Attributes

Givens

Provides a given Ordering instance for Money[C] instances.

Attributes

Extensions

extension [C <: Currency](amounts: Iterable[Money[C]])

Computes the arithmetic mean of all monetary amounts.

Returns None if the collection is empty.

Attributes

Returns: Some(average) if non-empty, None otherwise.
Note: Requires a CurrencyMathContext for division operations.

Sums all monetary amounts in the collection.

Returns Money.zero[C] if the collection is empty.

Attributes

Returns: The sum of all amounts, or zero if empty.
Note: Requires a ValueOf[C] to construct the zero value and a CurrencyMathContext for arithmetic operations.

extension [C <: Currency](self: Money[C])(using valueOf: ValueOf[C])

Multiplies this Money amount by a scalar value. Requires a given instance of world.money.currency.CurrencyMathContext.

Attributes

Note: Using Double can lead to precision inaccuracies.

Adds another value to this Money instance. Requires a given instance of world.money.currency.CurrencyMathContext.

Value parameters

augend: The value to add.

Attributes

Returns: A new Money instance representing the sum.
Note: The value to be added must either be another Money instance of the same currency, or a raw numeric type.

Using Double can lead to precision inaccuracies.

Subtracts the value of subtrahend from this Money instance. Requires a given instance of world.money.currency.CurrencyMathContext.

Value parameters

subtrahend: The value to subtract.

Attributes

Returns: A new Money instance representing the difference.
Note: The value to be subtracted must either be another Money instance of the same currency, or a raw numeric type.

Using Double can lead to precision inaccuracies.

Attempts to divide this Money amount by a scalar value. Requires a given instance of world.money.currency.CurrencyMathContext.

Attributes

Returns: An Either containing a errors.ArithmeticError on failure (e.g., division by zero), or the resulting Money instance.
Note: Using Double can lead to precision inaccuracies.

Returns the absolute value of this amount.

Attributes

Adds the value of augend to this Money instance. Requires a given instance of world.money.currency.CurrencyMathContext.

Value parameters

augend: The value to add.

Attributes

Returns: A new Money instance representing the sum.
Note: The value to be added must either be another Money instance of the same currency, or a raw numeric type.

Using Double can lead to precision inaccuracies.

Allocates this money amount proportionally according to the given ratios.

This method divides the total amount among multiple parts based on their relative proportions, handling any remainder by distributing it to the first portions. This ensures that the sum of allocated amounts equals the original amount exactly.

Common use cases include:

Splitting bills among multiple parties
Distributing tax amounts across line items
Allocating revenue shares

Value parameters

context: The math context for division operations.
ratios: A sequence of positive BigDecimal values representing relative proportions. Ratios need not sum to 1; they are normalized internally.

Attributes

Returns

A sequence of Money amounts proportional to the ratios, or an ArithmeticError if allocation fails (e.g., empty ratios, negative ratios, or division errors).

Example

import world.money.*
val total = 100.USD
// Split 100 USD in ratio 3:2:1 (50 USD, 33.33 USD, 16.67 USD)
val shares = total.allocate(Seq(3, 2, 1))

Compares this Money instance to another of the same currency.

Attributes

Converts this monetary amount to another currency.

This is the primary method for handling currency conversions. It requires a given world.money.conversion.ExchangeRateProvider to be available in the implicit scope, which is responsible for supplying the necessary conversion rate.

Type parameters

T: The singleton type of the target currency.

Value parameters

provider: An world.money.conversion.ExchangeRateProvider instance that supplies exchange rates for currency conversion.
target: A ValueOf instance for the target currency type T, provided automatically by the compiler.

Attributes

Returns

Right with a Money[T] instance containing the converted amount on success, or Left with an world.money.errors.ConversionError on failure.

Example

import world.money.*
import world.money.conversion.*
import world.money.currency.{Currencies, CurrencyValue}
import world.money.errors.ConversionError
val tenShillings = 10.KES
// A simple mock provider for the example
given mockProvider: ExchangeRateProvider with
def get(query: ConversionQuery): Either[ConversionError, ConversionRate] =
if (query.base == Currencies.KES && query.term == Currencies.JPY)
Right(ConversionRate(Currencies.KES, Currencies.JPY, BigDecimal("10.50")))
else
Left(ConversionError.RateNotFound(query))
// The target currency type is specified
val conversionResult = tenShillings.convertTo[Currencies.JPY.type]
conversionResult.foreach { jpyAmount =>
// The result is correctly typed as Money[Currencies.JPY.type]
assert(jpyAmount.value.unwrap == CurrencyValue(105.0).unwrap)
}

Attempts to divide this Money amount by a scalar value. Requires a given instance of world.money.currency.CurrencyMathContext.

Attributes

Returns: An Either containing a errors.ArithmeticError on failure (e.g., division by zero), or the resulting Money instance.
Note: Using Double can lead to precision inaccuracies.

Returns the maximum of this amount and another.

Value parameters

that: The other money amount to compare.

Attributes

Returns: The money amount with the larger value.

Returns the minimum of this amount and another.

Value parameters

that: The other money amount to compare.

Attributes

Returns: The money amount with the smaller value.

Multiplies this Money amount by a scalar value. Requires a given instance of world.money.currency.CurrencyMathContext.

Attributes

Note: Using Double can lead to precision inaccuracies.

Returns a Money instance with its value rounded to the currency's conventional number of fractional digits.

This is useful for preparing a monetary amount for final representation or payment, adhering to the standard format of its currency.

Attributes

Returns

A new Money instance with the rounded value.

Note

This method uses RoundingMode.HALF_UP. For currencies without a defined minorUnit (e.g., precious metals like Gold), this operation has no effect and returns the instance unchanged.

Example

import world.money.*
val unrounded = 123.456.KES // KES has 2 minor units
val rounded = unrounded.rounded
// rounded is now 123.46.KES
val jpyAmount = 987.5.JPY // JPY has 0 minor units
val roundedJpy = jpyAmount.rounded
// roundedJpy is now 988.JPY

Returns a Money instance with its value rounded to the currency's conventional number of fractional digits, using a specified rounding mode.

This method allows for explicit control over how rounding is performed, which is essential for financial applications that must comply with specific rounding rules.

Value parameters

mode: The RoundingMode to apply.

Attributes

Returns

A new Money instance with the rounded value.

Note

For currencies without a defined minorUnit (e.g., precious metals), this operation has no effect and returns the instance unchanged.

Example

import world.money.*
import scala.math.BigDecimal.RoundingMode
val amount = 123.456.KES
// Explicitly round down
val roundedDown = amount.rounded(RoundingMode.DOWN)
// roundedDown is now 123.45.KES
// Explicitly round up
val roundedUp = amount.rounded(RoundingMode.UP)
// roundedUp is now 123.46.KES

Returns the sign of this amount's value (-1, 0, or 1).

Attributes

Subtracts the value of subtrahend from this Money instance. Requires a given instance of world.money.currency.CurrencyMathContext.

Value parameters

subtrahend: The value to subtract.

Attributes

Returns: A new Money instance representing the difference.
Note: The value to be subtracted must either be another Money instance of the same currency, or a raw numeric type.

Using Double can lead to precision inaccuracies.

Negates this Money amount.

Attributes

Example

 import world.money.*
-100.KES // Results in Money(-100, KES)

In this article

Generated with