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 &currencyCodeFile, 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 &currencyCode, 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 &currencyCode, 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