Provided by: liblocale-currency-format-perl_1.35-3_all bug

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: &#xA3;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', '&#x00A3;#,###.##', 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).

   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('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 FMT_SYMBOL and currency_symbol. Otherwise, it reads "No worries, mate!"

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.