Locale::Currency::Format(3pm)

1Format(3)             User Contributed Perl Documentation            Format(3)
2
3
4

NAME

6       Locale::Currency::Format - Perl functions for formatting monetary
7       values
8

SYNOPSIS

10         use Locale::Currency::Format;
11
12         $amt = currency_format('USD', 1000);             # => 1,000.00 USD
13         $amt = currency_format('EUR', 1000, FMT_COMMON); # => EUR1.000,00
14         $amt = currency_format('USD', 1000, FMT_SYMBOL); # => $1,000.00
15
16         $sym = currency_symbol('USD');                   # => $
17         $sym = currency_symbol('GBP', SYM_HTML);         # => &#163;
18
19         $decimals = decimal_precision('USD');            # => 2
20         $decimals = decimal_precision('BHD');            # => 3
21
22         $thou_sep = thousands_separator('USD');          # => ,
23         $thou_sep = thousands_separator('EUR');          # => .
24
25         $dec_sep = decimal_separator('USD');             # => .
26         $dec_sep = decimal_separator('EUR');             # => ,
27
28         currency_set('USD', '#.###,## $', FMT_COMMON);   # => set custom format
29         currency_format('USD', 1000, FMT_COMMON);        # => 1.000,00 $
30         currency_set('USD');                             # => reset default format
31
32       The following example illustrates how to use Locale::Currency::Format
33       with Mason. Skip it if you are not interested in Mason. A simple Mason
34       component might look like this:
35
36         Total: <% 123456789, 'eur' |c %>
37
38         <%init>
39           use Locale::Currency::Format;
40
41           $m->interp->set_escape(c => \&escape_currency);
42
43           sub escape_currency {
44             my ($amt, $code) = ${$_[0]} =~ /(.*?)([A-Za-z]{3})/;
45             ${$_[0]} = currency_format($code, $amt, FMT_HTML);
46           }
47         </%init>
48

DESCRIPTION

