Locale::Currency::Format (3pm)

  use Locale::Currency::Format;

  $amt = currency_format('USD', 1000);             # => 1,000.00 USD
  $amt = currency_format('EUR', 1000, FMT_COMMON); # => EUR1.000,00
  $amt = currency_format('USD', 1000, FMT_SYMBOL); # => $1,000.00

  $sym = currency_symbol('USD');                   # => $
  $sym = currency_symbol('GBP', SYM_HTML);         # => £

  $decimals = decimal_precision('USD');            # => 2
  $decimals = decimal_precision('BHD');            # => 3

  $thou_sep = thousands_separator('USD');          # => ,
  $thou_sep = thousands_separator('EUR');          # => .

  $dec_sep = decimal_separator('USD');             # => .
  $dec_sep = decimal_separator('EUR');             # => ,

  currency_set('USD', '#.###,## $', FMT_COMMON);   # => set custom format
  currency_format('USD', 1000, FMT_COMMON);        # => 1.000,00 $
  currency_set('USD');                             # => reset default format

The following example illustrates how to use Locale::Currency::Format with Mason. Skip it if you are not interested in Mason. A simple Mason component might look like this:

Total: <% 123456789, 'eur' |c %>

<%init> use Locale::Currency::Format;

$m->interp->set_escape(c => \&escape_currency);

sub escape_currency { my ($amt, $code) = ${$_[0]} =~ /(.*?)([A-Za-z]{3})/; ${$_[0]} = currency_format($code, $amt, FMT_HTML); } </%init>

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 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 GBP, 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 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 \s-1HTML\s0 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 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 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 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 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 \s-1US\s0 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), "\n"; } else { print "cannot set currency format for $currency: $error\n"; } 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 \s-1US\s0 currency (ie. \s-1FMT_SYMBOL\s0, \s-1FMT_HTML\s0, \s-1FMT_COMMON\s0).

A \s-1WORD\s0 \s-1OF\s0 \s-1CAUTION\s0

Please be aware that some currencies might have missing common format. In that case, currency_format will fall back to \s-1FMT_STANDARD\s0 format.

Also, be aware that some currencies do not have monetary symbol.

As countries merge together or split into smaller ones, currencies can be added or removed by the \s-1ISO\s0. Please help keep the list up to date by sending your feedback to the email address at the bottom.

To see the error, examine $Locale::Currency::Format::error

use Locale::Currency::Format; my $value = currency_format('USD', 1000); print $value ? $value : $Locale::Currency::Format::error

OR

use Locale::Currency::Format qw(:DEFAULT $error); my $value = currency_format('USD', 1000); print $value ? $value : $error

Lastly, please refer to perluniintro and perlunicode for displaying Unicode characters if you intend to use \s-1FMT_SYMBOL\s0 and currency_symbol. Otherwise, it reads \*(L"No worries, mate!\*(R"

Locale::Currency, Math::Currency, Number::Format, perluniintro, perlunicode

If you find any inaccurate or missing information, please send your comments to [email protected]. Your effort is certainly appreciated!

James Kiser <[email protected]>

Tan D Nguyen <[email protected]>

This library is free software. You may distribute under the terms of either the \s-1GNU\s0 General Public License or the Artistic License.