Package org.jscience.economics.money

Provides support for monetary quantities and their currencies.

See: Description

Interface Summary

Interface	Description
Money	This interface represents something generally accepted as a medium of exchange, a measure of value, or a means of payment.

Class Summary

Class	Description
Currency	This class represents a currency Unit.

Package org.jscience.economics.money Description

Provides support for monetary quantities and their currencies.

Conversions between quantities stated in different currencies is possible if the exchange rates for the currencies have been set (otherwise ConversionException is thrown).

Monetary quantities support the dynamic changes of the currencies exchange rates as illustrated in the following example:

    import static javax.measure.units.SI.*;
    import static javax.measure.units.NonSI.*;
    import static org.jscience.economics.money.Currency.*;
    
        ///////////////////////////////////////////////////////////////////////
        // Calculates the cost of a car trip in Europe for an American tourist.
        ///////////////////////////////////////////////////////////////////////

        // Use currency symbols instead of ISO-4217 codes.
        UnitFormat.getStandardInstance().label(USD, "$"); // Use "$" symbol instead of currency code ("USD")
        UnitFormat.getStandardInstance().label(EUR, "€"); // Use "€" symbol instead of currency code ("EUR")

        // Sets exchange rates.
        Currency.setReferenceCurrency(USD);
        EUR.setExchangeRate(1.17); // 1.0 € = 1.17 $

        // Calculates trip cost.
        Amount<?> carMileage        = Amount.valueOf(20, MILE.divide(GALLON_LIQUID_US)); // 20 mi/gal.
        Amount<?> gazPrice          = Amount.valueOf(1.2, EUR.divide(LITER)); // 1.2 €/L
        Amount<Length> tripDistance = Amount.valueOf(400, KILO(METRE)); // 400 km
        Amount<Money>  tripCost     = tripDistance.divide(carMileage).times(gazPrice).to(USD);

        // Displays cost.
        System.out.println("Trip cost = " + tripCost + " (" + tripCost.to(EUR) + ")");

    > Trip cost = 66.05 $ (56.45 €)
   

The exchange rates between currencies is context local. Application may use different sets of exchange rates concurrently (e.g. rates for buying and rates for selling). For example:

        LocalContext.enter(); 
        try {
            EUR.setExchangeRate(1.22);  // Buying rate.
            Amount<Money> price = Amount.valueOf(9.99, EUR);
            System.out.println("Price: " + price.to(USD);
        } finally {
            LocalContext.exit();
        }
        ...
        LocalContext.enter(); 
        try {
            EUR.setExchangeRate(1.18);  // Selling rate.
            Amount<Money> price = Amount.valueOf(14.99, USD);
            System.out.println("Price: " + price.to(EUR);
        } finally {
            LocalContext.exit();
        }

Like any amount, money quantities can be exact or approximate (with an error known and guaranteed).

         Unit<Money> CENTS = Currency.USD.times(100);
         Amount<Money> exactPrice = Amount.valueOf(1499, CENTS); // Integer value.
         Amount<Money> apprxPrice = Amount.valueOf(14.99, USD);  // Floating-Point IEEE 754 accuracy.