NAME¶

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

SYNOPSIS¶

  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>

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), "\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 US currency (ie. FMT_SYMBOL, FMT_HTML, FMT_COMMON).

    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

SEE ALSO¶

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

ISSUES¶

Pull requests are greatly appreciated at https://github.com/tann/locale-currency-format

CONTRIBUTOR(S)¶

Please add your name to this list when sending a pull request.

James Kiser <james.kiser@gmail.com>

Lars Wirzenius <lars@catalyst.net.nz>

AUTHOR¶

Tan D Nguyen <https://github.com/tann>

COPYRIGHT¶

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