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
28class QDate;
29class QStringList;
30class QFileInfo;
31
32class 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 */
45class KDECORE_EXPORT KCurrencyCode
46{
47public:
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 &currencyCodeFile, 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 &currencyCode, 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 &currencyCode, const QString &language = QString() );
332
333
334private:
335 QSharedDataPointer<KCurrencyCodePrivate> d;
336};
337
338Q_DECLARE_OPERATORS_FOR_FLAGS( KCurrencyCode::CurrencyStatusFlags )
339
340
341#endif // KCURRENCYCODE_H
342