Locale::Currency::Format - Perl functions for formatting monetary values

NAME

Locale::Currency::Format - Perl functions for formatting monetary values

SYNOPSIS

  use Locale::Currency::Format;
  $amnt = currency_format('usd', 1000);             # => 1,000.00 USD
  $amnt = currency_format('eur', 1000, FMT_COMMON); # => EUR1.000,00
  $amnt = currency_format('usd', 1000, FMT_SYMBOL); # => $1,000.00
  $sym  = currency_symbol('usd');                   # => $
  $sym  = currency_symbol('gbp', SYM_HTML);         # => £
  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 ($amnt, $code) = ${$_[0]} =~ /(.*?)([A-Za-z]{3})/;
      ${$_[0]} = currency_format($code, $amnt, FMT_HTML);
    }
  </%init>

DESCRIPTION

Locale::Currency::Format is a light-weight Perl module that allows one to display monetary values in the formats recognized internationally or locally depending on his wish.

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 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
           FMT_SYMBOL   Ex: $1,000.00
           FMT_COMMON   Ex: 1.000 Dong (Vietnam), BEF 1.000 (Belgium)
           FMT_HTML     Ex: &#xA3;1,000.00  (pound-sign HTML escape)
           FMT_NAME     Ex: 1,000.00 US Dollar
           By default the trailing zeros after the decimal point will
           be added. To turn it off, do a bitwise B<or> of FMT_NOZEROS
           with one of the five options above.
           Ex: FMT_STANDARD | FMT_NOZEROS  will give 1,000 USD


=item C<currency_symbol(CODE [, TYPE])>

For conveniences, the function currency_symbol is provided for 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

A WORD OF CAUTION

Please be aware that some currencies might have missing common format. In that case, currency_format will fall back to FMT_STANDARD 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 ISO. 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('US', 1000);
  print $value ? $value : $Locale::Currency::Format::error
  OR
  use Locale::Currency::Format qw(:DEFAULT $error);
  my $value = currency_format('US', 1000);
  print $value ? $value : $error

Lastly, please refer to the perluniintro manpage and the perlunicode manpage for displaying Unicode characters if you intend to use FMT_SYMBOL and currency_symbol. Otherwise, it reads ``No worries, mate!''

SEE ALSO

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

BUGS

If you find any inaccurate or missing information, please send your comments to tnguyen@cpan.org. Your effort is certainly appreciated!

 Locale::Currency::Format - Perl functions for formatting monetary values