GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  LOCALE::CURRENCY::FORMAT (3)

.ds Aq ’

NAME

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

CONTENTS

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

<B>Locale::Currency::FormatB> 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]) <B>currency_formatB> 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 <B>B>$Locale::Currency::Format::error<B>B>.



    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 <B>currency_symbolB> 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 <B>B>$Locale::Currency::Format::error<B>B>.



    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 <B>currency_nameB> is provided for currency name lookup given a 3-letter currency code. Upon failure, it returns undef and an error message is stored in <B>B>$Locale::Currency::Format::error<B>B>.



    CODE
        A 3-letter currency code as specified in ISO 4217



decimal_precision(CODE) For conveniences, the function <B>decimal_precisionB> 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 <B>B>$Locale::Currency::Format::error<B>B>.



    CODE
        A 3-letter currency code as specified in ISO 4217



decimal_separator(CODE) For conveniences, the function <B>decimal_separatorB> 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 <B>B>$Locale::Currency::Format::error<B>B>.



    CODE
        A 3-letter currency code as specified in ISO 4217



thousands_separator(CODE) For conveniences, the function <B>thousands_separatorB> 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 <B>B>$Locale::Currency::Format::error<B>B>.



    CODE
        A 3-letter currency code as specified in ISO 4217



currency_set(CODE [, TEMPLATE, FORMAT]) <B>currency_setB> 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 <B>2.999,99 $B> instead of the usual <B>B>$2<B>,999.99B>. 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 <B>currency_setB> 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 <B>currency_setB> 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, <B>currency_formatB> will fall back to <B>FMT_STANDARDB> 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 <B>FMT_SYMBOLB> and <B>currency_symbolB>. 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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 FORMAT (3) 2015-10-26

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.