KDELibs4Support

kcurrencycode.h
1 /*
2  Copyright (c) 2009 John Layt <[email protected]>
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 <kdelibs4support_export.h>
24 
25 #include <QSharedDataPointer>
26 #include <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 <[email protected]>
44  *
45  * @deprecated since 5.0, a replacement will be provided by the KStandards
46  * framework (not available in KDE Frameworks 5.0)
47  */
48 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KCurrencyCode
49 {
50 public:
51  /**
52  * The Status of the Currency
53  *
54  * @see CurrencyStatusFlags
55  * @see currencyStatus()
56  */
58  ActiveCurrency = 0x01, /**< Currency is currently in use */
59  SuspendedCurrency = 0x02, /**< Currency is not currently in use but has not been replaced */
60  ObsoleteCurrency = 0x04 /**< Currency is no longer in use and has been replaced */
61  };
62  Q_DECLARE_FLAGS(CurrencyStatusFlags, CurrencyStatus)
63 
64  /**
65  * Constructs a KCurrencyCode for a given ISO Currency Code.
66  *
67  * If the supplied Currency Code is not known then the KCurrencyCode will return isValid() == false
68  *
69  * @param isoCurrencyCode the ISO Currency Code to construct, defaults to USD
70  * @param language the language to use for translations, default to the Locale language
71  *
72  */
73  KDELIBS4SUPPORT_DEPRECATED explicit KCurrencyCode(const QString &isoCurrencyCode, const QString &language = QString());
74 
75  /**
76  * Constructs a KCurrencyCode for a given config file and Language.
77  *
78  * Note that any translations must be supplied in the config file, none will be provided.
79  *
80  * If the supplied config file is not valid then the KCurrencyCode will return isValid() == false
81  *
82  * @param currencyCodeFile the ISO Currency Code to construct, defaults to USD
83  * @param language the language to use for translations, default to the Locale language
84  *
85  */
86  KDELIBS4SUPPORT_DEPRECATED explicit KCurrencyCode(const QFileInfo &currencyCodeFile, const QString &language = QString());
87 
88  /**
89  * Copy Constructor
90  *
91  * @param rhs KCurrencyCode to copy
92  *
93  */
94  KCurrencyCode(const KCurrencyCode &rhs);
95 
96  /**
97  * Destructor.
98  */
99  virtual ~KCurrencyCode();
100 
101  /**
102  * Assignment operator
103  *
104  * @param rhs KCurrencyCode to assign
105  *
106  */
107  KCurrencyCode &operator=(const KCurrencyCode &rhs);
108 
109  /**
110  * Return the ISO 4217 Currency Code in Alpha 3 format, e.g. USD
111  *
112  * @return the ISO Currency Code
113  *
114  * @see isoCurrencyCodeNumeric()
115  */
116  QString isoCurrencyCode() const;
117 
118  /**
119  * Return the ISO 4217 Currency Code in Numeric 3 format, e.g. 840
120  *
121  * @return the ISO Currency Code
122  *
123  * @see isoCurrencyCode()
124  */
125  QString isoCurrencyCodeNumeric() const;
126 
127  /**
128  * Return translated Currency Code Name in a standard display format
129  * e.g. United States Dollar
130  *
131  * @return the display Currency Code Name
132  *
133  * @see isoName()
134  */
135  QString name() const;
136 
137  /**
138  * Return untranslated official ISO Currency Code Name
139  *
140  * This name is not translated and should only be used where appropriate.
141  * For displaying the name to a user, use name() instead.
142  *
143  * @return the official ISO Currency Code Name
144  *
145  * @see name()
146  */
147  QString isoName() const;
148 
149  /**
150  * Return Currency Status for the currency, if Active, Suspended or Obsolete
151  *
152  * @return the Currency Status
153  *
154  * @see CurrencyStatus
155  */
156  CurrencyStatus status() const;
157 
158  /**
159  * Return the date the currency was introduced
160  *
161  * @return the date the currency was introduced
162  *
163  * @see status()
164  * @see dateSuspended()
165  * @see dateWithdrawn()
166  */
167  QDate dateIntroduced() const;
168 
169  /**
170  * Return the date the currency was suspended
171  *
172  * @return the date the currency was suspended, QDate() if active
173  *
174  * @see status()
175  * @see dateIntroduced()
176  * @see dateWithdrawn()
177  */
178  QDate dateSuspended() const;
179 
180  /**
181  * Return the date the currency was withdrawn from circulation
182  *
183  * @return the date the currency was withdrawn, QDate() if active
184  *
185  * @see status()
186  * @see dateIntroduced()
187  * @see dateSuspended()
188  */
189  QDate dateWithdrawn() const;
190 
191  /**
192  * Return a list of valid Symbols for the Currency in order of preference
193  *
194  * This list will normally contain the Default and Unambiguous symbols and the ISO Currency Code
195  *
196  * @return list of Currency Symbols
197  *
198  * @see defaultSymbol()
199  * @see unambiguousSymbol()
200  */
201  QStringList symbolList() const;
202 
203  /**
204  * Return the default Symbol for the Currency, e.g. $ or £
205  *
206  * @return the default Currency Symbol
207  *
208  * @see symbols()
209  * @see unambiguousSymbol()
210  */
211  QString defaultSymbol() const;
212 
213  /**
214  * Return the unambiguous Symbol for the Currency, e.g. US$ or NZ$
215  *
216  * @return the unambiguous Currency Symbol
217  *
218  * @see symbols()
219  * @see defaultSymbol()
220  */
221  QString unambiguousSymbol() const;
222 
223  /**
224  * Return if the Currency has subunits or not,
225  * e.g. USD has cents, VUV has none
226  *
227  * @return true if the Currency has subunits
228  *
229  * @see hasSubunitsInCirculation()
230  * @see subunitName()
231  * @see subunitSymbol()
232  * @see subunitsPerUnit()
233  */
234  bool hasSubunits() const;
235 
236  /**
237  * Return if the Currency has subunits in circulation,
238  * e.g. JPY has sen but these are no longer used due to inflation
239  *
240  * @return true if the Currency has subunits in circulation
241  *
242  * @see hasSubunits()
243  */
244  bool hasSubunitsInCirculation() const;
245 
246  /**
247  * Return the Currency subunit symbol if it has one
248  * e.g. ¢ for USD cent
249  *
250  * @return the currency subunit symbol
251  *
252  * @see hasSubunits()
253  */
254  QString subunitSymbol() const;
255 
256  /**
257  * Return the number of subunits in every unit, e.g. 100 cents in the dollar
258  *
259  * @return number of subunits per unit, 0 if no subunits
260  *
261  * @see hasSubunits()
262  */
263  int subunitsPerUnit() const;
264 
265  /**
266  * Return the number of decimal places required to display the currency subunits
267  *
268  * @return number of decimal places
269  */
270  int decimalPlaces() const;
271 
272  /**
273  * Return a list of countries known to be using the currency
274  *
275  * @return list of ISO Country Codes using the currency
276  */
277  QStringList countriesUsingCurrency() const;
278 
279  /**
280  * Return if the currency object loaded/initialised correctly
281  *
282  * @return true if valid KCurrencyCode object
283  */
284  bool isValid() const;
285 
286  /**
287  * Return if a given Currency Code is supported in KDE.
288  * Optionally validate if an Active, Suspended, or Obsolete currency, default is if any.
289  *
290  * @param currencyCode the Currency Code to validate
291  * @param currencyStatus the CurrencyStatus to validate
292  *
293  * @return true if valid currency code
294  */
295  static bool isValid(const QString &currencyCode, CurrencyStatusFlags currencyStatus =
296  CurrencyStatusFlags(ActiveCurrency |
297  SuspendedCurrency |
298  ObsoleteCurrency));
299 
300  /**
301  * Provides list of all known ISO Currency Codes.
302  *
303  * Use currencyCodeToName(currencyCode) to get human readable, localized currency names.
304  *
305  * By default returns all Active, Suspended and Obsolete currencies, set the currencyStatus
306  * flags as appropriate to return required status currencies
307  *
308  * @param currencyStatus which status currencies to return
309  *
310  * @return a list of all ISO Currency Codes
311  *
312  * @see currencyCodeToName
313  */
314  static QStringList allCurrencyCodesList(CurrencyStatusFlags currencyStatus =
315  CurrencyStatusFlags(ActiveCurrency |
316  SuspendedCurrency |
317  ObsoleteCurrency));
318 
319  /**
320  * Convert a known ISO Currency Code to a human readable, localized form.
321  *
322  * If an unknown Currency Code is supplied, empty string is returned;
323  * this will never happen if the code has been obtained by one of the
324  * KCurrencyCode methods.
325  *
326  * @param currencyCode the ISO Currency Code
327  * @param language the language to use for translations, default to the Locale language
328  *
329  * @return the human readable and localized form of the Currency name
330  *
331  * @see currencyCode
332  * @see allCurrencyCodesList
333  */
334  static QString currencyCodeToName(const QString &currencyCode, const QString &language = QString());
335 
336 private:
337  QSharedDataPointer<KCurrencyCodePrivate> d;
338 };
339 
340 Q_DECLARE_OPERATORS_FOR_FLAGS(KCurrencyCode::CurrencyStatusFlags)
341 
342 #endif // KCURRENCYCODE_H
CurrencyStatus
The Status of the Currency.
Definition: kcurrencycode.h:57
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Jul 31 2021 23:00:31 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.