Re: Copious warnings from Sys::Syslog
[p5sagit/p5-mst-13.2.git] / lib / Locale / Currency.pod
1
2 =head1 NAME
3
4 Locale::Currency - ISO three letter codes for currency identification (ISO 4217)
5
6 =head1 SYNOPSIS
7
8     use Locale::Currency;
9
10     $curr = code2currency('usd');     # $curr gets 'US Dollar'
11     $code = currency2code('Euro');    # $code gets 'eur'
12
13     @codes   = all_currency_codes();
14     @names   = all_currency_names();
15
16
17 =head1 DESCRIPTION
18
19 The C<Locale::Currency> module provides access to the ISO three-letter
20 codes for identifying currencies and funds, as defined in ISO 4217.
21 You can either access the codes via the L<conversion routines>
22 (described below),
23 or with the two functions which return lists of all currency codes or
24 all currency names.
25
26 There are two special codes defined by the standard which aren't
27 understood by this module:
28
29 =over 4
30
31 =item XTS
32
33 Specifically reserved for testing purposes.
34
35 =item XXX
36
37 For transactions where no currency is involved.
38
39 =back
40
41
42 =head1 CONVERSION ROUTINES
43
44 There are two conversion routines: C<code2currency()> and C<currency2code()>.
45
46 =over 4
47
48 =item code2currency()
49
50 This function takes a three letter currency code and returns a string
51 which contains the name of the currency identified. If the code is
52 not a valid currency code, as defined by ISO 4217, then C<undef>
53 will be returned.
54
55     $curr = code2currency($code);
56
57 =item currency2code()
58
59 This function takes a currency name and returns the corresponding
60 three letter currency code, if such exists.
61 If the argument could not be identified as a currency name,
62 then C<undef> will be returned.
63
64     $code = currency2code('French Franc');
65
66 The case of the currency name is not important.
67 See the section L<KNOWN BUGS AND LIMITATIONS> below.
68
69 =back
70
71
72 =head1 QUERY ROUTINES
73
74 There are two function which can be used to obtain a list of all
75 currency codes, or all currency names:
76
77 =over 4
78
79 =item C<all_currency_codes()>
80
81 Returns a list of all three-letter currency codes.
82 The codes are guaranteed to be all lower-case,
83 and not in any particular order.
84
85 =item C<all_currency_names()>
86
87 Returns a list of all currency names for which there is a corresponding
88 three-letter currency code. The names are capitalised, and not returned
89 in any particular order.
90
91 =back
92
93
94 =head1 EXAMPLES
95
96 The following example illustrates use of the C<code2currency()> function.
97 The user is prompted for a currency code, and then told the corresponding
98 currency name:
99
100     $| = 1;    # turn off buffering
101
102     print "Enter currency code: ";
103     chop($code = <STDIN>);
104     $curr = code2currency($code);
105     if (defined $curr)
106     {
107         print "$code = $curr\n";
108     }
109     else
110     {
111         print "'$code' is not a valid currency code!\n";
112     }
113
114 =head1 KNOWN BUGS AND LIMITATIONS
115
116 =over 4
117
118 =item *
119
120 In the current implementation, all data is read in when the
121 module is loaded, and then held in memory.
122 A lazy implementation would be more memory friendly.
123
124 =item *
125
126 This module also includes the special codes which are
127 not for a currency, such as Gold, Platinum, etc.
128 This might cause a problem if you're using this module
129 to display a list of currencies.
130 Let Neil know if this does cause a problem, and we can
131 do something about it.
132
133 =item *
134
135 ISO 4217 also defines a numeric code for each currency.
136 Currency codes are not currently supported by this module,
137 in the same way Locale::Country supports multiple codesets.
138
139 =item *
140
141 There are three cases where there is more than one
142 code for the same currency name.
143 Kwacha has two codes: mwk for Malawi, and zmk for Zambia.
144 The Russian Ruble has two codes: rub and rur.
145 The Belarussian Ruble has two codes: byr and byb.
146 The currency2code() function only returns one code, so
147 you might not get back the code you expected.
148
149 =back
150
151 =head1 SEE ALSO
152
153 =over 4
154
155 =item Locale::Country
156
157 ISO codes for identification of country (ISO 3166).
158
159 =item Locale::Script
160
161 ISO codes for identification of written scripts (ISO 15924).
162
163 =item ISO 4217:1995
164
165 Code for the representation of currencies and funds.
166
167 =item http://www.bsi-global.com/iso4217currency
168
169 Official web page for the ISO 4217 maintenance agency.
170 This has the latest list of codes, in MS Word format. Boo.
171
172 =back
173
174 =head1 AUTHOR
175
176 Michael Hennecke E<lt>hennecke@rz.uni-karlsruhe.deE<gt>
177 and
178 Neil Bowers E<lt>neil@bowers.comE<gt>
179
180 =head1 COPYRIGHT
181
182 Copyright (C) 2002, Neil Bowers.
183
184 Copyright (c) 2001 Michael Hennecke and
185 Canon Research Centre Europe (CRE).
186
187 This module is free software; you can redistribute it and/or
188 modify it under the same terms as Perl itself.
189
190 =cut
191