|
|
| |
Format(3) |
User Contributed Perl Documentation |
Format(3) |
Locale::Currency::Format - Perl functions for formatting monetary values
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(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).
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!"
Locale::Currency, Math::Currency, Number::Format, perluniintro, perlunicode
Pull requests are greatly appreciated at
https://github.com/tann/locale-currency-format
Please add your name to this list when sending a pull request.
James Kiser <james.kiser@gmail.com>
Lars Wirzenius <lars@catalyst.net.nz>
Tan D Nguyen <https://github.com/tann>
This library is free software. You may distribute under the terms of either the
GNU General Public License or the Artistic License.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |