1 | /* |
2 | Copyright (c) 2009 John Layt <john@layt.net> |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License as published by the Free Software Foundation; either |
7 | version 2 of the License, or (at your option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KCURRENCYCODE_H |
21 | #define KCURRENCYCODE_H |
22 | |
23 | #include <kdecore_export.h> |
24 | |
25 | #include <QtCore/QSharedDataPointer> |
26 | #include <QtCore/QString> |
27 | |
28 | class QDate; |
29 | class QStringList; |
30 | class QFileInfo; |
31 | |
32 | class KCurrencyCodePrivate; |
33 | |
34 | /** |
35 | * @since 4.4 |
36 | * |
37 | * This is a class to implement the ISO 4217 Currency Code standard |
38 | * |
39 | * @b license GNU-LGPL v.2 or later |
40 | * |
41 | * @see KLocale |
42 | * |
43 | * @author John Layt <john@layt.net> |
44 | */ |
45 | class KDECORE_EXPORT KCurrencyCode |
46 | { |
47 | public: |
48 | /** |
49 | * The Status of the Currency |
50 | * |
51 | * @see CurrencyStatusFlags |
52 | * @see currencyStatus() |
53 | */ |
54 | enum CurrencyStatus { |
55 | ActiveCurrency = 0x01, /**< Currency is currently in use */ |
56 | SuspendedCurrency = 0x02, /**< Currency is not currently in use but has not been replaced */ |
57 | ObsoleteCurrency = 0x04 /**< Currency is no longer in use and has been replaced */ |
58 | }; |
59 | Q_DECLARE_FLAGS( CurrencyStatusFlags, CurrencyStatus ) |
60 | |
61 | /** |
62 | * Constructs a KCurrencyCode for a given ISO Currency Code. |
63 | * |
64 | * If the supplied Currency Code is not known then the KCurrencyCode will return isValid() == false |
65 | * |
66 | * @param isoCurrencyCode the ISO Currency Code to construct, defaults to USD |
67 | * @param language the language to use for translations, default to the Locale language |
68 | * |
69 | */ |
70 | explicit KCurrencyCode( const QString &isoCurrencyCode, const QString &language = QString() ); |
71 | |
72 | /** |
73 | * Constructs a KCurrencyCode for a given config file and Language. |
74 | * |
75 | * Note that any translations must be supplied in the config file, none will be provided. |
76 | * |
77 | * If the supplied config file is not valid then the KCurrencyCode will return isValid() == false |
78 | * |
79 | * @param currencyCodeFile the ISO Currency Code to construct, defaults to USD |
80 | * @param language the language to use for translations, default to the Locale language |
81 | * |
82 | */ |
83 | explicit KCurrencyCode( const QFileInfo ¤cyCodeFile, const QString &language = QString() ); |
84 | |
85 | /** |
86 | * Copy Constructor |
87 | * |
88 | * @param rhs KCurrencyCode to copy |
89 | * |
90 | */ |
91 | KCurrencyCode( const KCurrencyCode &rhs ); |
92 | |
93 | /** |
94 | * Destructor. |
95 | */ |
96 | virtual ~KCurrencyCode(); |
97 | |
98 | /** |
99 | * Assignment operator |
100 | * |
101 | * @param rhs KCurrencyCode to assign |
102 | * |
103 | */ |
104 | KCurrencyCode& operator=( const KCurrencyCode &rhs ); |
105 | |
106 | /** |
107 | * Return the ISO 4217 Currency Code in Alpha 3 format, e.g. USD |
108 | * |
109 | * @return the ISO Currency Code |
110 | * |
111 | * @see isoCurrencyCodeNumeric() |
112 | */ |
113 | QString isoCurrencyCode() const; |
114 | |
115 | /** |
116 | * Return the ISO 4217 Currency Code in Numeric 3 format, e.g. 840 |
117 | * |
118 | * @return the ISO Currency Code |
119 | * |
120 | * @see isoCurrencyCode() |
121 | */ |
122 | QString isoCurrencyCodeNumeric() const; |
123 | |
124 | /** |
125 | * Return translated Currency Code Name in a standard display format |
126 | * e.g. United States Dollar |
127 | * |
128 | * @return the display Currency Code Name |
129 | * |
130 | * @see isoName() |
131 | */ |
132 | QString name() const; |
133 | |
134 | /** |
135 | * Return untranslated official ISO Currency Code Name |
136 | * |
137 | * This name is not translated and should only be used where appropriate. |
138 | * For displaying the name to a user, use name() instead. |
139 | * |
140 | * @return the official ISO Currency Code Name |
141 | * |
142 | * @see name() |
143 | */ |
144 | QString isoName() const; |
145 | |
146 | /** |
147 | * Return Currency Status for the currency, if Active, Suspended or Obsolete |
148 | * |
149 | * @return the Currency Status |
150 | * |
151 | * @see CurrencyStatus |
152 | */ |
153 | CurrencyStatus status() const; |
154 | |
155 | /** |
156 | * Return the date the currency was introduced |
157 | * |
158 | * @return the date the currency was introduced |
159 | * |
160 | * @see status() |
161 | * @see dateSuspended() |
162 | * @see dateWithdrawn() |
163 | */ |
164 | QDate dateIntroduced() const; |
165 | |
166 | /** |
167 | * Return the date the currency was suspended |
168 | * |
169 | * @return the date the currency was suspended, QDate() if active |
170 | * |
171 | * @see status() |
172 | * @see dateIntroduced() |
173 | * @see dateWithdrawn() |
174 | */ |
175 | QDate dateSuspended() const; |
176 | |
177 | /** |
178 | * Return the date the currency was withdrawn from circulation |
179 | * |
180 | * @return the date the currency was withdrawn, QDate() if active |
181 | * |
182 | * @see status() |
183 | * @see dateIntroduced() |
184 | * @see dateSuspended() |
185 | */ |
186 | QDate dateWithdrawn() const; |
187 | |
188 | /** |
189 | * Return a list of valid Symbols for the Currency in order of preference |
190 | * |
191 | * This list will normally contain the Default and Unambiguous symbols and the ISO Currency Code |
192 | * |
193 | * @return list of Currency Symbols |
194 | * |
195 | * @see defaultSymbol() |
196 | * @see unambiguousSymbol() |
197 | */ |
198 | QStringList symbolList() const; |
199 | |
200 | /** |
201 | * Return the default Symbol for the Currency, e.g. $ or £ |
202 | * |
203 | * @return the default Currency Symbol |
204 | * |
205 | * @see symbols() |
206 | * @see unambiguousSymbol() |
207 | */ |
208 | QString defaultSymbol() const; |
209 | |
210 | /** |
211 | * Return the unambiguous Symbol for the Currency, e.g. US$ or NZ$ |
212 | * |
213 | * @return the unambiguous Currency Symbol |
214 | * |
215 | * @see symbols() |
216 | * @see defaultSymbol() |
217 | */ |
218 | QString unambiguousSymbol() const; |
219 | |
220 | /** |
221 | * Return if the Currency has subunits or not, |
222 | * e.g. USD has cents, VUV has none |
223 | * |
224 | * @return true if the Currency has subunits |
225 | * |
226 | * @see hasSubunitsInCirculation() |
227 | * @see subunitName() |
228 | * @see subunitSymbol() |
229 | * @see subunitsPerUnit() |
230 | */ |
231 | bool hasSubunits() const; |
232 | |
233 | /** |
234 | * Return if the Currency has subunits in circulation, |
235 | * e.g. JPY has sen but these are no longer used due to inflation |
236 | * |
237 | * @return true if the Currency has subunits in circulation |
238 | * |
239 | * @see hasSubunits() |
240 | */ |
241 | bool hasSubunitsInCirculation() const; |
242 | |
243 | /** |
244 | * Return the Currency subunit symbol if it has one |
245 | * e.g. ¢ for USD cent |
246 | * |
247 | * @return the currency subunit symbol |
248 | * |
249 | * @see hasSubunits() |
250 | */ |
251 | QString subunitSymbol() const; |
252 | |
253 | /** |
254 | * Return the number of subunits in every unit, e.g. 100 cents in the dollar |
255 | * |
256 | * @return number of subunits per unit, 0 if no subunits |
257 | * |
258 | * @see hasSubunits() |
259 | */ |
260 | int subunitsPerUnit() const; |
261 | |
262 | /** |
263 | * Return the number of decimal places required to display the currency subunits |
264 | * |
265 | * @return number of decimal places |
266 | */ |
267 | int decimalPlaces() const; |
268 | |
269 | /** |
270 | * Return a list of countries known to be using the currency |
271 | * |
272 | * @return list of ISO Country Codes using the currency |
273 | */ |
274 | QStringList countriesUsingCurrency() const; |
275 | |
276 | /** |
277 | * Return if the currency object loaded/initialised correctly |
278 | * |
279 | * @return true if valid KCurrencyCode object |
280 | */ |
281 | bool isValid() const; |
282 | |
283 | /** |
284 | * Return if a given Currency Code is supported in KDE. |
285 | * Optionally validate if an Active, Suspended, or Obsolete currency, default is if any. |
286 | * |
287 | * @param currencyCode the Currency Code to validate |
288 | * @param currencyStatus the CurrencyStatus to validate |
289 | * |
290 | * @return true if valid currency code |
291 | */ |
292 | static bool isValid( const QString ¤cyCode, CurrencyStatusFlags currencyStatus = |
293 | CurrencyStatusFlags( ActiveCurrency | |
294 | SuspendedCurrency | |
295 | ObsoleteCurrency ) ); |
296 | |
297 | /** |
298 | * Provides list of all known ISO Currency Codes. |
299 | * |
300 | * Use currencyCodeToName(currencyCode) to get human readable, localized currency names. |
301 | * |
302 | * By default returns all Active, Suspended and Obsolete currencies, set the currencyStatus |
303 | * flags as appropriate to return required status currencies |
304 | * |
305 | * @param currencyStatus which status currencies to return |
306 | * |
307 | * @return a list of all ISO Currency Codes |
308 | * |
309 | * @see currencyCodeToName |
310 | */ |
311 | static QStringList allCurrencyCodesList( CurrencyStatusFlags currencyStatus = |
312 | CurrencyStatusFlags( ActiveCurrency | |
313 | SuspendedCurrency | |
314 | ObsoleteCurrency ) ); |
315 | |
316 | /** |
317 | * Convert a known ISO Currency Code to a human readable, localized form. |
318 | * |
319 | * If an unknown Currency Code is supplied, empty string is returned; |
320 | * this will never happen if the code has been obtained by one of the |
321 | * KCurrencyCode methods. |
322 | * |
323 | * @param currencyCode the ISO Currency Code |
324 | * @param language the language to use for translations, default to the Locale language |
325 | * |
326 | * @return the human readable and localized form of the Currency name |
327 | * |
328 | * @see currencyCode |
329 | * @see allCurrencyCodesList |
330 | */ |
331 | static QString currencyCodeToName( const QString ¤cyCode, const QString &language = QString() ); |
332 | |
333 | |
334 | private: |
335 | QSharedDataPointer<KCurrencyCodePrivate> d; |
336 | }; |
337 | |
338 | Q_DECLARE_OPERATORS_FOR_FLAGS( KCurrencyCode::CurrencyStatusFlags ) |
339 | |
340 | |
341 | #endif // KCURRENCYCODE_H |
342 | |