File indexing completed on 2024-10-13 12:11:09
0001 /* 0002 Copyright (c) 2009 John Layt <john@layt.net> 0003 0004 This library is free software; you can redistribute it and/or 0005 modify it under the terms of the GNU Library General Public 0006 License as published by the Free Software Foundation; either 0007 version 2 of the License, or (at your option) any later version. 0008 0009 This library is distributed in the hope that it will be useful, 0010 but WITHOUT ANY WARRANTY; without even the implied warranty of 0011 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0012 Library General Public License for more details. 0013 0014 You should have received a copy of the GNU Library General Public License 0015 along with this library; see the file COPYING.LIB. If not, write to 0016 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0017 Boston, MA 02110-1301, USA. 0018 */ 0019 0020 #ifndef KCURRENCYCODE_H 0021 #define KCURRENCYCODE_H 0022 0023 #include <kdelibs4support_export.h> 0024 0025 #include <QSharedDataPointer> 0026 #include <QString> 0027 0028 class QDate; 0029 class QStringList; 0030 class QFileInfo; 0031 0032 class KCurrencyCodePrivate; 0033 0034 /** 0035 * @since 4.4 0036 * 0037 * This is a class to implement the ISO 4217 Currency Code standard 0038 * 0039 * @b license GNU-LGPL v.2 or later 0040 * 0041 * @see KLocale 0042 * 0043 * @author John Layt <john@layt.net> 0044 * 0045 * @deprecated since 5.0, a replacement will be provided by the KStandards 0046 * framework (not available in KDE Frameworks 5.0) 0047 */ 0048 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KCurrencyCode 0049 { 0050 public: 0051 /** 0052 * The Status of the Currency 0053 * 0054 * @see CurrencyStatusFlags 0055 * @see currencyStatus() 0056 */ 0057 enum CurrencyStatus { 0058 ActiveCurrency = 0x01, /**< Currency is currently in use */ 0059 SuspendedCurrency = 0x02, /**< Currency is not currently in use but has not been replaced */ 0060 ObsoleteCurrency = 0x04 /**< Currency is no longer in use and has been replaced */ 0061 }; 0062 Q_DECLARE_FLAGS(CurrencyStatusFlags, CurrencyStatus) 0063 0064 /** 0065 * Constructs a KCurrencyCode for a given ISO Currency Code. 0066 * 0067 * If the supplied Currency Code is not known then the KCurrencyCode will return isValid() == false 0068 * 0069 * @param isoCurrencyCode the ISO Currency Code to construct, defaults to USD 0070 * @param language the language to use for translations, default to the Locale language 0071 * 0072 */ 0073 KDELIBS4SUPPORT_DEPRECATED explicit KCurrencyCode(const QString &isoCurrencyCode, const QString &language = QString()); 0074 0075 /** 0076 * Constructs a KCurrencyCode for a given config file and Language. 0077 * 0078 * Note that any translations must be supplied in the config file, none will be provided. 0079 * 0080 * If the supplied config file is not valid then the KCurrencyCode will return isValid() == false 0081 * 0082 * @param currencyCodeFile the ISO Currency Code to construct, defaults to USD 0083 * @param language the language to use for translations, default to the Locale language 0084 * 0085 */ 0086 KDELIBS4SUPPORT_DEPRECATED explicit KCurrencyCode(const QFileInfo ¤cyCodeFile, const QString &language = QString()); 0087 0088 /** 0089 * Copy Constructor 0090 * 0091 * @param rhs KCurrencyCode to copy 0092 * 0093 */ 0094 KCurrencyCode(const KCurrencyCode &rhs); 0095 0096 /** 0097 * Destructor. 0098 */ 0099 virtual ~KCurrencyCode(); 0100 0101 /** 0102 * Assignment operator 0103 * 0104 * @param rhs KCurrencyCode to assign 0105 * 0106 */ 0107 KCurrencyCode &operator=(const KCurrencyCode &rhs); 0108 0109 /** 0110 * Return the ISO 4217 Currency Code in Alpha 3 format, e.g. USD 0111 * 0112 * @return the ISO Currency Code 0113 * 0114 * @see isoCurrencyCodeNumeric() 0115 */ 0116 QString isoCurrencyCode() const; 0117 0118 /** 0119 * Return the ISO 4217 Currency Code in Numeric 3 format, e.g. 840 0120 * 0121 * @return the ISO Currency Code 0122 * 0123 * @see isoCurrencyCode() 0124 */ 0125 QString isoCurrencyCodeNumeric() const; 0126 0127 /** 0128 * Return translated Currency Code Name in a standard display format 0129 * e.g. United States Dollar 0130 * 0131 * @return the display Currency Code Name 0132 * 0133 * @see isoName() 0134 */ 0135 QString name() const; 0136 0137 /** 0138 * Return untranslated official ISO Currency Code Name 0139 * 0140 * This name is not translated and should only be used where appropriate. 0141 * For displaying the name to a user, use name() instead. 0142 * 0143 * @return the official ISO Currency Code Name 0144 * 0145 * @see name() 0146 */ 0147 QString isoName() const; 0148 0149 /** 0150 * Return Currency Status for the currency, if Active, Suspended or Obsolete 0151 * 0152 * @return the Currency Status 0153 * 0154 * @see CurrencyStatus 0155 */ 0156 CurrencyStatus status() const; 0157 0158 /** 0159 * Return the date the currency was introduced 0160 * 0161 * @return the date the currency was introduced 0162 * 0163 * @see status() 0164 * @see dateSuspended() 0165 * @see dateWithdrawn() 0166 */ 0167 QDate dateIntroduced() const; 0168 0169 /** 0170 * Return the date the currency was suspended 0171 * 0172 * @return the date the currency was suspended, QDate() if active 0173 * 0174 * @see status() 0175 * @see dateIntroduced() 0176 * @see dateWithdrawn() 0177 */ 0178 QDate dateSuspended() const; 0179 0180 /** 0181 * Return the date the currency was withdrawn from circulation 0182 * 0183 * @return the date the currency was withdrawn, QDate() if active 0184 * 0185 * @see status() 0186 * @see dateIntroduced() 0187 * @see dateSuspended() 0188 */ 0189 QDate dateWithdrawn() const; 0190 0191 /** 0192 * Return a list of valid Symbols for the Currency in order of preference 0193 * 0194 * This list will normally contain the Default and Unambiguous symbols and the ISO Currency Code 0195 * 0196 * @return list of Currency Symbols 0197 * 0198 * @see defaultSymbol() 0199 * @see unambiguousSymbol() 0200 */ 0201 QStringList symbolList() const; 0202 0203 /** 0204 * Return the default Symbol for the Currency, e.g. $ or £ 0205 * 0206 * @return the default Currency Symbol 0207 * 0208 * @see symbols() 0209 * @see unambiguousSymbol() 0210 */ 0211 QString defaultSymbol() const; 0212 0213 /** 0214 * Return the unambiguous Symbol for the Currency, e.g. US$ or NZ$ 0215 * 0216 * @return the unambiguous Currency Symbol 0217 * 0218 * @see symbols() 0219 * @see defaultSymbol() 0220 */ 0221 QString unambiguousSymbol() const; 0222 0223 /** 0224 * Return if the Currency has subunits or not, 0225 * e.g. USD has cents, VUV has none 0226 * 0227 * @return true if the Currency has subunits 0228 * 0229 * @see hasSubunitsInCirculation() 0230 * @see subunitName() 0231 * @see subunitSymbol() 0232 * @see subunitsPerUnit() 0233 */ 0234 bool hasSubunits() const; 0235 0236 /** 0237 * Return if the Currency has subunits in circulation, 0238 * e.g. JPY has sen but these are no longer used due to inflation 0239 * 0240 * @return true if the Currency has subunits in circulation 0241 * 0242 * @see hasSubunits() 0243 */ 0244 bool hasSubunitsInCirculation() const; 0245 0246 /** 0247 * Return the Currency subunit symbol if it has one 0248 * e.g. ¢ for USD cent 0249 * 0250 * @return the currency subunit symbol 0251 * 0252 * @see hasSubunits() 0253 */ 0254 QString subunitSymbol() const; 0255 0256 /** 0257 * Return the number of subunits in every unit, e.g. 100 cents in the dollar 0258 * 0259 * @return number of subunits per unit, 0 if no subunits 0260 * 0261 * @see hasSubunits() 0262 */ 0263 int subunitsPerUnit() const; 0264 0265 /** 0266 * Return the number of decimal places required to display the currency subunits 0267 * 0268 * @return number of decimal places 0269 */ 0270 int decimalPlaces() const; 0271 0272 /** 0273 * Return a list of countries known to be using the currency 0274 * 0275 * @return list of ISO Country Codes using the currency 0276 */ 0277 QStringList countriesUsingCurrency() const; 0278 0279 /** 0280 * Return if the currency object loaded/initialised correctly 0281 * 0282 * @return true if valid KCurrencyCode object 0283 */ 0284 bool isValid() const; 0285 0286 /** 0287 * Return if a given Currency Code is supported in KDE. 0288 * Optionally validate if an Active, Suspended, or Obsolete currency, default is if any. 0289 * 0290 * @param currencyCode the Currency Code to validate 0291 * @param currencyStatus the CurrencyStatus to validate 0292 * 0293 * @return true if valid currency code 0294 */ 0295 static bool isValid(const QString ¤cyCode, CurrencyStatusFlags currencyStatus = 0296 CurrencyStatusFlags(ActiveCurrency | 0297 SuspendedCurrency | 0298 ObsoleteCurrency)); 0299 0300 /** 0301 * Provides list of all known ISO Currency Codes. 0302 * 0303 * Use currencyCodeToName(currencyCode) to get human readable, localized currency names. 0304 * 0305 * By default returns all Active, Suspended and Obsolete currencies, set the currencyStatus 0306 * flags as appropriate to return required status currencies 0307 * 0308 * @param currencyStatus which status currencies to return 0309 * 0310 * @return a list of all ISO Currency Codes 0311 * 0312 * @see currencyCodeToName 0313 */ 0314 static QStringList allCurrencyCodesList(CurrencyStatusFlags currencyStatus = 0315 CurrencyStatusFlags(ActiveCurrency | 0316 SuspendedCurrency | 0317 ObsoleteCurrency)); 0318 0319 /** 0320 * Convert a known ISO Currency Code to a human readable, localized form. 0321 * 0322 * If an unknown Currency Code is supplied, empty string is returned; 0323 * this will never happen if the code has been obtained by one of the 0324 * KCurrencyCode methods. 0325 * 0326 * @param currencyCode the ISO Currency Code 0327 * @param language the language to use for translations, default to the Locale language 0328 * 0329 * @return the human readable and localized form of the Currency name 0330 * 0331 * @see currencyCode 0332 * @see allCurrencyCodesList 0333 */ 0334 static QString currencyCodeToName(const QString ¤cyCode, const QString &language = QString()); 0335 0336 private: 0337 QSharedDataPointer<KCurrencyCodePrivate> d; 0338 }; 0339 0340 Q_DECLARE_OPERATORS_FOR_FLAGS(KCurrencyCode::CurrencyStatusFlags) 0341 0342 #endif // KCURRENCYCODE_H