50       Locale::Currency::Format is a light-weight Perl module that enables
51       Perl code to display monetary values in the formats recognized
52       internationally and/or locally.
53
54       "currency_format(CODE, AMOUNT [, FORMAT])"
55         currency_format takes two mandatory parameters, namely currency code
56         and amount respectively, and optionally a third parameter indicating
57         which format is desired. Upon failure, it returns undef and an error
58         message is stored in $Locale::Currency::Format::error.
59
60             CODE
61                 A 3-letter currency code as specified in ISO 4217.
62                 Note that old code such as DEM, FRF and so on can also
63                 be valid.
64
65             AMOUNT
66                 A numeric value.
67
68             FORMAT
69                 There are five different format options FMT_STANDARD,
70                 FMT_COMMON, FMT_SYMBOL, FMT_HTML and FMT_NAME. If it is
71                 omitted, the default format is FMT_STANDARD.
72
73                 FMT_STANDARD Ex: 1,000.00 USD, 1.000.000,00 EUR
74                 FMT_SYMBOL   Ex: $1,000.00
75                 FMT_COMMON   Ex: 1.000 Dong (Vietnam), BEF 1.000 (Belgium)
76                 FMT_HTML     Ex: &#xA3;1,000.00  (pound-sign HTML escape)
77                 FMT_NAME     Ex: 1,000.00 US Dollar
78
79                 NOTE: By default the trailing zeros after the decimal
80                 point will be added. To turn it off, do a bitwise C<or>
81                 of FMT_NOZEROS with one of the five options above.
82                 Ex: FMT_STANDARD | FMT_NOZEROS  will give 1,000 USD
83
84       "currency_symbol(CODE [, TYPE])"
85         For conveniences, the function currency_symbol is provided for
86         currency symbol lookup given a 3-letter currency code. Optionally,
87         one can specify which format the symbol should be returned - Unicode-
88         based character or HTML escape.  Default is a Unicode-based
89         character. Upon failure, it returns undef and an error message is
90         stored in $Locale::Currency::Format::error.
91
92             CODE
93                 A 3-letter currency code as specified in ISO 4217
94
95             TYPE
96                 There are two available types SYM_UTF and SYM_HTML
97                 SYM_UTF  returns the symbol (if exists) as an Unicode
98                          character
99                 SYM_HTML returns the symbol (if exists) as a HTML escape
100
101       currency_name(CODE)
102         For conveniences, the function currency_name is provided for currency
103         name lookup given a 3-letter currency code. Upon failure, it returns
104         undef and an error message is stored in
105         $Locale::Currency::Format::error.
106
107             CODE
108                 A 3-letter currency code as specified in ISO 4217
109
110       decimal_precision(CODE)
111         For conveniences, the function decimal_precision is provided to
112         lookup the decimal precision for a given 3-letter currency code.
113
114         Upon failure, it returns undef and an error message is stored in
115         $Locale::Currency::Format::error.
116
117             CODE
118                 A 3-letter currency code as specified in ISO 4217
119
120       decimal_separator(CODE)
121         For conveniences, the function decimal_separator is provided to
122         lookup the decimal separator for a given 3-letter currency code.
123
124         Upon failure, it returns undef and an error message is stored in
125         $Locale::Currency::Format::error.
126
127             CODE
128                 A 3-letter currency code as specified in ISO 4217
129
130       thousands_separator(CODE)
131         For conveniences, the function thousands_separator is provided to
132         lookup the thousands separator for a given 3-letter currency code.
133
134         Upon failure, it returns undef and an error message is stored in
135         $Locale::Currency::Format::error.
136
137             CODE
138                 A 3-letter currency code as specified in ISO 4217
139
140       "currency_set(CODE [, TEMPLATE, FORMAT])"
141         currency_set can be used to set a custom format for a currency
142         instead of the provided format. For example, in many non-English
143         speaking countries, the US dollars might be displayed as 2.999,99 $
144         instead of the usual $2,999.99. In order to accomplish this, one will
145         need to do as follows:
146
147             use Locale::Currency::Format qw(:default $error);
148
149             my $currency = 'USD';
150             my $template = '#.###,## $';
151             if (currency_set($currency, $template, FMT_COMMON)) {
152                 print currency_format($currency, 2999.99, FMT_COMMON), "\n";
153             }
154             else {
155                 print "cannot set currency format for $currency: $error\n";
156             }
157
158         The arguments to currency_set are:
159
160             CODE
161                 A 3-letter currency code as specified in ISO 4217
162
163             TEMPLATE
164                 A template in the form #.###,##$, #.### kr, etc.
165
166                 If a unicode character is used, make sure that
167                 the template is double-quoted.
168                 Ex: currency_set('GBP', "\x{00A3}#,###.##", FMT_SYMBOL)
169
170                 If an HTML symbol is wanted, escape its equivalent HTML code.
171                 Ex: currency_set('GBP', '&#x00A3;#,###.##', FMT_HTML)
172
173             FORMAT
174                 This argument is required if TEMPLATE is present.
175                 The formats FMT_SYMBOL, FMT_COMMON, FMT_HTML are accepted.
176
177                 NOTE!
178                 FMT_STANDARD and FMT_NAME will always be in the form
179                 <amount><space><code|name> such as 1,925.95 AUD. Hence,
180                 currency_set returns an error if FMT_STANDARD or FMT_NAME
181                 is specified as FORMAT.
182
183                 With FMT_COMMON, you can always achieve what you would
184                 have done with FMT_STANDARD and FMT_NAME, as follows
185
186                 my $amt = 1950.95;
187                 currency_set('USD', 'USD #.###,##', FMT_COMMON);
188                 print currency_format('USD', $amt, FMT_COMMON); # USD 1,950.95
189                 currency_set('USD', 'US Dollar #.###,##', FMT_COMMON);
190                 print currency_format('USD', $amt, FMT_COMMON); # US Dollar 1,950.95
191
192         Invoking currency_set with one argument will reset all formats to
193         their original settings.
194
195         For example
196
197             currency_set('USD')
198
199         will clear all previous custom settings for the US currency (ie.
200         FMT_SYMBOL, FMT_HTML, FMT_COMMON).
201
202   A WORD OF CAUTION
203       Please be aware that some currencies might have missing common format.
204       In that case, currency_format will fall back to FMT_STANDARD format.
205
206       Also, be aware that some currencies do not have monetary symbol.
207
208       As countries merge together or split into smaller ones, currencies can
209       be added or removed by the ISO. Please help keep the list up to date by
210       sending your feedback to the email address at the bottom.
211
212       To see the error, examine $Locale::Currency::Format::error
213
214           use Locale::Currency::Format;
215           my $value = currency_format('USD', 1000);
216           print $value ? $value : $Locale::Currency::Format::error
217
218           OR
219
220           use Locale::Currency::Format qw(:DEFAULT $error);
221           my $value = currency_format('USD', 1000);
222           print $value ? $value : $error
223
224       Lastly, please refer to perluniintro and perlunicode for displaying
225       Unicode characters if you intend to use FMT_SYMBOL and currency_symbol.
226       Otherwise, it reads "No worries, mate!"
227

ISSUES

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

CONTRIBUTOR(S)

237       Please add your name to this list when sending a pull request.
238
239       James Kiser <james.kiser@gmail.com>
240
241       Lars Wirzenius <lars@catalyst.net.nz>
242

AUTHOR

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

COPYRIGHT

247       This library is free software. You may distribute under the terms of
248       either the GNU General Public License or the Artistic License.
249
250
251
252perl v5.36.0                      2023-01-20                         Format(3)