Description :
*Locale::Currency::Format* is a light-weight Perl module that enables Perl
code to display monetary values in the formats recognized internationally
and/or locally.
* \'currency_format(CODE, AMOUNT [, FORMAT])\'
*currency_format* takes two mandatory parameters, namely currency code
and amount respectively, and optionally a third parameter indicating
which format is desired. Upon failure, it returns _undef_ and an error
message is stored in *$Locale::Currency::Format::error*.
CODE
A 3-letter currency code as specified in ISO 4217.
Note that old code such as DEM, FRF and so on can also
be valid.
AMOUNT
A numeric value.
FORMAT
There are five different format options FMT_STANDARD,
FMT_COMMON, FMT_SYMBOL, FMT_HTML and FMT_NAME. If it is
omitted, the default format is FMT_STANDARD.
FMT_STANDARD Ex: 1,000.00 USD, 1.000.000,00 EUR
FMT_SYMBOL Ex: $1,000.00
FMT_COMMON Ex: 1.000 Dong (Vietnam), BEF 1.000 (Belgium)
FMT_HTML Ex: £1,000.00 (pound-sign HTML escape)
FMT_NAME Ex: 1,000.00 US Dollar
NOTE: By default the trailing zeros after the decimal
point will be added. To turn it off, do a bitwise C< or>
of FMT_NOZEROS with one of the five options above.
Ex: FMT_STANDARD | FMT_NOZEROS will give 1,000 USD
* \'currency_symbol(CODE [, TYPE])\'
For conveniences, the function *currency_symbol* is provided for currency
symbol lookup given a 3-letter currency code. Optionally, one can specify
which format the symbol should be returned - Unicode-based character or
HTML escape. Default is a Unicode-based character. Upon failure, it
returns _undef_ and an error message is stored in
*$Locale::Currency::Format::error*.
CODE
A 3-letter currency code as specified in ISO 4217
TYPE
There are two available types SYM_UTF and SYM_HTML
SYM_UTF returns the symbol (if exists) as an Unicode
character
SYM_HTML returns the symbol (if exists) as a HTML escape
* \'currency_name(CODE)\'
For conveniences, the function *currency_name* is provided for currency
name lookup given a 3-letter currency code. Upon failure, it returns
_undef_ and an error message is stored in
*$Locale::Currency::Format::error*.
CODE
A 3-letter currency code as specified in ISO 4217
* \'decimal_precision(CODE)\'
For conveniences, the function *decimal_precision* is provided to lookup
the decimal precision for a given 3-letter currency code.
Upon failure, it returns _undef_ and an error message is stored in
*$Locale::Currency::Format::error*.
CODE
A 3-letter currency code as specified in ISO 4217
* \'decimal_separator(CODE)\'
For conveniences, the function *decimal_separator* is provided to lookup
the decimal separator for a given 3-letter currency code.
Upon failure, it returns _undef_ and an error message is stored in
*$Locale::Currency::Format::error*.
CODE
A 3-letter currency code as specified in ISO 4217
* \'thousands_separator(CODE)\'
For conveniences, the function *thousands_separator* is provided to
lookup the thousands separator for a given 3-letter currency code.
Upon failure, it returns _undef_ and an error message is stored in
*$Locale::Currency::Format::error*.
CODE
A 3-letter currency code as specified in ISO 4217
* \'currency_set(CODE [, TEMPLATE, FORMAT])\'
*currency_set* can be used to set a custom format for a currency instead
of the provided format. For example, in many non-English speaking
countries, the US dollars might be displayed as *2.999,99 $* instead of
the usual *$2,999.99*. In order to accomplish this, one will need to do
as follows:
use Locale::Currency::Format qw(:default $error);
my $currency = \'USD\';
my $template = \'#.###,## $\';
if (currency_set($currency, $template, FMT_COMMON)) {
print currency_format($currency, 2999.99, FMT_COMMON), \"\
\";
}
else {
print \"cannot set currency format for $currency: $error\
\";
}
The arguments to *currency_set* are:
CODE
A 3-letter currency code as specified in ISO 4217
TEMPLATE
A template in the form #.###,##$, #.### kr, etc.
If a unicode character is used, make sure that
the template is double-quoted.
Ex: currency_set(\'GBP\', \"\\x{00A3}#,###.##\", FMT_SYMBOL)
If an HTML symbol is wanted, escape its equivalent HTML code.
Ex: currency_set(\'GBP\', \'£#,###.##\', FMT_HTML)
FORMAT
This argument is required if TEMPLATE is present.
The formats FMT_SYMBOL, FMT_COMMON, FMT_HTML are accepted.
NOTE!
FMT_STANDARD and FMT_NAME will always be in the form
< amount>< space>< code|name> such as 1,925.95 AUD. Hence,
currency_set returns an error if FMT_STANDARD or FMT_NAME
is specified as FORMAT.
With FMT_COMMON, you can always achieve what you would
have done with FMT_STANDARD and FMT_NAME, as follows
my $amt = 1950.95;
currency_set(\'USD\', \'USD #.###,##\', FMT_COMMON);
print currency_format(\'USD\', $amt, FMT_COMMON); # USD 1,950.95
currency_set(\'USD\', \'US Dollar #.###,##\', FMT_COMMON);
print currency_format(\'USD\', $amt, FMT_COMMON); # US Dollar 1,950.95
Invoking *currency_set* with one argument will reset all formats to their
original settings.
For example
currency_set(\'USD\')
will clear all previous custom settings for the US currency (ie.
FMT_SYMBOL, FMT_HTML, FMT_COMMON).
|
