File indexing completed on 2024-02-18 14:56:15

0001 /* This file is part of the KDE libraries
0002     Copyright (C) 1997 Stephan Kulow <coolo@kde.org>
0003     Copyright (C) 1999-2003 Hans Petter Bieker <bieker@kde.org>
0004     Copyright (c) 2002 Lukas Tinkl <lukas@kde.org>
0005 
0006     This library is free software; you can redistribute it and/or
0007     modify it under the terms of the GNU Library General Public
0008     License as published by the Free Software Foundation; either
0009     version 2 of the License, or (at your option) any later version.
0010 
0011     This library is distributed in the hope that it will be useful,
0012     but WITHOUT ANY WARRANTY; without even the implied warranty of
0013     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014     Library General Public License for more details.
0015 
0016     You should have received a copy of the GNU Library General Public License
0017     along with this library; see the file COPYING.LIB.  If not, write to
0018     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0019     Boston, MA 02110-1301, USA.
0020 */
0021 #ifndef KLOCALE_H
0022 #define KLOCALE_H
0023 
0024 #include <kdelibs4support_export.h>
0025 #include <ksharedconfig.h>
0026 
0027 // Include for providing source code compatibility
0028 #include <klocalizedstring.h>
0029 
0030 #include <QString>
0031 #include <QList>
0032 
0033 class QStringList;
0034 class QTextCodec;
0035 class QDate;
0036 class QTime;
0037 class QDateTime;
0038 
0039 class KDateTime;
0040 class KCalendarSystem;
0041 class KCurrencyCode;
0042 class KDayPeriod;
0043 
0044 class KLocalePrivate;
0045 
0046 /**
0047  * \file klocale.h
0048  */
0049 
0050 /**
0051   * KLocale provides support for language and country specific stuff.
0052   *
0053   * KLocale supports specifying the format
0054   * for numbers, currency, time, and date.
0055   *
0056   * Use KLocale::global() to get pointer to the global KLocale object,
0057   * containing the applications current locale settings.
0058   *
0059   * For example, to format the date May 17, 1995 in the current locale, use:
0060   *
0061   * \code
0062   *   QString date = KLocale::global()->formatDate(QDate(1995,5,17));
0063   * \endcode
0064   *
0065   * @author Stephan Kulow <coolo@kde.org>, Preston Brown <pbrown@kde.org>,
0066   * Hans Petter Bieker <bieker@kde.org>, Lukas Tinkl <lukas.tinkl@suse.cz>
0067   * @short class for supporting locale settings
0068   *
0069   * @deprecated since 5.0. For translation support use KLocalizedString (from the
0070   * KI18n framework); for string formatting use QLocale() or KFormat (from the
0071   * KCoreAddons framework) if QLocale doesn't provide the formatting you need.
0072   * For more information about porting code that is still using KLocale see:
0073   * https://community.kde.org/Frameworks/Porting_Notes#Localization
0074   */
0075 class KDELIBS4SUPPORT_EXPORT KLocale
0076 {
0077 public:
0078     /**
0079      * Constructs a KLocale.
0080      *
0081      * The constructor looks for entries Language and Country
0082      * in the group Locale in the configuration file.
0083      *
0084      * If no configuration file is specified, it will also look for languages
0085      * and country using the environment variables (KDE_LANG, LC_MESSAGES,
0086      * LC_ALL, LANG), as well as the global configuration file.
0087      *
0088      * If you specify a configuration file, it has to be valid until the KLocale
0089      * object is destroyed.  Note that a setLocale() will be performed on the
0090      * config using the current locale language and country, which may cause
0091      * a sync() and reparseConfiguration() which will save any changes
0092      * you have made and load any changes other shared copies have made.
0093      *
0094      * @param config  a configuration file with a Locale group detailing
0095      *                locale-related preferences (such as language, country,
0096      *                and formatting options).
0097      */
0098     KDELIBS4SUPPORT_DEPRECATED explicit KLocale(KSharedConfig::Ptr config = KSharedConfig::Ptr());
0099 
0100     /**
0101      * Constructs a KLocale.
0102      *
0103      * Allows you to override the language and, optionally, the
0104      * country of this locale.
0105      *
0106      * If you specify a configuration file, a setLocale() will be performed on
0107      * the config using the current locale language and country,
0108      * which may cause a sync() and reparseConfiguration() which
0109      * will save any changes you have made.
0110      *
0111      * @param language the ISO Language Code for the locale, e.g. "en" for English
0112      * @param country  the ISO Country Code for the locale, e.g. "US" for USA
0113      * @param config   a configuration file with a Locale group detailing
0114      *                 locale-related preferences (such as language, country,
0115      *                 and formatting options).
0116      */
0117     KLocale(const QString &language, const QString &country = QString(),
0118             KConfig *config = nullptr);
0119 
0120     /**
0121      * Copy constructor
0122      */
0123     KLocale(const KLocale &rhs);
0124 
0125     /**
0126      * Assignment operator
0127      */
0128     KLocale &operator= (const KLocale &rhs);
0129 
0130     /**
0131      * Destructor
0132      */
0133     virtual ~KLocale();
0134 
0135     /**
0136      * Changes the current encoding.
0137      *
0138      * @param mibEnum The mib of the preferred codec
0139      *
0140      * @return True on success.
0141      */
0142     bool setEncoding(int mibEnum);
0143 
0144     /**
0145      * Various positions for where to place the positive or negative
0146      * sign when they are related to a monetary value.
0147      */
0148     enum SignPosition {
0149         /**
0150          * Put parantheses around the quantity, e.g. "$ (217)"
0151          */
0152         ParensAround = 0,
0153         /**
0154          * Prefix the quantity with the sign, e.g. "$ -217"
0155          */
0156         BeforeQuantityMoney = 1,
0157         /**
0158          * Suffix the quanitity with the sign, e.g. "$ 217-"
0159          */
0160         AfterQuantityMoney = 2,
0161         /**
0162          * Prefix the currency symbol with the sign, e.g. "-$ 217"
0163          */
0164         BeforeMoney = 3,
0165         /**
0166          * Suffix the currency symbol with the sign, e.g. "$- 217"
0167          */
0168         AfterMoney = 4
0169     };
0170 
0171     /**
0172      * @since 4.3
0173      *
0174      * The set of digit characters used to display and enter numbers.
0175      */
0176     enum DigitSet {
0177         ArabicDigits,             /**< 0123456789 (European and some Asian
0178                                        languages and western Arabic dialects) */
0179         ArabicIndicDigits,        /**< ٠١٢٣٤٥٦٧٨٩ (eastern Arabic dialects) */
0180         EasternArabicIndicDigits, /**< ۰۱۲۳۴۵۶۷۸۹ (Persian and Urdu) */
0181         DevenagariDigits,         /**< ०१२३४५६७८९ (Hindi) */
0182         BengaliDigits,            /**< ০১২৩৪৫৬৭৮৯ (Bengali and  Assamese) */
0183         GujaratiDigits,           /**< ૦૧૨૩૪૫૬૭૮૯ (Gujarati) */
0184         GurmukhiDigits,           /**< ੦੧੨੩੪੫੬੭੮੯ (Punjabi) */
0185         KannadaDigits,            /**< ೦೧೨೩೪೫೬೭೮೯ (Kannada) */
0186         KhmerDigits,              /**< ០១២៣៤៥៦៧៨៩ (Khmer) */
0187         MalayalamDigits,          /**< ൦൧൨൩൪൫൬൭൮൯ (Malayalam) */
0188         OriyaDigits,              /**< ୦୧୨୩୪୫୬୭୮୯ (Oriya) */
0189         TamilDigits,              /**< ௦௧௨௩௪௫௬௭௮ (Tamil) */
0190         TeluguDigits,             /**< ౦౧౨౩౪౫౬౭౯ (Telugu) */
0191         ThaiDigits                /**< ๐๑๒๓๔๕๖๗๘๙ (Thai) */
0192         // The following Decimal Digit Sets are defined in Unicode but the associated
0193         // languages are not yet translated in KDE, so are not yet enabled.
0194         // The script names are taken from the Unicode standard, the associated
0195         // languages from Wikipedia.
0196         //  BalineseDigits,           /**< ᭐᭑᭒᭓᭔᭕᭖᭗᭘᭙ (Balinese) */
0197         //  ChamDigits,               /**< ꩐꩑꩒꩓꩔꩕꩖꩗꩘꩙ (Cham) */
0198         //  JavaneseDigits,           /**< ꧐꧑꧒꧓꧔꧕꧖꧗꧘꧙ (Javanese) */
0199         //  KayahLiDigits,            /**< ꤀꤁꤂꤃꤄꤅꤆꤇꤈꤉ (Kayah) */
0200         //  LaoDigits,                /**< ໐໑໒໓໔໕໖໗໘໙ (Lao) */
0201         //  LepchaDigits,             /**< ᱀᱁᱂᱃᱄᱅᱆᱇᱈᱉ (Lepcha) */
0202         //  LimbuDigits,              /**< ᥆᥇᥈᥉᥊᥋᥌᥍᥎᥏ (Limbu) */
0203         //  MeeteiMayekDigits,        /**< ꯰꯱꯲꯳꯴꯵꯶꯷꯸꯹ (Meitei) */
0204         //  MongolianDigits,          /**< ᠐᠑᠒᠓᠔᠕᠖᠗᠘᠙ (Mongolian) */
0205         //  MyanmarDigits,            /**< ၀၁၂၃၄၅၆၇၈၉ (Myanmar/Burmese ) */
0206         //  MyanmarShanDigits,        /**< ႐႑႒႓႔႕႖႗႘႙ (Shan) */
0207         //  NewTaiLueDigits,          /**< ᧐᧑᧒᧓᧔᧕᧖᧗᧘᧙ (Tai Lü) */
0208         //  NKoDigits,                /**< ߀߁߂߃߄߅߆߇߈߉ (Mande and N'Ko) */
0209         //  OlChikiDigits,            /**< ᱐᱑᱒᱓᱔᱕᱖᱗᱘᱙ (Santali) */
0210         //  OsmanyaDigits,            /**< ҠҡҢңҤҥҦҧҨҩ (Somali) */
0211         //  SaurashtraDigits,         /**< ꣐꣑꣒꣓꣔꣕꣖꣗꣘꣙ (Saurashtra) */
0212         //  SundaneseDigits,          /**< ᮰᮱᮲᮳᮴᮵᮶᮷᮸᮹ (Sundanese) */
0213         //  TaiThamDigits,            /**< ᪐᪑᪒᪓᪔᪕᪖᪗᪘᪙ (Tai Lü) */
0214         //  TibetanDigits,            /**< ༠༡༢༣༤༥༦༧༨༩ (Tibetan) */
0215         //  VaiDigits,                /**< ꘠꘡꘢꘣꘤꘥꘦꘧꘨꘩ (Vai) */
0216     };
0217 
0218     /**
0219      * @since 4.3
0220      *
0221      * Convert a digit set identifier to a human readable, localized name.
0222      *
0223      * @param digitSet the digit set identifier
0224      * @param withDigits whether to add the digits themselves to the name
0225      *
0226      * @return the human readable and localized name of the digit set
0227      *
0228      * @see DigitSet
0229      */
0230     QString digitSetToName(DigitSet digitSet, bool withDigits = false) const;
0231 
0232     /**
0233      * @since 4.3
0234      *
0235      * Provides list of all known digit set identifiers.
0236      *
0237      * @return list of all digit set identifiers
0238      * @see DigitSet
0239      * @see digitSetToName
0240      */
0241     QList<DigitSet> allDigitSetsList() const;
0242 
0243     /**
0244      * Returns what a decimal point should look like ("." or "," etc.)
0245      * according to the current locale or user settings.
0246      *
0247      * @return The decimal symbol used by locale.
0248      */
0249     QString decimalSymbol() const;
0250 
0251     /**
0252      * Returns what the thousands separator should look
0253      * like ("," or "." etc.)
0254      * according to the current locale or user settings.
0255      *
0256      * @return The thousands separator used by locale.
0257      */
0258     QString thousandsSeparator() const;
0259 
0260     /**
0261      * @since 4.3
0262      *
0263      * Returns the identifier of the digit set used to display numbers.
0264      *
0265      * @return the digit set identifier
0266      * @see DigitSet
0267      * @see digitSetToName
0268      */
0269     DigitSet digitSet() const;
0270 
0271     /**
0272      * @since 4.4
0273      *
0274      * Returns the ISO 4217 Currency Code for the current locale
0275      *
0276      * @return The default ISO Currency Code used by locale.
0277     */
0278     QString currencyCode() const;
0279 
0280     /**
0281      * @since 4.4
0282      *
0283      * Returns the Currency Code object for the current locale
0284      *
0285      * @return The default Currency Code object used by locale.
0286     */
0287     KCurrencyCode *currency() const;
0288 
0289     /**
0290      * Returns what the symbol denoting currency in the current locale
0291      * as as defined by user settings should look like.
0292      *
0293      * @return The default currency symbol used by locale.
0294      */
0295     QString currencySymbol() const;
0296 
0297     /**
0298      * Returns what a decimal point should look like ("." or "," etc.)
0299      * for monetary values, according to the current locale or user
0300      * settings.
0301      *
0302      * @return The monetary decimal symbol used by locale.
0303      */
0304     QString monetaryDecimalSymbol() const;
0305 
0306     /**
0307      * Returns what a thousands separator for monetary values should
0308      * look like ("," or " " etc.) according to the current locale or
0309      * user settings.
0310      *
0311      * @return The monetary thousands separator used by locale.
0312      */
0313     QString monetaryThousandsSeparator() const;
0314 
0315     /**
0316      * Returns what a positive sign should look like ("+", " ", etc.)
0317      * according to the current locale or user settings.
0318      *
0319      * @return The positive sign used by locale.
0320      */
0321     QString positiveSign() const;
0322 
0323     /**
0324      * Returns what a negative sign should look like ("-", etc.)
0325      * according to the current locale or user settings.
0326      *
0327      * @return The negative sign used by locale.
0328      */
0329     QString negativeSign() const;
0330 
0331     /**
0332      * @deprecated use decimalPlaces() or monetaryDecimalPlaces()
0333      *
0334      * The number of fractional digits to include in monetary values (usually 2).
0335      *
0336      * @return Default number of fractional digits used by locale.
0337      */
0338     KDELIBS4SUPPORT_DEPRECATED int fracDigits() const;
0339 
0340     /**
0341      * @since 4.4
0342      *
0343      * The number of decimal places to include in numeric values (usually 2).
0344      *
0345      * @return Default number of numeric decimal places used by locale.
0346      */
0347     int decimalPlaces() const;
0348 
0349     /**
0350      * @since 4.4
0351      *
0352      * The number of decimal places to include in monetary values (usually 2).
0353      *
0354      * @return Default number of monetary decimal places used by locale.
0355      */
0356     int monetaryDecimalPlaces() const;
0357 
0358     /**
0359      * If and only if the currency symbol precedes a positive value,
0360      * this will be true.
0361      *
0362      * @return Where to print the currency symbol for positive numbers.
0363      */
0364     bool positivePrefixCurrencySymbol() const;
0365 
0366     /**
0367      * If and only if the currency symbol precedes a negative value,
0368      * this will be true.
0369      *
0370      * @return True if the currency symbol precedes negative numbers.
0371      */
0372     bool negativePrefixCurrencySymbol() const;
0373 
0374     /**
0375      * Returns the position of a positive sign in relation to a
0376      * monetary value.
0377      *
0378      * @return Where/how to print the positive sign.
0379      * @see SignPosition
0380      */
0381     SignPosition positiveMonetarySignPosition() const;
0382 
0383     /**
0384      * Denotes where to place a negative sign in relation to a
0385      * monetary value.
0386      *
0387      * @return Where/how to print the negative sign.
0388      * @see SignPosition
0389      */
0390     SignPosition negativeMonetarySignPosition() const;
0391 
0392     /**
0393      * @since 4.3
0394      *
0395      * Retuns the digit set used to display monetary values.
0396      *
0397      * @return the digit set identifier
0398      * @see DigitSet
0399      * @see digitSetToName
0400      */
0401     DigitSet monetaryDigitSet() const;
0402 
0403     /**
0404      * Given a double, converts that to a numeric string containing
0405      * the localized monetary equivalent.
0406      *
0407      * e.g. given 123456, return "$ 123,456.00".
0408      *
0409      * If precision isn't specified or is < 0, then the default monetaryDecimalPlaces() is used.
0410      *
0411      * @param num The number we want to format
0412      * @param currency The currency symbol you want.
0413      * @param precision Number of decimal places displayed
0414      *
0415      * @return The number of money as a localized string
0416      * @see monetaryDecimalPlaces()
0417      */
0418     QString formatMoney(double num, const QString &currency = QString(), int precision = -1) const;
0419 
0420     /**
0421      * Given a double, converts that to a numeric string containing
0422      * the localized numeric equivalent.
0423      *
0424      * e.g. given 123456.78F, return "123,456.78" (for some European country).
0425      *
0426      * If precision isn't specified or is < 0, then the default decimalPlaces() is used.
0427      *
0428      * This function is a wrapper that is provided for convenience.
0429      *
0430      * @param num The number to convert
0431      * @param precision Number of decimal places used.
0432      *
0433      * @return The number as a localized string
0434      * @see formatNumber(const QString, bool, int)
0435      * @see decimalPlaces()
0436      */
0437     QString formatNumber(double num, int precision = -1) const;
0438 
0439     /**
0440      * Given a string representing a number, converts that to a numeric
0441      * string containing the localized numeric equivalent.
0442      *
0443      * e.g. given 123456.78F, return "123,456.78" (for some European country).
0444      *
0445      * If precision isn't specified or is < 0, then the default decimalPlaces() is used.
0446      *
0447      * @param numStr The number to format, as a string.
0448      * @param round Round fractional digits. (default true)
0449      * @param precision Number of fractional digits used for rounding. Unused if round=false.
0450      *
0451      * @return The number as a localized string
0452      */
0453     QString formatNumber(const QString &numStr, bool round = true, int precision = -1) const;
0454 
0455     /**
0456      * Given an integer, converts that to a numeric string containing
0457      * the localized numeric equivalent.
0458      *
0459      * e.g. given 123456L, return "123,456" (for some European country).
0460      *
0461      * @param num The number to convert
0462      *
0463      * @return The number as a localized string
0464      */
0465     QString formatLong(long num) const;
0466 
0467     /**
0468      * These binary units are used in KDE by the formatByteSize()
0469      * functions.
0470      *
0471      * NOTE: There are several different units standards:
0472      * 1) SI  (i.e. metric), powers-of-10.
0473      * 2) IEC, powers-of-2, with specific units KiB, MiB, etc.
0474      * 3) JEDEC, powers-of-2, used for solid state memory sizing which
0475      *    is why you see flash cards labels as e.g. 4GB.  These (ab)use
0476      *    the metric units.  Although JEDEC only defines KB, MB, GB, if
0477      *    JEDEC is selected all units will be powers-of-2 with metric
0478      *    prefixes for clarity in the event of sizes larger than 1024 GB.
0479      *
0480      * Although 3 different dialects are possible this enum only uses
0481      * metric names since adding all 3 different names of essentially the same
0482      * unit would be pointless.  Use BinaryUnitDialect to control the exact
0483      * units returned.
0484      *
0485      * @since 4.4
0486      * @see binaryUnitDialect
0487      */
0488     enum BinarySizeUnits {
0489         /// Auto-choose a unit such that the result is in the range [0, 1000 or 1024)
0490         DefaultBinaryUnits = -1,
0491 
0492         // The first real unit must be 0 for the current implementation!
0493         UnitByte,      ///<  B         1 byte
0494         UnitKiloByte,  ///<  KiB/KB/kB 1024/1000 bytes.
0495         UnitMegaByte,  ///<  MiB/MB/MB 2^20/10^06 bytes.
0496         UnitGigaByte,  ///<  GiB/GB/GB 2^30/10^09 bytes.
0497         UnitTeraByte,  ///<  TiB/TB/TB 2^40/10^12 bytes.
0498         UnitPetaByte,  ///<  PiB/PB/PB 2^50/10^15 bytes.
0499         UnitExaByte,   ///<  EiB/EB/EB 2^60/10^18 bytes.
0500         UnitZettaByte, ///<  ZiB/ZB/ZB 2^70/10^21 bytes.
0501         UnitYottaByte, ///<  YiB/YB/YB 2^80/10^24 bytes.
0502         UnitLastUnit = UnitYottaByte
0503     };
0504 
0505     /**
0506      * This enum chooses what dialect is used for binary units.
0507      *
0508      * Note: Although JEDEC abuses the metric prefixes and can therefore be
0509      * confusing, it has been used to describe *memory* sizes for quite some time
0510      * and programs should therefore use either Default, JEDEC, or IEC 60027-2
0511      * for memory sizes.
0512      *
0513      * On the other hand network transmission rates are typically in metric so
0514      * Default, Metric, or IEC (which is unambiguous) should be chosen.
0515      *
0516      * Normally choosing DefaultBinaryDialect is the best option as that uses
0517      * the user's selection for units.
0518      *
0519      * @since 4.4
0520      * @see binaryUnitDialect
0521      * @see setBinaryUnitDialect
0522      */
0523     enum BinaryUnitDialect {
0524         DefaultBinaryDialect = -1, ///< Used if no specific preference
0525         IECBinaryDialect,          ///< KDE Default, KiB, MiB, etc. 2^(10*n)
0526         JEDECBinaryDialect,        ///< KDE 3.5 default, KB, MB, etc. 2^(10*n)
0527         MetricBinaryDialect,       ///< SI Units, kB, MB, etc. 10^(3*n)
0528         LastBinaryDialect = MetricBinaryDialect
0529     };
0530 
0531     /**
0532      * Converts @p size from bytes to the string representation using the
0533      * user's default binary unit dialect.  The default unit dialect is
0534      * IEC 60027-2.
0535      *
0536      * Example:
0537      * formatByteSize(1024) returns "1.0 KiB" by default.
0538      *
0539      * @param  size  size in bytes
0540      * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB
0541      * @see BinaryUnitDialect
0542      * @todo KDE 5: Remove in favor of overload added in KDE 4.4.
0543      */
0544     QString formatByteSize(double size) const;
0545 
0546     /**
0547      * @since 4.4
0548      *
0549      * Converts @p size from bytes to the appropriate string representation
0550      * using the binary unit dialect @p dialect and the specific units @p specificUnit.
0551      *
0552      * Example:
0553      * formatByteSize(1000, unit, KLocale::UnitKiloByte) returns:
0554      *   for KLocale::MetricBinaryDialect, "1.0 kB",
0555      *   for KLocale::IECBinaryDialect,    "0.9 KiB",
0556      *   for KLocale::JEDECBinaryDialect,  "0.9 KB".
0557      *
0558      * @param size size in bytes
0559      * @param precision number of places after the decimal point to use.  KDE uses
0560      *        1 by default so when in doubt use 1.
0561      * @param dialect binary unit standard to use.  Use DefaultBinaryDialect to
0562      *        use the localized user selection unless you need to use a specific
0563      *        unit type (such as displaying a flash memory size in JEDEC).
0564      * @param specificUnit specific unit size to use in result.  Use
0565      *        DefaultBinaryUnits to automatically select a unit that will return
0566      *        a sanely-sized number.
0567      * @return converted size as a translated string including the units.
0568      *         E.g. "1.23 KiB", "2 GB" (JEDEC), "4.2 kB" (Metric).
0569      * @see BinaryUnitDialect
0570      */
0571     QString formatByteSize(double size, int precision,
0572                            BinaryUnitDialect dialect = KLocale::DefaultBinaryDialect,
0573                            BinarySizeUnits specificUnit = KLocale::DefaultBinaryUnits) const;
0574 
0575     /**
0576      * Returns the user's configured binary unit dialect.
0577      * e.g. if MetricBinaryDialect is returned then the values
0578      * configured for how much a set of bytes are worth would
0579      * be 10^(3*n) and KB (1000 bytes == 1 KB), in this case.
0580      *
0581      * Will never return DefaultBinaryDialect.
0582      *
0583      * @since 4.4
0584      * @return User's configured binary unit dialect
0585      * @see BinaryUnitDialect
0586      */
0587     BinaryUnitDialect binaryUnitDialect() const;
0588 
0589     /**
0590      * Sets @p newDialect to be the default dialect for this locale (and only
0591      * this locale).  Newly created KLocale objects will continue to default
0592      * to the user's choice.
0593      *
0594      * @param newDialect the new dialect to set as default for this locale object.
0595      * @since 4.4
0596      */
0597     void setBinaryUnitDialect(BinaryUnitDialect newDialect);
0598 
0599     /**
0600      * Given a number of milliseconds, converts that to a string containing
0601      * the localized equivalent
0602      *
0603      * e.g. given formatDuration(60000), returns "1.0 minutes"
0604      *
0605      * @param mSec Time duration in milliseconds
0606      * @return converted duration as a string - e.g. "5.5 seconds" "23.0 minutes"
0607      */
0608     QString formatDuration(unsigned long mSec) const;
0609 
0610     /**
0611      * Given a number of milliseconds, converts that to a pretty string containing
0612      * the localized equivalent.
0613      *
0614      * e.g. given prettyFormatDuration(60001) returns "1 minute"
0615      *      given prettyFormatDuration(62005) returns "1 minute and 2 seconds"
0616      *      given prettyFormatDuration(90060000) returns "1 day and 1 hour"
0617      *
0618      * @param mSec Time duration in milliseconds
0619      * @return converted duration as a string.
0620      *         Units not interesting to the user, for example seconds or minutes when the first
0621      *         unit is day, are not returned because they are irrelevant. The same applies for
0622      *         seconds when the first unit is hour.
0623      * @since 4.2
0624      */
0625     QString prettyFormatDuration(unsigned long mSec) const;
0626 
0627     /**
0628      * @deprecated
0629      *
0630      * Use this to determine whether nouns are declined in
0631      * locale's language. This property should remain
0632      * read-only (no setter function)
0633      *
0634      * @return If nouns are declined
0635      */
0636     KDELIBS4SUPPORT_DEPRECATED bool nounDeclension() const;
0637 
0638     /**
0639      * @since 4.6
0640      *
0641      * Available Calendar Systems
0642      *
0643      * @see setCalendarSystem()
0644      * @see calendarSystem()
0645      */
0646     enum CalendarSystem {
0647         GregorianCalendar = 1, /**< KDE Default, proleptic Gregorian Calendar as used by QDate */
0648         //BahaiCalendar = 2, /**< Baha'i Calendar */
0649         //BuddhistLunarCalendar = 3, /**< Buddhist Lunar Calendar*/
0650         //ChineseCalendar = 4, /**< Chinese Calendar */
0651         CopticCalendar = 5, /**< Coptic Calendar as used Coptic Church and some parts of Egypt */
0652         EthiopianCalendar = 6, /**< Ethiopian Calendar, aka Ethiopic Calendar */
0653         //EthiopianAmeteAlemCalendar = 7, /**< Ethiopian Amete Alem version, aka Ethiopic Amete Alem */
0654         HebrewCalendar = 9, /**< Hebrew Calendar, aka Jewish Calendar */
0655         //HinduCalendar = 10, /**< Hindu Lunar Calendar */
0656         //IslamicLunarCalendar = 11, /**< Islamic Lunar Calendar */
0657         IslamicCivilCalendar = 12, /**< Islamic Civil Calendar, aka Hijri, not the Lunar Calendar */
0658         //IslamicUmAlQuraCalendar = 13, /**< Islamic Lunar Calendar, Um Al Qura varient used in Saudi Arabia */
0659         IndianNationalCalendar = 14, /**< Indian National Calendar, not the Lunar Calendar */
0660         //Iso8601Calendar = 15, /**< ISO 8601 Standard Calendar */
0661         JalaliCalendar = 16, /**< Jalali Calendar, aka Persian or Iranian, also used in Afghanistan */
0662         //JalaliBirashkCalendar = 17, /**< Jalali Calendar, Birashk Algorythm variant */
0663         //Jalali33YearCalendar = 18, /**< Jalali Calendar, 33 Year cycle variant */
0664         JapaneseCalendar = 19, /**< Japanese Calendar, Gregorian calculation using Japanese Era (Nengô) */
0665         //JucheCalendar = 20, /**< Juche Calendar, used in North Korea */
0666         JulianCalendar = 21, /**< Julian Calendar, as used in Orthodox Churches */
0667         MinguoCalendar = 22, /**< Minguo Calendar, aka ROC, Republic of China or Taiwanese */
0668         ThaiCalendar = 23, /**< Thai Calendar, aka Buddhist or Thai Buddhist */
0669 
0670         QDateCalendar = GregorianCalendar /**< @deprecated Alias for GregorianCalendar */
0671     };
0672 
0673     /**
0674      * @since 4.6
0675      *
0676      * System used for Week Numbers
0677      *
0678      * @see setWeekNumberSystem()
0679      * @see weekNumberSystem()
0680      */
0681     enum WeekNumberSystem {
0682         DefaultWeekNumber = -1, /**< The system locale default */
0683         IsoWeekNumber     =  0, /**< ISO Week Number */
0684         FirstFullWeek     =  1, /**< Week 1 starts on the first Week Start Day in year ends after 7 days */
0685         FirstPartialWeek  =  2, /**< Week 1 starts Jan 1st ends day before first Week Start Day in year */
0686         SimpleWeek        =  3  /**< Week 1 starts Jan 1st ends after 7 days */
0687     };
0688 
0689     /**
0690      * @since 4.4
0691      *
0692      * Standard used for Date Time Format String
0693      */
0694     enum DateTimeFormatStandard {
0695         KdeFormat,        /**< KDE Standard */
0696         PosixFormat,      /**< POSIX Standard */
0697         UnicodeFormat     /**< UNICODE Standard (Qt/Java/OSX/Windows) */
0698     };
0699 
0700     /**
0701      * @since 4.6
0702      *
0703      * Mode to use when parsing a Date Time input string
0704      */
0705     enum DateTimeParseMode {
0706         LiberalParsing   /**< Parse Date/Time liberally.  So long as the
0707                                input string contains at least a reconizable
0708                                month and day the input will be accepted. */
0709         //ModerateParsing, /**< Parse Date/Time with modeate tolerance.
0710         //                      The date components in the format must all
0711         //                      occur in the input and in the same order,
0712         //                      but the spacing and the componants themselves
0713         //                      may vary from the strict format. */
0714         //StrictParsing    /**< Parse Date/Time strictly to the format. */
0715     };
0716 
0717     /**
0718      * @since 4.6
0719      *
0720      * The various Components that make up a Date / Time
0721      * In the future the Components may be combined as flags for dynamic
0722      * generation of Date Formats.
0723      *
0724      * @see KCalendarSystem
0725      * @see KLocalizedDate
0726      * @see DateTimeComponentFormat
0727      */
0728     enum DateTimeComponent {
0729         Year          = 0x1,        /**< The Year portion of a date, may be number or name */
0730         YearName      = 0x2,        /**< The Year Name portion of a date */
0731         Month         = 0x4,        /**< The Month portion of a date, may be number or name */
0732         MonthName     = 0x8,        /**< The Month Name portion of a date */
0733         Day           = 0x10,       /**< The Day portion of a date, may be number or name */
0734         DayName       = 0x20,       /**< The Day Name portion of a date */
0735         JulianDay     = 0x40,       /**< The Julian Day of a date */
0736         EraName       = 0x80,       /**< The Era Name portion of a date */
0737         EraYear       = 0x100,      /**< The Era and Year portion of a date */
0738         YearInEra     = 0x200,      /**< The Year In Era portion of a date */
0739         DayOfYear     = 0x400,      /**< The Day Of Year portion of a date, may be number or name */
0740         DayOfYearName = 0x800,      /**< The Day Of Year Name portion of a date */
0741         DayOfWeek     = 0x1000,     /**< The Day Of Week / Weekday portion of a date, may be number or name */
0742         DayOfWeekName = 0x2000,     /**< The Day Of Week Name / Weekday Name portion of a date */
0743         Week          = 0x4000,     /**< The Week Number portion of a date */
0744         WeekYear      = 0x8000,     /**< The Week Year portion of a date */
0745         MonthsInYear  = 0x10000,    /**< The Months In Year portion of a date */
0746         WeeksInYear   = 0x20000,    /**< The Weeks In Year portion of a date */
0747         DaysInYear    = 0x40000,    /**< The Days In Year portion of a date */
0748         DaysInMonth   = 0x80000,    /**< The Days In Month portion of a date */
0749         DaysInWeek    = 0x100000,   /**< The Days In Week portion of a date */
0750         Hour          = 0x200000,   /**< The Hours portion of a date */
0751         Minute        = 0x400000,   /**< The Minutes portion of a date */
0752         Second        = 0x800000,   /**< The Seconds portion of a date */
0753         Millisecond   = 0x1000000,  /**< The Milliseconds portion of a date */
0754         DayPeriod     = 0x2000000,  /**< The Day Period portion of a date, e.g. AM/PM */
0755         DayPeriodHour = 0x4000000,  /**< The Day Period Hour portion of a date */
0756         Timezone      = 0x8000000,  /**< The Time Zone portion of a date, may be offset or name */
0757         TimezoneName  = 0x10000000, /**< The Time Zone Name portion of a date */
0758         UnixTime      = 0x20000000  /**< The UNIX Time portion of a date */
0759     };
0760     Q_DECLARE_FLAGS(DateTimeComponents, DateTimeComponent)
0761 
0762     /**
0763      * @since 4.6
0764      *
0765      * Format used for individual Date/Time Components when converted to/from a string
0766      * Largely equivalent to the UNICODE CLDR format width definitions 1..5
0767      *
0768      * @see DateTimeComponentFormat
0769      */
0770     enum DateTimeComponentFormat {
0771         DefaultComponentFormat = -1, /**< The system locale default for the componant */
0772         ShortNumber = 0,             /**< Number at its natural width, e.g. 2 for the 2nd*/
0773         LongNumber,                  /**< Number padded to a required width, e.g. 02 for the 2nd*/
0774         //OrdinalNumber                /**< Ordinal number format, e.g. "2nd" for the 2nd */
0775         NarrowName = 3,              /**< Narrow text format, may not be unique, e.g. M for Monday */
0776         ShortName,                   /**< Short text format, e.g. Mon for Monday */
0777         LongName                     /**< Long text format, e.g. Monday for Monday */
0778     };
0779 
0780     /**
0781      * Format for date string.
0782      */
0783     enum DateFormat {
0784         ShortDate,        /**< Locale Short date format, e.g. 08-04-2007 */
0785         LongDate,         /**< Locale Long date format, e.g. Sunday 08 April 2007 */
0786         FancyShortDate,   /**< Same as ShortDate for dates a week or more ago. For more
0787                                recent dates, it is represented as Today, Yesterday, or
0788                                the weekday name. */
0789         FancyLongDate,    /**< Same as LongDate for dates a week or more ago. For more
0790                                recent dates, it is represented as Today, Yesterday, or
0791                                the weekday name. */
0792         IsoDate,          /**< ISO-8601 Date format YYYY-MM-DD, e.g. 2009-12-31 */
0793         IsoWeekDate,      /**< ISO-8601 Week Date format YYYY-Www-D, e.g. 2009-W01-1 */
0794         IsoOrdinalDate    /**< ISO-8601 Ordinal Date format YYYY-DDD, e.g. 2009-001 */
0795     };
0796 
0797     /**
0798      * Returns a string formatted to the current locale's conventions
0799      * regarding dates.
0800      *
0801      * @param date the date to be formatted
0802      * @param format category of date format to use
0803      *
0804      * @return the date as a string
0805      */
0806     QString formatDate(const QDate &date, DateFormat format = LongDate) const;
0807 
0808     /**
0809      * Returns a string formatted to the current locale's conventions
0810      * regarding both date and time.
0811      *
0812      * @param dateTime the date and time to be formatted
0813      * @param format category of date format to use
0814      * @param includeSecs if @c true, the string will include the seconds part
0815      *                    of the time; otherwise, the seconds will be omitted
0816      *
0817      * @return the date and time as a string
0818      */
0819     QString formatDateTime(const QDateTime &dateTime, DateFormat format = ShortDate,
0820                            bool includeSecs = false) const;
0821 
0822     /**
0823      * Options for formatting date-time values.
0824      */
0825     enum DateTimeFormatOption {
0826         TimeZone = 0x01,    /**< Include a time zone string */
0827         Seconds  = 0x02     /**< Include the seconds value */
0828     };
0829     Q_DECLARE_FLAGS(DateTimeFormatOptions, DateTimeFormatOption)
0830 
0831     /**
0832      * Returns a string formatted to the current locale's conventions
0833      * regarding both date and time.
0834      *
0835      * @param dateTime the date and time to be formatted
0836      * @param format category of date format to use
0837      * @param options additional output options
0838      *
0839      * @return The date and time as a string
0840      */
0841     QString formatDateTime(const KDateTime &dateTime, DateFormat format = ShortDate,
0842                            DateTimeFormatOptions options = {}) const;
0843 
0844     /**
0845      * Use this to determine whether in dates a possessive form of month
0846      * name is preferred ("of January" rather than "January")
0847      *
0848      * @return If possessive form should be used
0849     */
0850     bool dateMonthNamePossessive() const;
0851 
0852     /**
0853      * @deprecated replaced by formatLocaleTime()
0854      *
0855      * Returns a string formatted to the current locale's conventions
0856      * regarding times.
0857      *
0858      * @param pTime The time to be formatted.
0859      * @param includeSecs if true, seconds are included in the output,
0860      *        otherwise only hours and minutes are formatted.
0861      * @param isDuration if true, the given time is a duration, not a clock time.
0862      * This means "am/pm" shouldn't be displayed.
0863      *
0864      * @return The time as a string
0865      */
0866     QString formatTime(const QTime &pTime, bool includeSecs = false, bool isDuration = false) const;
0867 
0868     /**
0869      * @since 4.4
0870      *
0871      * Format flags for readLocaleTime() and formatLocaleTime()
0872      */
0873     enum TimeFormatOption {
0874         TimeDefault        = 0x0,   ///< Default formatting using seconds and the format
0875         ///< as specified by the locale.
0876         TimeWithoutSeconds = 0x1,   ///< Exclude the seconds part of the time from display
0877         TimeWithoutAmPm    = 0x2,   ///< Read/format time string without am/pm suffix but
0878         ///< keep the 12/24h format as specified by locale time
0879         ///< format, eg. "07.33.05" instead of "07.33.05 pm" for
0880         ///< time format "%I.%M.%S %p".
0881         TimeDuration       = 0x6,   ///< Read/format time string as duration. This will strip
0882         ///< the am/pm suffix and read/format times with an hour
0883         ///< value of 0-23 hours, eg. "19.33.05" instead of
0884         ///< "07.33.05 pm" for time format "%I.%M.%S %p".
0885         ///< This automatically implies @c TimeWithoutAmPm.
0886         TimeFoldHours      = 0xE    ///< Read/format time string as duration. This will not
0887                              ///< not output the hours part of the duration but will
0888                              ///< add the hours (times sixty) to the number of minutes,
0889                              ///< eg. "70.23" instead of "01.10.23" for time format
0890                              ///< "%I.%M.%S %p".
0891     };
0892     Q_DECLARE_FLAGS(TimeFormatOptions, TimeFormatOption)
0893 
0894     /**
0895      * @since 4.4
0896      *
0897      * Returns a string formatted to the current locale's conventions
0898      * regarding times.
0899      *
0900      * @param pTime the time to be formatted
0901      * @param options format option to use when formatting the time
0902      * @return The time as a string
0903      */
0904     QString formatLocaleTime(const QTime &pTime,
0905                              TimeFormatOptions options = KLocale::TimeDefault) const;
0906 
0907     /**
0908      * @since 4.3
0909      *
0910      * Returns the identifier of the digit set used to display dates and time.
0911      *
0912      * @return the digit set identifier
0913      * @see DigitSet
0914      * @see digitSetToName
0915      */
0916     DigitSet dateTimeDigitSet() const;
0917 
0918     /**
0919      * Use this to determine if the user wants a 12 hour clock.
0920      *
0921      * @return If the user wants 12h clock
0922      * @deprecated. A possible equivalent would be:
0923      * @code
0924      * static bool use12Clock()
0925      * {
0926      *     const QString str = QLocale().timeFormat();
0927      *     // 'A' or 'a' means am/pm is shown (and then 'h' uses 12-hour format)
0928      *     // but 'H' forces a 24-hour format anyway, even with am/pm shown.
0929      *     return str.contains(QLatin1Char('a'), Qt::CaseInsensitive) && !str.contains(QLatin1Char('H'));
0930      * }
0931      * @endcode
0932      */
0933     bool use12Clock() const;
0934 
0935     /**
0936      * @since 4.6
0937      *
0938      * Returns the Day Period matching the time given
0939      *
0940      * @param time the time to return the day period for
0941      * @param format the format to return teh day period in
0942      * @return the Day Period for the given time
0943      */
0944     QString dayPeriodText(const QTime &time, DateTimeComponentFormat format = DefaultComponentFormat) const;
0945 
0946     /**
0947      * Use this to determine which day is the first day of the week.
0948      *
0949      * @return an integer (Monday=1..Sunday=7)
0950      */
0951     int weekStartDay() const;
0952 
0953     /**
0954      * Use this to determine which day is the first working day of the week.
0955      *
0956      * @since 4.2
0957      * @return an integer (Monday=1..Sunday=7)
0958      */
0959     int workingWeekStartDay() const;
0960 
0961     /**
0962      * Use this to determine which day is the last working day of the week.
0963      *
0964      * @since 4.2
0965      * @return an integer (Monday=1..Sunday=7)
0966      */
0967     int workingWeekEndDay() const;
0968 
0969     /**
0970      * Use this to determine which day is reserved for religious observance
0971      *
0972      * @since 4.2
0973      * @return day number (None = 0, Monday = 1, ..., Sunday = 7)
0974      */
0975     int weekDayOfPray() const;
0976 
0977     /**
0978      * Returns a pointer to the calendar system object.
0979      *
0980      * @return the current calendar system instance
0981      */
0982     const KCalendarSystem *calendar() const;
0983 
0984     /**
0985      * @deprecated use calendarSystem() instead
0986      *
0987      * Returns the name of the calendar system that is currently being
0988      * used by the system.
0989      *
0990      * @see calendarSystem()
0991      * @return the name of the calendar system
0992      */
0993     KDELIBS4SUPPORT_DEPRECATED QString calendarType() const;
0994 
0995     /**
0996      * @since 4.6
0997      *
0998      * Returns the type of Calendar System used in this Locale
0999      *
1000      * @see KLocale::CalendarSystem
1001      * @see KCalendarSystem
1002      * @return the type of Calendar System
1003      */
1004     KLocale::CalendarSystem calendarSystem() const;
1005 
1006     /**
1007      * @deprecated use setCalendarSystem() instead
1008      *
1009      * Changes the current calendar system to the calendar specified.
1010      * If the calendar system specified is not found, gregorian will be used.
1011      *
1012      * @see setCalendarSystem()
1013      * @param calendarType the name of the calendar type
1014      */
1015     KDELIBS4SUPPORT_DEPRECATED void setCalendar(const QString &calendarType);
1016 
1017     /**
1018      * @since 4.6
1019      *
1020      * Sets the type of Calendar System to use in this Locale
1021      *
1022      * @see KLocale::CalendarSystem
1023      * @see KCalendarSystem
1024      * @param calendarSystem the Calendar System to use
1025      */
1026     void setCalendarSystem(KLocale::CalendarSystem calendarSystem);
1027 
1028     /**
1029      * @since 4.6
1030      *
1031      * Sets the type of Week Number System to use in this Locale
1032      *
1033      * @see Klocale::WeekNumberSystem
1034      * @see weekNumberSystem()
1035      * @param weekNumberSystem the Week Number System to use
1036      */
1037     void setWeekNumberSystem(KLocale::WeekNumberSystem weekNumberSystem);
1038 
1039     /**
1040      * @since 4.6
1041      *
1042      * Returns the type of Week Number System used in this Locale
1043      *
1044      * @see Klocale::WeekNumberSystem
1045      * @see setWeekNumberSystem()
1046      * @returns the Week Number System used
1047      */
1048     KLocale::WeekNumberSystem weekNumberSystem();
1049 
1050     /**
1051      * @since 4.7
1052      *
1053      * Returns the type of Week Number System used in this Locale
1054      *
1055      * @see Klocale::WeekNumberSystem
1056      * @see setWeekNumberSystem()
1057      * @returns the Week Number System used
1058      */
1059     KLocale::WeekNumberSystem weekNumberSystem() const;
1060 
1061     /**
1062      * Converts a localized monetary string to a double.
1063      *
1064      * @param numStr the string we want to convert.
1065      * @param ok the boolean that is set to false if it's not a number.
1066      *           If @p ok is 0, it will be ignored
1067      *
1068      * @return The string converted to a double
1069      */
1070     double readMoney(const QString &numStr, bool *ok = nullptr) const;
1071 
1072     /**
1073      * Converts a localized numeric string to a double.
1074      *
1075      * @param numStr the string we want to convert.
1076      * @param ok the boolean that is set to false if it's not a number.
1077      *           If @p ok is 0, it will be ignored
1078      *
1079      * @return The string converted to a double
1080      */
1081     double readNumber(const QString &numStr, bool *ok = nullptr) const;
1082 
1083     /**
1084      * Converts a localized date string to a QDate.  This method will try all
1085      * ReadDateFlag formats in preferred order to read a valid date.
1086      *
1087      * The bool pointed by ok will be invalid if the date entered was not valid.
1088      *
1089      * @param str the string we want to convert.
1090      * @param ok the boolean that is set to false if it's not a valid date.
1091      *           If @p ok is 0, it will be ignored
1092      *
1093      * @return The string converted to a QDate
1094      * @see KCalendarSystem::readDate()
1095      */
1096     QDate readDate(const QString &str, bool *ok = nullptr) const;
1097 
1098     /**
1099      * Converts a localized date string to a QDate, using the specified format.
1100      * You will usually not want to use this method.
1101      * @see KCalendarSystem::readDate()
1102      */
1103     QDate readDate(const QString &intstr, const QString &fmt, bool *ok = nullptr) const;
1104 
1105     /**
1106      * Flags for readDate()
1107      */
1108     enum ReadDateFlags {
1109         NormalFormat          =    1, /**< Only accept a date string in
1110                                            the locale LongDate format */
1111         ShortFormat           =    2, /**< Only accept a date string in
1112                                            the locale ShortDate format */
1113         IsoFormat             =    4, /**< Only accept a date string in
1114                                            ISO date format (YYYY-MM-DD) */
1115         IsoWeekFormat         =    8, /**< Only accept a date string in
1116                                            ISO Week date format (YYYY-Www-D) */
1117         IsoOrdinalFormat      =   16  /**< Only accept a date string in
1118                                            ISO Week date format (YYYY-DDD) */
1119     };
1120 
1121     /**
1122      * Converts a localized date string to a QDate.
1123      * This method is stricter than readDate(str,&ok): it will only accept
1124      * a date in a specific format, depending on @p flags.
1125      *
1126      * @param str the string we want to convert.
1127      * @param flags what format the the date string will be in
1128      * @param ok the boolean that is set to false if it's not a valid date.
1129      *           If @p ok is 0, it will be ignored
1130      *
1131      * @return The string converted to a QDate
1132      * @see KCalendarSystem::readDate()
1133      */
1134     QDate readDate(const QString &str, ReadDateFlags flags, bool *ok = nullptr) const;
1135 
1136     /**
1137      * Converts a localized time string to a QTime.
1138      * This method will try to parse it with seconds, then without seconds.
1139      * The bool pointed to by @p ok will be set to false if the time entered was
1140      * not valid.
1141      *
1142      * @param str the string we want to convert.
1143      * @param ok the boolean that is set to false if it's not a valid time.
1144      *           If @p ok is 0, it will be ignored
1145      *
1146      * @return The string converted to a QTime
1147      */
1148     QTime readTime(const QString &str, bool *ok = nullptr) const;
1149 
1150     /**
1151      * Flags for the old version of readTime()
1152      *
1153      * @deprecated replaced by TimeFormatOptions
1154      */
1155     enum ReadTimeFlags {
1156         WithSeconds = 0,    ///< Only accept a time string with seconds. Default (no flag set)
1157         WithoutSeconds = 1  ///< Only accept a time string without seconds.
1158     }; // (maybe use this enum as a bitfield, if adding independent features?)
1159 
1160     /**
1161      * @deprecated replaced readLocaleTime()
1162      *
1163      * Converts a localized time string to a QTime.
1164      * This method is stricter than readTime(str,&ok): it will either accept
1165      * a time with seconds or a time without seconds.
1166      * Use this method when the format is known by the application.
1167      *
1168      * @param str the string we want to convert.
1169      * @param flags whether the time string is expected to contain seconds or not.
1170      * @param ok the boolean that is set to false if it's not a valid time.
1171      *           If @p ok is 0, it will be ignored
1172      *
1173      * @return The string converted to a QTime
1174      */
1175     QTime readTime(const QString &str, ReadTimeFlags flags, bool *ok = nullptr) const;
1176 
1177     /**
1178      * Additional processing options for readLocaleTime().
1179      *
1180      * @remarks This is currently used as an enum but declared as a flag
1181      *          to be extensible
1182      */
1183     enum TimeProcessingOption {
1184         ProcessStrict    = 0x1,    ///< Process time in a strict manner, ie.
1185         ///< a read time string has to exactly match
1186         ///< the defined time format.
1187         ProcessNonStrict = 0x2     ///< Process time in a lax manner, ie.
1188                            ///< allow spaces in the time-format to be
1189                            ///< left out when entering a time string.
1190     };
1191     Q_DECLARE_FLAGS(TimeProcessingOptions, TimeProcessingOption)
1192 
1193     /**
1194      * @since 4.4
1195      *
1196      * Converts a localized time string to a QTime.
1197      * This method is stricter than readTime(str, &ok) in that it will either
1198      * accept a time with seconds or a time without seconds.
1199      *
1200      * @param str the string we want to convert
1201      * @param ok the boolean that is set to false if it's not a valid time.
1202      *           If @p ok is 0, it will be ignored.
1203      * @param options format option to apply when formatting the time
1204      * @param processing if set to @c ProcessStrict, checking will be strict
1205      *               and the read time string has to have the exact time format
1206      *               specified. If set to @c ProcessNonStrict processing the time
1207      *               is lax and spaces in the time string can be left out.
1208      *
1209      * @return The string converted to a QTime
1210      */
1211     QTime readLocaleTime(const QString &str, bool *ok = nullptr,
1212                          TimeFormatOptions options = KLocale::TimeDefault,
1213                          TimeProcessingOptions processing = ProcessNonStrict) const;
1214 
1215     /**
1216      * Returns the language code used by this object.
1217      *
1218      * Use languageCodeToName(language) to get human readable, localized
1219      * language name.
1220      *
1221      * @return the currently used language code
1222      *
1223      * @see languageCodeToName
1224      */
1225     QString language() const;
1226 
1227     /**
1228      * Returns the country code of the country where the user lives.
1229      *
1230      * The returned code complies with the ISO 3166-1 alpha-2 standard,
1231      * except by KDE convention it is returned in lowercase whereas the
1232      * official standard is uppercase.
1233      * See http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for details.
1234      *
1235      * defaultCountry() is returned by default, if no other available,
1236      * this will always be uppercase 'C'.
1237      *
1238      * Use countryCodeToName(country) to get human readable, localized
1239      * country names.
1240      *
1241      * @return the country code for the user
1242      *
1243      * @see countryCodeToName
1244      */
1245     QString country() const;
1246 
1247     /**
1248      * @since 4.6
1249      *
1250      * Returns the Country Division Code of the Country where the user lives.
1251      * When no value is set, then the Country Code will be returned.
1252      *
1253      * The returned code complies with the ISO 3166-2 standard.
1254      * See http://en.wikipedia.org/wiki/ISO_3166-2 for details.
1255      *
1256      * Note that unlike country() this method will return the correct case,
1257      * i.e. normally uppercase..
1258      *
1259      * In KDE 4.6 it is the apps responsibility to obtain a translation for the
1260      * code, translation and other services will be priovided in KDE 4.7.
1261      *
1262      * @return the Country Division Code for the user
1263      * @see setCountryDivisionCode
1264      */
1265     QString countryDivisionCode() const;
1266 
1267     /**
1268      * Returns the language codes selected by user, ordered by decreasing
1269      * priority.
1270      *
1271      * Use languageCodeToName(language) to get human readable, localized
1272      * language name.
1273      *
1274      * @return list of language codes
1275      *
1276      * @see languageCodeToName
1277      */
1278     QStringList languageList() const;
1279 
1280     /**
1281      * @since 4.4
1282      *
1283      * Returns the ISO Currency Codes used in the locale, ordered by decreasing
1284      * priority.
1285      *
1286      * Use KCurrency::currencyCodeToName(currencyCode) to get human readable,
1287      * localized language name.
1288      *
1289      * @return list of ISO Currency Codes
1290      *
1291      * @see currencyCodeToName
1292      */
1293     QStringList currencyCodeList() const;
1294 
1295     /**
1296      * Returns the user's preferred encoding.
1297      *
1298      * @return The name of the preferred encoding
1299      *
1300      * @see codecForEncoding
1301      * @see encodingMib
1302      */
1303     const QByteArray encoding() const;
1304 
1305     /**
1306      * Returns the user's preferred encoding.
1307      *
1308      * @return The Mib of the preferred encoding
1309      *
1310      * @see encoding
1311      * @see codecForEncoding
1312      */
1313     int encodingMib() const;
1314 
1315     /**
1316      * Returns the user's preferred encoding. Should never be NULL.
1317      *
1318      * @return The codec for the preferred encoding
1319      *
1320      * @see encoding
1321      * @see encodingMib
1322      */
1323     QTextCodec *codecForEncoding() const;
1324 
1325     /**
1326      * Returns the file encoding.
1327      *
1328      * @return The Mib of the file encoding
1329      *
1330      * @see QFile::encodeName
1331      * @see QFile::decodeName
1332      */
1333     int fileEncodingMib() const;
1334 
1335     /**
1336      * Changes the current date format.
1337      *
1338      * The format of the date is a string which contains variables that will
1339      * be replaced:
1340      * @li %Y with the whole year (e.g. "2004" for "2004")
1341      * @li %y with the lower 2 digits of the year (e.g. "04" for "2004")
1342      * @li %n with the month (January="1", December="12")
1343      * @li %m with the month with two digits (January="01", December="12")
1344      * @li %e with the day of the month (e.g. "1" on the first of march)
1345      * @li %d with the day of the month with two digits (e.g. "01" on the first of march)
1346      * @li %b with the short form of the month (e.g. "Jan" for January)
1347      * @li %B with the long form of the month (e.g. "January")
1348      * @li %a with the short form of the weekday (e.g. "Wed" for Wednesday)
1349      * @li %A with the long form of the weekday (e.g. "Wednesday" for Wednesday)
1350      *
1351      * Everything else in the format string will be taken as is.
1352      * For example, March 20th 1989 with the format "%y:%m:%d" results
1353      * in "89:03:20".
1354      *
1355      * @param format The new date format
1356      */
1357     void setDateFormat(const QString &format);
1358 
1359     /**
1360      * Changes the current short date format.
1361      *
1362      * The format of the date is a string which contains variables that will
1363      * be replaced:
1364      * @li %Y with the whole year (e.g. "1984" for "1984")
1365      * @li %y with the lower 2 digits of the year (e.g. "84" for "1984")
1366      * @li %n with the month (January="1", December="12")
1367      * @li %m with the month with two digits (January="01", December="12")
1368      * @li %e with the day of the month (e.g. "1" on the first of march)
1369      * @li %d with the day of the month with two digits(e.g. "01" on the first of march)
1370      * @li %b with the short form of the month (e.g. "Jan" for January)
1371      * @li %B with the long form of the month (e.g. "January")
1372      * @li %a with the short form of the weekday (e.g. "Wed" for Wednesday)
1373      * @li %A with the long form of the weekday (e.g. "Wednesday" for Wednesday)
1374      *
1375      * Everything else in the format string will be taken as is.
1376      * For example, March 20th 1989 with the format "%y:%m:%d" results
1377      * in "89:03:20".
1378      *
1379      * @param format The new short date format
1380      */
1381     void setDateFormatShort(const QString &format);
1382 
1383     /**
1384      * Changes the form of month name used in dates.
1385      *
1386      * @param possessive True if possessive forms should be used
1387      */
1388     void setDateMonthNamePossessive(bool possessive);
1389 
1390     /**
1391      * Changes the current time format.
1392      *
1393      * The format of the time is string a which contains variables that will
1394      * be replaced:
1395      * @li %H with the hour in 24h format and 2 digits (e.g. 5pm is "17", 5am is "05")
1396      * @li %k with the hour in 24h format and one digits (e.g. 5pm is "17", 5am is "5")
1397      * @li %I with the hour in 12h format and 2 digits (e.g. 5pm is "05", 5am is "05")
1398      * @li %l with the hour in 12h format and one digits (e.g. 5pm is "5", 5am is "5")
1399      * @li %M with the minute with 2 digits (e.g. the minute of 07:02:09 is "02")
1400      * @li %S with the seconds with 2 digits  (e.g. the minute of 07:02:09 is "09")
1401      * @li %p with pm or am (e.g. 17.00 is "pm", 05.00 is "am")
1402      *
1403      * Everything else in the format string will be taken as is.
1404      * For example, 5.23pm with the format "%H:%M" results
1405      * in "17:23".
1406      *
1407      * @param format The new time format
1408      */
1409     void setTimeFormat(const QString &format);
1410 
1411     /**
1412      * @since 4.3
1413      *
1414      * Set digit characters used to display dates and time.
1415      *
1416      * @param digitSet the digit set identifier
1417      * @see DigitSet
1418      */
1419     void setDateTimeDigitSet(DigitSet digitSet);
1420 
1421     /**
1422      * Changes how KLocale defines the first day in week.
1423      *
1424      * @param day first day of the week (Monday=1..Sunday=7) as integer
1425      */
1426     void setWeekStartDay(int day);
1427 
1428     /**
1429      * Changes how KLocale defines the first working day in week.
1430      *
1431      * @since 4.2
1432      * @param day first working day of the week (Monday=1..Sunday=7) as integer
1433      */
1434     void setWorkingWeekStartDay(int day);
1435 
1436     /**
1437      * Changes how KLocale defines the last working day in week.
1438      *
1439      * @since 4.2
1440      * @param day last working day of the week (Monday=1..Sunday=7) as integer
1441      */
1442     void setWorkingWeekEndDay(int day);
1443 
1444     /**
1445      * Changes how KLocale defines the day reserved for religious observance.
1446      *
1447      * @since 4.2
1448      * @param day day of the week for religious observance (None=0,Monday=1..Sunday=7) as integer
1449      */
1450     void setWeekDayOfPray(int day);
1451 
1452     /**
1453      * Returns the currently selected date format.
1454      *
1455      * @return Current date format.
1456      * @see setDateFormat()
1457      */
1458     QString dateFormat() const;
1459 
1460     /**
1461      * Returns the currently selected short date format.
1462      *
1463      * @return Current short date format.
1464      * @see setDateFormatShort()
1465      */
1466     QString dateFormatShort() const;
1467 
1468     /**
1469      * Returns the currently selected time format.
1470      *
1471      * @return Current time format.
1472      * @see setTimeFormat()
1473      */
1474     QString timeFormat() const;
1475 
1476     /**
1477      * Changes the symbol used to identify the decimal pointer.
1478      *
1479      * @param symbol The new decimal symbol.
1480      */
1481     void setDecimalSymbol(const QString &symbol);
1482 
1483     /**
1484      * Changes the separator used to group digits when formating numbers.
1485      *
1486      * @param separator The new thousands separator.
1487      */
1488     void setThousandsSeparator(const QString &separator);
1489 
1490     /**
1491      * Changes the sign used to identify a positive number. Normally this is
1492      * left blank.
1493      *
1494      * @param sign Sign used for positive numbers.
1495      */
1496     void setPositiveSign(const QString &sign);
1497 
1498     /**
1499      * Changes the sign used to identify a negative number.
1500      *
1501      * @param sign Sign used for negative numbers.
1502      */
1503     void setNegativeSign(const QString &sign);
1504 
1505     /**
1506      * @since 4.3
1507      *
1508      * Changes the set of digit characters used to display numbers.
1509      *
1510      * @param digitSet the digit set identifier
1511      * @see DigitSet
1512      */
1513     void setDigitSet(DigitSet digitSet);
1514 
1515     /**
1516      * Changes the sign position used for positive monetary values.
1517      *
1518      * @param signpos The new sign position
1519      */
1520     void setPositiveMonetarySignPosition(SignPosition signpos);
1521 
1522     /**
1523      * Changes the sign position used for negative monetary values.
1524      *
1525      * @param signpos The new sign position
1526      */
1527     void setNegativeMonetarySignPosition(SignPosition signpos);
1528 
1529     /**
1530      * Changes the position where the currency symbol should be printed for
1531      * positive monetary values.
1532      *
1533      * @param prefix True if the currency symbol should be prefixed instead of
1534      * postfixed
1535      */
1536     void setPositivePrefixCurrencySymbol(bool prefix);
1537 
1538     /**
1539      * Changes the position where the currency symbol should be printed for
1540      * negative monetary values.
1541      *
1542      * @param prefix True if the currency symbol should be prefixed instead of
1543      * postfixed
1544      */
1545     void setNegativePrefixCurrencySymbol(bool prefix);
1546 
1547     /**
1548      * @deprecated use setDecimalPlaces() or setMonetaryDecimalPlaces()
1549      *
1550      * Changes the number of digits used when formating numbers.
1551      *
1552      * @param digits The default number of digits to use.
1553      */
1554     KDELIBS4SUPPORT_DEPRECATED void setFracDigits(int digits);
1555 
1556     /**
1557      * @since 4.4
1558      *
1559      * Changes the number of decimal places used when formating numbers.
1560      *
1561      * @param digits The default number of digits to use.
1562      */
1563     void setDecimalPlaces(int digits);
1564 
1565     /**
1566      * @since 4.4
1567      *
1568      * Changes the number of decimal places used when formating money.
1569      *
1570      * @param digits The default number of digits to use.
1571      */
1572     void setMonetaryDecimalPlaces(int digits);
1573 
1574     /**
1575      * Changes the separator used to group digits when formating monetary values.
1576      *
1577      * @param separator The new thousands separator.
1578      */
1579     void setMonetaryThousandsSeparator(const QString &separator);
1580 
1581     /**
1582      * Changes the symbol used to identify the decimal pointer for monetary
1583      * values.
1584      *
1585      * @param symbol The new decimal symbol.
1586      */
1587     void setMonetaryDecimalSymbol(const QString &symbol);
1588 
1589     /**
1590      * @since 4.4
1591      *
1592      * Changes the current ISO Currency Code.
1593      *
1594      * @param newCurrencyCode The new Currency Code
1595      */
1596     void setCurrencyCode(const QString &newCurrencyCode);
1597 
1598     /**
1599      * Changes the current currency symbol.
1600      *
1601      * This symbol should be consistant with the selected Currency Code
1602      *
1603      * @param symbol The new currency symbol
1604      * @see currencyCode, KCurrency::currencySymbols
1605      */
1606     void setCurrencySymbol(const QString &symbol);
1607 
1608     /**
1609      * @since 4.3
1610      *
1611      * Set digit characters used to display monetary values.
1612      *
1613      * @param digitSet the digit set identifier
1614      * @see DigitSet
1615      */
1616     void setMonetaryDigitSet(DigitSet digitSet);
1617 
1618     /**
1619      * Returns the preferred page size for printing.
1620      *
1621      * @return The preferred page size, cast it to QPrinter::PaperSize
1622      */
1623     int pageSize() const;
1624 
1625     /**
1626      * Changes the preferred page size when printing.
1627      *
1628      * @param paperFormat the new preferred page size in the format QPrinter::PaperSize
1629      */
1630     void setPageSize(int paperFormat);
1631 
1632     /**
1633      * The Metric system will give you information in mm, while the
1634      * Imperial system will give you information in inches.
1635      */
1636     enum MeasureSystem {
1637         Metric,    ///< Metric system (used e.g. in Europe)
1638         Imperial   ///< Imperial system (used e.g. in the United States)
1639     };
1640 
1641     /**
1642      * Returns which measuring system we use.
1643      *
1644      * @return The preferred measuring system
1645      */
1646     MeasureSystem measureSystem() const;
1647 
1648     /**
1649      * Changes the preferred measuring system.
1650      *
1651      * @return value The preferred measuring system
1652      */
1653     void setMeasureSystem(MeasureSystem value);
1654 
1655     /**
1656      * Provides list of all known language codes.
1657      *
1658      * Use languageCodeToName(language) to get human readable, localized
1659      * language names.
1660      *
1661      * @return list of all language codes
1662      *
1663      * @see languageCodeToName
1664      * @see installedLanguages
1665      */
1666     QStringList allLanguagesList() const;
1667 
1668     /**
1669      * @since 4.6
1670      *
1671      * Provides list of all installed KDE Language Translations.
1672      *
1673      * Use languageCodeToName(language) to get human readable, localized
1674      * language names.
1675      *
1676      * @return list of all installed language codes
1677      *
1678      * @see languageCodeToName
1679      */
1680     QStringList installedLanguages() const;
1681 
1682     /**
1683      * Convert a known language code to a human readable, localized form.
1684      * If an unknown language code is supplied, empty string is returned;
1685      * this will never happen if the code has been obtained by one of the
1686      * KLocale methods.
1687      *
1688      * @param language the language code
1689      *
1690      * @return the human readable and localized form if the code is known,
1691      *         empty otherwise
1692      *
1693      * @see language
1694      * @see languageList
1695      * @see allLanguagesList
1696      * @see installedLanguages
1697      */
1698     QString languageCodeToName(const QString &language) const;
1699 
1700     /**
1701      * Provides list of all known country codes.
1702      *
1703      * Use countryCodeToName(country) to get human readable, localized
1704      * country names.
1705      *
1706      * @return a list of all country codes
1707      *
1708      * @see countryCodeToName
1709      */
1710     QStringList allCountriesList() const;
1711 
1712     /**
1713      * Convert a known country code to a human readable, localized form.
1714      *
1715      * If an unknown country code is supplied, empty string is returned;
1716      * this will never happen if the code has been obtained by one of the
1717      * KLocale methods.
1718      *
1719      * @param country the country code
1720      *
1721      * @return the human readable and localized form of the country name
1722      *
1723      * @see country
1724      * @see allCountriesList
1725      */
1726     QString countryCodeToName(const QString &country) const;
1727 
1728     /**
1729      * Parses locale string into distinct parts.
1730      * The format of locale is language_COUNTRY@modifier.CHARSET
1731      *
1732      * @param locale the locale string to split
1733      * @param language set to the language part of the locale
1734      * @param country set to the country part of the locale
1735      * @param modifier set to the modifer part of the locale
1736      * @param charset set to the charset part of the locale
1737      */
1738     static void splitLocale(const QString &locale, QString &language, QString &country,
1739                             QString &modifier, QString &charset);
1740 
1741     /**
1742      * Return the global KLocale instance.
1743      * This is the one used by default by all i18n calls.
1744      *
1745      * Note: in multi-threaded programs, you should call KLocale::global()
1746      * in the main thread (e.g. in main(), after creating the QCoreApplication
1747      * and setting the main component), to ensure that the initialization is
1748      * done in the main thread. However KApplication takes care of this, so this
1749      * is only needed when not using KApplication.
1750      *
1751      * @since 5.0
1752      */
1753     static KLocale *global();
1754 
1755     /**
1756      * Returns the name of the internal language.
1757      *
1758      * @return Name of the default language
1759      */
1760     static QString defaultLanguage();
1761 
1762     /**
1763      * Returns the code of the default country, i.e. "C"
1764      *
1765      * This function will not provide a sensible value to use in your app,
1766      * please use country() instead.
1767      *
1768      * @see country
1769      *
1770      * @return Name of the default country
1771      */
1772     static QString defaultCountry();
1773 
1774     /**
1775      * @since 4.4
1776      *
1777      * Returns the ISO Code of the default currency.
1778      *
1779      * @return ISO Currency Code of the default currency
1780      */
1781     static QString defaultCurrencyCode();
1782 
1783     /**
1784      * Changes the current country. The current country will be left
1785      * unchanged if failed. It will force a reload of the country specific
1786      * configuration.
1787      *
1788      * An empty country value will set the country to the system default.
1789      *
1790      * If you specify a configuration file, a setLocale() will be performed on
1791      * the config using the current locale language, which may cause a sync()
1792      * and reparseConfiguration() which will save any changes you have made.
1793      *
1794      * @param country the ISO 3166 country code
1795      * @param config  a configuration file with a Locale group detailing
1796      *                locale-related preferences (such as language, contry,
1797      *                and formatting options).
1798      *
1799      * @return @c true on success, @c false on failure
1800      */
1801     bool setCountry(const QString &country, KConfig *config);
1802 
1803     /**
1804      * @since 4.6
1805      *
1806      * Sets the Country Division Code of the Country where the user lives.
1807      *
1808      * The code must comply with the ISO 3166-2 standard.
1809      * See http://en.wikipedia.org/wiki/ISO_3166-2 for details.
1810      *
1811      * In KDE 4.6 it is the apps responsibility to validate the input,
1812      * full validation and other services will be provided in KDE 4.7.
1813      *
1814      * @param countryDivision the Country Division Code for the user
1815      * @return @c true on success, @c false on failure
1816      * @see countryDivisionCode
1817      */
1818     bool setCountryDivisionCode(const QString &countryDivision);
1819 
1820     /**
1821      * Changes the current language. The current language will be left
1822      * unchanged if failed. It will force a reload of the country specific
1823      * configuration as well.
1824      *
1825      * If you specify a configuration file, a setLocale() will be performed on
1826      * the config using the current locale language, which may cause a sync()
1827      * and reparseConfiguration() which will save any changes you have made.
1828      *
1829      * @param language the language code
1830      * @param config   a configuration file with a Locale group detailing
1831      *                 locale-related preferences (such as language, country,
1832      *                 and formatting options).
1833      *
1834      * @return true on success
1835      */
1836     bool setLanguage(const QString &language, KConfig *config);
1837 
1838     /**
1839      * Changes the list of preferred languages for the locale. The first valid
1840      * language in the list will be used, or the default language (en_US)
1841      * if none of the specified languages were available.
1842      *
1843      * @param languages the list of language codes
1844      *
1845      * @return true if one of the specified languages were used
1846      */
1847     bool setLanguage(const QStringList &languages);
1848 
1849     /**
1850      * @since 4.3
1851      *
1852      * Convert all digits in the string to the given digit set.
1853      *
1854      * Conversion is normally not performed if the given digit set
1855      * is not appropriate in the current locale and language context.
1856      * Unconditional conversion may be requested by setting
1857      * @p ignoreContext to @c true.
1858      *
1859      * @param str the string to convert
1860      * @param digitSet the digit set identifier
1861      * @param ignoreContext unconditional conversion if @c true
1862      *
1863      * @return string with converted digits
1864      *
1865      * @see DigitSet
1866      */
1867     QString convertDigits(const QString &str, DigitSet digitSet,
1868                           bool ignoreContext = false) const;
1869 
1870     /**
1871      * @since 4.8
1872      *
1873      * Reparse locale configuration files for the current selected
1874      * language.
1875      */
1876     void reparseConfiguration();
1877 
1878 private:
1879     friend class KLocalePrivate;
1880     friend class KLocaleTest;
1881     friend class KDateTimeFormatter;
1882     KLocalePrivate *const d;
1883 };
1884 
1885 Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::DateTimeFormatOptions)
1886 Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::DateTimeComponents)
1887 Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::TimeFormatOptions)
1888 Q_DECLARE_OPERATORS_FOR_FLAGS(KLocale::TimeProcessingOptions)
1889 
1890 #endif