SEE ALSO

NAME

Podius::Property::Currency - component property representing currency (ISO 4217)

SYNOPSIS

  $property = new Podius::Property::Currency;

Supposed to be used in the Podius::Component manpage and the Podius::Property manpage module trees only.

DESCRIPTION

This module implements component property allowing easy representation of currency as described in ISO 4217.

This property derives from Selection and has all its features. Additionally, there is an option to convert certain amount from/to the current currency to/from another one (if possible) and make other currency manipulations.

Note, that for get_conversion_rate, convert_amount_to_currency and convert_amount_from_currency methods to work, there is a need in CurrencyRates.pl that contains the hashref of conversion rates for the corresponding currency codes. You may use a cronjob to update this file using shipped generate-currency-rates or similar script.

The currency code (available by access or access_code methods) is a 3 english letter string, like ``USD'' or ``EUR''.

Only the methods different from the Podius::Property::Selecion manpage are described here.

REQUIREMENTS

the Podius::Property::Selection manpage, the Exception manpage.

METHODS

get_conversion_rate

description

Returns a conversion rate for the current (or other specified) currency. If the rate for the currency is not found, then exception is thrown.

Usually the semantics of the returned number is the units of the currency per one dollar, but the rate may be based on a different currency as well.

parameters

  * optional other currency (property or code)

returns

Conversion rate (number).

access_sign

description: Only accessor form is available.; Returns the assigned currenct sign, like ``$'' or euro-sign. Usually this is one unicode chars or abbreviature.
returns: String (in utf-8).

access_label

description: Only accessor form is available.; Returns the assigned currenct label, like ``US Dollar'' or ``Euro''. This label may contain unicode chars for certain currencies.
returns: String (in utf-8).

convert_amount_to_currency

description

Returns the amount converted to another currency and formatted. By default the precision is currency-dependent, this is usually 2 digits after the point for most of the world currencies, but may be 0 or 3 for certain currencies. It is possible to disable formatting or force the custom precision.

It is possible to make adjustment to the base amount (relative or absolute, or even replace it) by passing the corresponding parameter. Pass any false value to disable adjustment. See examples.

parameters

  * base amount
  * other currency (property or code)
  * adjustment (+X, -X, +X%, -X%, X, or undef/"" to disable)
  * precision (0..8 - force, 9 - as-is, undef/"" - use actual sub-units)

returns

Converted and formatted amount (floating number).

convert_amount_from_currency

description: See the description of convert_amount_to_currency, this method is almost identical, except that the amount is converted to the current currency and not from the current currency.

format_amount

description

See the description of convert_amount_to_currency, this method is just a shortcut to convert_amount_to_currency(amount, undef, adjustment, precision), so no currency conversion is done.

parameters

  * amount to format
  * adjustment (+X, -X, +X%, -X%, X, or undef/"" to disable)
  * precision (0..8 - force, 9 - as-is, undef/"" - use actual sub-units)

returns

Formatted amount (floating number).