KDELibs4Support

klocale.h
Go to the documentation of this file.
1 /* This file is part of the KDE libraries
2  Copyright (C) 1997 Stephan Kulow <[email protected]>
3  Copyright (C) 1999-2003 Hans Petter Bieker <[email protected]>
4  Copyright (c) 2002 Lukas Tinkl <[email protected]>
5 
6  This library is free software; you can redistribute it and/or
7  modify it under the terms of the GNU Library General Public
8  License as published by the Free Software Foundation; either
9  version 2 of the License, or (at your option) any later version.
10 
11  This library is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  Library General Public License for more details.
15 
16  You should have received a copy of the GNU Library General Public License
17  along with this library; see the file COPYING.LIB. If not, write to
18  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19  Boston, MA 02110-1301, USA.
20 */
21 #ifndef KLOCALE_H
22 #define KLOCALE_H
23 
24 #include <kdelibs4support_export.h>
25 #include <ksharedconfig.h>
26 
27 // Include for providing source code compatibility
28 #include <klocalizedstring.h>
29 
30 #include <QString>
31 #include <QList>
32 
33 class QStringList;
34 class QTextCodec;
35 class QDate;
36 class QTime;
37 class QDateTime;
38 
39 class KDateTime;
40 class KCalendarSystem;
41 class KCurrencyCode;
42 class KDayPeriod;
43 
44 class KLocalePrivate;
45 
46 /**
47  * \file klocale.h
48  */
49 
50 /**
51  * KLocale provides support for language and country specific stuff.
52  *
53  * KLocale supports specifying the format
54  * for numbers, currency, time, and date.
55  *
56  * Use KLocale::global() to get pointer to the global KLocale object,
57  * containing the applications current locale settings.
58  *
59  * For example, to format the date May 17, 1995 in the current locale, use:
60  *
61  * \code
62  * QString date = KLocale::global()->formatDate(QDate(1995,5,17));
63  * \endcode
64  *
65  * @author Stephan Kulow <[email protected]>, Preston Brown <[email protected]>,
66  * Hans Petter Bieker <[email protected]>, Lukas Tinkl <[email protected]>
67  * @short class for supporting locale settings
68  *
69  * @deprecated since 5.0. For translation support use KLocalizedString (from the
70  * KI18n framework); for string formatting use QLocale() or KFormat (from the
71  * KCoreAddons framework) if QLocale doesn't provide the formatting you need.
72  * For more information about porting code that is still using KLocale see:
73  * https://community.kde.org/Frameworks/Porting_Notes#Localization
74  */
75 class KDELIBS4SUPPORT_EXPORT KLocale
76 {
77 public:
78  /**
79  * Constructs a KLocale.
80  *
81  * The constructor looks for entries Language and Country
82  * in the group Locale in the configuration file.
83  *
84  * If no configuration file is specified, it will also look for languages
85  * and country using the environment variables (KDE_LANG, LC_MESSAGES,
86  * LC_ALL, LANG), as well as the global configuration file.
87  *
88  * If you specify a configuration file, it has to be valid until the KLocale
89  * object is destroyed. Note that a setLocale() will be performed on the
90  * config using the current locale language and country, which may cause
91  * a sync() and reparseConfiguration() which will save any changes
92  * you have made and load any changes other shared copies have made.
93  *
94  * @param config a configuration file with a Locale group detailing
95  * locale-related preferences (such as language, country,
96  * and formatting options).
97  */
98  KDELIBS4SUPPORT_DEPRECATED explicit KLocale(KSharedConfig::Ptr config = KSharedConfig::Ptr());
99 
100  /**
101  * Constructs a KLocale.
102  *
103  * Allows you to override the language and, optionally, the
104  * country of this locale.
105  *
106  * If you specify a configuration file, a setLocale() will be performed on
107  * the config using the current locale language and country,
108  * which may cause a sync() and reparseConfiguration() which
109  * will save any changes you have made.
110  *
111  * @param language the ISO Language Code for the locale, e.g. "en" for English
112  * @param country the ISO Country Code for the locale, e.g. "US" for USA
113  * @param config a configuration file with a Locale group detailing
114  * locale-related preferences (such as language, country,
115  * and formatting options).
116  */
117  KLocale(const QString &language, const QString &country = QString(),
118  KConfig *config = nullptr);
119 
120  /**
121  * Copy constructor
122  */
123  KLocale(const KLocale &rhs);
124 
125  /**
126  * Assignment operator
127  */
128  KLocale &operator= (const KLocale &rhs);
129 
130  /**
131  * Destructor
132  */
133  virtual ~KLocale();
134 
135  /**
136  * Changes the current encoding.
137  *
138  * @param mibEnum The mib of the preferred codec
139  *
140  * @return True on success.
141  */
142  bool setEncoding(int mibEnum);
143 
144  /**
145  * Various positions for where to place the positive or negative
146  * sign when they are related to a monetary value.
147  */
149  /**
150  * Put parantheses around the quantity, e.g. "$ (217)"
151  */
152  ParensAround = 0,
153  /**
154  * Prefix the quantity with the sign, e.g. "$ -217"
155  */
156  BeforeQuantityMoney = 1,
157  /**
158  * Suffix the quanitity with the sign, e.g. "$ 217-"
159  */
160  AfterQuantityMoney = 2,
161  /**
162  * Prefix the currency symbol with the sign, e.g. "-$ 217"
163  */
164  BeforeMoney = 3,
165  /**
166  * Suffix the currency symbol with the sign, e.g. "$- 217"
167  */
168  AfterMoney = 4
169  };
170 
171  /**
172  * @since 4.3
173  *
174  * The set of digit characters used to display and enter numbers.
175  */
176  enum DigitSet {
177  ArabicDigits, /**< 0123456789 (European and some Asian
178  languages and western Arabic dialects) */
179  ArabicIndicDigits, /**< ٠١٢٣٤٥٦٧٨٩ (eastern Arabic dialects) */
180  EasternArabicIndicDigits, /**< ۰۱۲۳۴۵۶۷۸۹ (Persian and Urdu) */
181  DevenagariDigits, /**< ०१२३४५६७८९ (Hindi) */
182  BengaliDigits, /**< ০১২৩৪৫৬৭৮৯ (Bengali and Assamese) */
183  GujaratiDigits, /**< ૦૧૨૩૪૫૬૭૮૯ (Gujarati) */
184  GurmukhiDigits, /**< ੦੧੨੩੪੫੬੭੮੯ (Punjabi) */
185  KannadaDigits, /**< ೦೧೨೩೪೫೬೭೮೯ (Kannada) */
186  KhmerDigits, /**< ០១២៣៤៥៦៧៨៩ (Khmer) */
187  MalayalamDigits, /**< ൦൧൨൩൪൫൬൭൮൯ (Malayalam) */
188  OriyaDigits, /**< ୦୧୨୩୪୫୬୭୮୯ (Oriya) */
189  TamilDigits, /**< ௦௧௨௩௪௫௬௭௮ (Tamil) */
190  TeluguDigits, /**< ౦౧౨౩౪౫౬౭౯ (Telugu) */
191  ThaiDigits /**< ๐๑๒๓๔๕๖๗๘๙ (Thai) */
192  // The following Decimal Digit Sets are defined in Unicode but the associated
193  // languages are not yet translated in KDE, so are not yet enabled.
194  // The script names are taken from the Unicode standard, the associated
195  // languages from Wikipedia.
196  // BalineseDigits, /**< ᭐᭑᭒᭓᭔᭕᭖᭗᭘᭙ (Balinese) */
197  // ChamDigits, /**< ꩐꩑꩒꩓꩔꩕꩖꩗꩘꩙ (Cham) */
198  // JavaneseDigits, /**< ꧐꧑꧒꧓꧔꧕꧖꧗꧘꧙ (Javanese) */
199  // KayahLiDigits, /**< ꤀꤁꤂꤃꤄꤅꤆꤇꤈꤉ (Kayah) */
200  // LaoDigits, /**< ໐໑໒໓໔໕໖໗໘໙ (Lao) */
201  // LepchaDigits, /**< ᱀᱁᱂᱃᱄᱅᱆᱇᱈᱉ (Lepcha) */
202  // LimbuDigits, /**< ᥆᥇᥈᥉᥊᥋᥌᥍᥎᥏ (Limbu) */
203  // MeeteiMayekDigits, /**< ꯰꯱꯲꯳꯴꯵꯶꯷꯸꯹ (Meitei) */
204  // MongolianDigits, /**< ᠐᠑᠒᠓᠔᠕᠖᠗᠘᠙ (Mongolian) */
205  // MyanmarDigits, /**< ၀၁၂၃၄၅၆၇၈၉ (Myanmar/Burmese ) */
206  // MyanmarShanDigits, /**< ႐႑႒႓႔႕႖႗႘႙ (Shan) */
207  // NewTaiLueDigits, /**< ᧐᧑᧒᧓᧔᧕᧖᧗᧘᧙ (Tai Lü) */
208  // NKoDigits, /**< ߀߁߂߃߄߅߆߇߈߉ (Mande and N'Ko) */
209  // OlChikiDigits, /**< ᱐᱑᱒᱓᱔᱕᱖᱗᱘᱙ (Santali) */
210  // OsmanyaDigits, /**< ҠҡҢңҤҥҦҧҨҩ (Somali) */
211  // SaurashtraDigits, /**< ꣐꣑꣒꣓꣔꣕꣖꣗꣘꣙ (Saurashtra) */
212  // SundaneseDigits, /**< ᮰᮱᮲᮳᮴᮵᮶᮷᮸᮹ (Sundanese) */
213  // TaiThamDigits, /**< ᪐᪑᪒᪓᪔᪕᪖᪗᪘᪙ (Tai Lü) */
214  // TibetanDigits, /**< ༠༡༢༣༤༥༦༧༨༩ (Tibetan) */
215  // VaiDigits, /**< ꘠꘡꘢꘣꘤꘥꘦꘧꘨꘩ (Vai) */
216  };
217 
218  /**
219  * @since 4.3
220  *
221  * Convert a digit set identifier to a human readable, localized name.
222  *
223  * @param digitSet the digit set identifier
224  * @param withDigits whether to add the digits themselves to the name
225  *
226  * @return the human readable and localized name of the digit set
227  *
228  * @see DigitSet
229  */
230  QString digitSetToName(DigitSet digitSet, bool withDigits = false) const;
231 
232  /**
233  * @since 4.3
234  *
235  * Provides list of all known digit set identifiers.
236  *
237  * @return list of all digit set identifiers
238  * @see DigitSet
239  * @see digitSetToName
240  */
241  QList<DigitSet> allDigitSetsList() const;
242 
243  /**
244  * Returns what a decimal point should look like ("." or "," etc.)
245  * according to the current locale or user settings.
246  *
247  * @return The decimal symbol used by locale.
248  */
249  QString decimalSymbol() const;
250 
251  /**
252  * Returns what the thousands separator should look
253  * like ("," or "." etc.)
254  * according to the current locale or user settings.
255  *
256  * @return The thousands separator used by locale.
257  */
258  QString thousandsSeparator() const;
259 
260  /**
261  * @since 4.3
262  *
263  * Returns the identifier of the digit set used to display numbers.
264  *
265  * @return the digit set identifier
266  * @see DigitSet
267  * @see digitSetToName
268  */
269  DigitSet digitSet() const;
270 
271  /**
272  * @since 4.4
273  *
274  * Returns the ISO 4217 Currency Code for the current locale
275  *
276  * @return The default ISO Currency Code used by locale.
277  */
278  QString currencyCode() const;
279 
280  /**
281  * @since 4.4
282  *
283  * Returns the Currency Code object for the current locale
284  *
285  * @return The default Currency Code object used by locale.
286  */
287  KCurrencyCode *currency() const;
288 
289  /**
290  * Returns what the symbol denoting currency in the current locale
291  * as as defined by user settings should look like.
292  *
293  * @return The default currency symbol used by locale.
294  */
295  QString currencySymbol() const;
296 
297  /**
298  * Returns what a decimal point should look like ("." or "," etc.)
299  * for monetary values, according to the current locale or user
300  * settings.
301  *
302  * @return The monetary decimal symbol used by locale.
303  */
304  QString monetaryDecimalSymbol() const;
305 
306  /**
307  * Returns what a thousands separator for monetary values should
308  * look like ("," or " " etc.) according to the current locale or
309  * user settings.
310  *
311  * @return The monetary thousands separator used by locale.
312  */
313  QString monetaryThousandsSeparator() const;
314 
315  /**
316  * Returns what a positive sign should look like ("+", " ", etc.)
317  * according to the current locale or user settings.
318  *
319  * @return The positive sign used by locale.
320  */
321  QString positiveSign() const;
322 
323  /**
324  * Returns what a negative sign should look like ("-", etc.)
325  * according to the current locale or user settings.
326  *
327  * @return The negative sign used by locale.
328  */
329  QString negativeSign() const;
330 
331  /**
332  * @deprecated use decimalPlaces() or monetaryDecimalPlaces()
333  *
334  * The number of fractional digits to include in monetary values (usually 2).
335  *
336  * @return Default number of fractional digits used by locale.
337  */
338  KDELIBS4SUPPORT_DEPRECATED int fracDigits() const;
339 
340  /**
341  * @since 4.4
342  *
343  * The number of decimal places to include in numeric values (usually 2).
344  *
345  * @return Default number of numeric decimal places used by locale.
346  */
347  int decimalPlaces() const;
348 
349  /**
350  * @since 4.4
351  *
352  * The number of decimal places to include in monetary values (usually 2).
353  *
354  * @return Default number of monetary decimal places used by locale.
355  */
356  int monetaryDecimalPlaces() const;
357 
358  /**
359  * If and only if the currency symbol precedes a positive value,
360  * this will be true.
361  *
362  * @return Where to print the currency symbol for positive numbers.
363  */
364  bool positivePrefixCurrencySymbol() const;
365 
366  /**
367  * If and only if the currency symbol precedes a negative value,
368  * this will be true.
369  *
370  * @return True if the currency symbol precedes negative numbers.
371  */
372  bool negativePrefixCurrencySymbol() const;
373 
374  /**
375  * Returns the position of a positive sign in relation to a
376  * monetary value.
377  *
378  * @return Where/how to print the positive sign.
379  * @see SignPosition
380  */
381  SignPosition positiveMonetarySignPosition() const;
382 
383  /**
384  * Denotes where to place a negative sign in relation to a
385  * monetary value.
386  *
387  * @return Where/how to print the negative sign.
388  * @see SignPosition
389  */
390  SignPosition negativeMonetarySignPosition() const;
391 
392  /**
393  * @since 4.3
394  *
395  * Retuns the digit set used to display monetary values.
396  *
397  * @return the digit set identifier
398  * @see DigitSet
399  * @see digitSetToName
400  */
401  DigitSet monetaryDigitSet() const;
402 
403  /**
404  * Given a double, converts that to a numeric string containing
405  * the localized monetary equivalent.
406  *
407  * e.g. given 123456, return "$ 123,456.00".
408  *
409  * If precision isn't specified or is < 0, then the default monetaryDecimalPlaces() is used.
410  *
411  * @param num The number we want to format
412  * @param currency The currency symbol you want.
413  * @param precision Number of decimal places displayed
414  *
415  * @return The number of money as a localized string
416  * @see monetaryDecimalPlaces()
417  */
418  QString formatMoney(double num, const QString &currency = QString(), int precision = -1) const;
419 
420  /**
421  * Given a double, converts that to a numeric string containing
422  * the localized numeric equivalent.
423  *
424  * e.g. given 123456.78F, return "123,456.78" (for some European country).
425  *
426  * If precision isn't specified or is < 0, then the default decimalPlaces() is used.
427  *
428  * This function is a wrapper that is provided for convenience.
429  *
430  * @param num The number to convert
431  * @param precision Number of decimal places used.
432  *
433  * @return The number as a localized string
434  * @see formatNumber(const QString, bool, int)
435  * @see decimalPlaces()
436  */
437  QString formatNumber(double num, int precision = -1) const;
438 
439  /**
440  * Given a string representing a number, converts that to a numeric
441  * string containing the localized numeric equivalent.
442  *
443  * e.g. given 123456.78F, return "123,456.78" (for some European country).
444  *
445  * If precision isn't specified or is < 0, then the default decimalPlaces() is used.
446  *
447  * @param numStr The number to format, as a string.
448  * @param round Round fractional digits. (default true)
449  * @param precision Number of fractional digits used for rounding. Unused if round=false.
450  *
451  * @return The number as a localized string
452  */
453  QString formatNumber(const QString &numStr, bool round = true, int precision = -1) const;
454 
455  /**
456  * Given an integer, converts that to a numeric string containing
457  * the localized numeric equivalent.
458  *
459  * e.g. given 123456L, return "123,456" (for some European country).
460  *
461  * @param num The number to convert
462  *
463  * @return The number as a localized string
464  */
465  QString formatLong(long num) const;
466 
467  /**
468  * These binary units are used in KDE by the formatByteSize()
469  * functions.
470  *
471  * NOTE: There are several different units standards:
472  * 1) SI (i.e. metric), powers-of-10.
473  * 2) IEC, powers-of-2, with specific units KiB, MiB, etc.
474  * 3) JEDEC, powers-of-2, used for solid state memory sizing which
475  * is why you see flash cards labels as e.g. 4GB. These (ab)use
476  * the metric units. Although JEDEC only defines KB, MB, GB, if
477  * JEDEC is selected all units will be powers-of-2 with metric
478  * prefixes for clarity in the event of sizes larger than 1024 GB.
479  *
480  * Although 3 different dialects are possible this enum only uses
481  * metric names since adding all 3 different names of essentially the same
482  * unit would be pointless. Use BinaryUnitDialect to control the exact
483  * units returned.
484  *
485  * @since 4.4
486  * @see binaryUnitDialect
487  */
489  /// Auto-choose a unit such that the result is in the range [0, 1000 or 1024)
490  DefaultBinaryUnits = -1,
491 
492  // The first real unit must be 0 for the current implementation!
493  UnitByte, ///< B 1 byte
494  UnitKiloByte, ///< KiB/KB/kB 1024/1000 bytes.
495  UnitMegaByte, ///< MiB/MB/MB 2^20/10^06 bytes.
496  UnitGigaByte, ///< GiB/GB/GB 2^30/10^09 bytes.
497  UnitTeraByte, ///< TiB/TB/TB 2^40/10^12 bytes.
498  UnitPetaByte, ///< PiB/PB/PB 2^50/10^15 bytes.
499  UnitExaByte, ///< EiB/EB/EB 2^60/10^18 bytes.
500  UnitZettaByte, ///< ZiB/ZB/ZB 2^70/10^21 bytes.
501  UnitYottaByte, ///< YiB/YB/YB 2^80/10^24 bytes.
502  UnitLastUnit = UnitYottaByte
503  };
504 
505  /**
506  * This enum chooses what dialect is used for binary units.
507  *
508  * Note: Although JEDEC abuses the metric prefixes and can therefore be
509  * confusing, it has been used to describe *memory* sizes for quite some time
510  * and programs should therefore use either Default, JEDEC, or IEC 60027-2
511  * for memory sizes.
512  *
513  * On the other hand network transmission rates are typically in metric so
514  * Default, Metric, or IEC (which is unambiguous) should be chosen.
515  *
516  * Normally choosing DefaultBinaryDialect is the best option as that uses
517  * the user's selection for units.
518  *
519  * @since 4.4
520  * @see binaryUnitDialect
521  * @see setBinaryUnitDialect
522  */
524  DefaultBinaryDialect = -1, ///< Used if no specific preference
525  IECBinaryDialect, ///< KDE Default, KiB, MiB, etc. 2^(10*n)
526  JEDECBinaryDialect, ///< KDE 3.5 default, KB, MB, etc. 2^(10*n)
527  MetricBinaryDialect, ///< SI Units, kB, MB, etc. 10^(3*n)
528  LastBinaryDialect = MetricBinaryDialect
529  };
530 
531  /**
532  * Converts @p size from bytes to the string representation using the
533  * user's default binary unit dialect. The default unit dialect is
534  * IEC 60027-2.
535  *
536  * Example:
537  * formatByteSize(1024) returns "1.0 KiB" by default.
538  *
539  * @param size size in bytes
540  * @return converted size as a string - e.g. 123.4 KiB , 12.0 MiB
541  * @see BinaryUnitDialect
542  * @todo KDE 5: Remove in favor of overload added in KDE 4.4.
543  */
544  QString formatByteSize(double size) const;
545 
546  /**
547  * @since 4.4
548  *
549  * Converts @p size from bytes to the appropriate string representation
550  * using the binary unit dialect @p dialect and the specific units @p specificUnit.
551  *
552  * Example:
553  * formatByteSize(1000, unit, KLocale::UnitKiloByte) returns:
554  * for KLocale::MetricBinaryDialect, "1.0 kB",
555  * for KLocale::IECBinaryDialect, "0.9 KiB",
556  * for KLocale::JEDECBinaryDialect, "0.9 KB".
557  *
558  * @param size size in bytes
559  * @param precision number of places after the decimal point to use. KDE uses
560  * 1 by default so when in doubt use 1.
561  * @param dialect binary unit standard to use. Use DefaultBinaryDialect to
562  * use the localized user selection unless you need to use a specific
563  * unit type (such as displaying a flash memory size in JEDEC).
564  * @param specificUnit specific unit size to use in result. Use
565  * DefaultBinaryUnits to automatically select a unit that will return
566  * a sanely-sized number.
567  * @return converted size as a translated string including the units.
568  * E.g. "1.23 KiB", "2 GB" (JEDEC), "4.2 kB" (Metric).
569  * @see BinaryUnitDialect
570  */
571  QString formatByteSize(double size, int precision,
573  BinarySizeUnits specificUnit = KLocale::DefaultBinaryUnits) const;
574 
575  /**
576  * Returns the user's configured binary unit dialect.
577  * e.g. if MetricBinaryDialect is returned then the values
578  * configured for how much a set of bytes are worth would
579  * be 10^(3*n) and KB (1000 bytes == 1 KB), in this case.
580  *
581  * Will never return DefaultBinaryDialect.
582  *
583  * @since 4.4
584  * @return User's configured binary unit dialect
585  * @see BinaryUnitDialect
586  */
587  BinaryUnitDialect binaryUnitDialect() const;
588 
589  /**
590  * Sets @p newDialect to be the default dialect for this locale (and only
591  * this locale). Newly created KLocale objects will continue to default
592  * to the user's choice.
593  *
594  * @param newDialect the new dialect to set as default for this locale object.
595  * @since 4.4
596  */
597  void setBinaryUnitDialect(BinaryUnitDialect newDialect);
598 
599  /**
600  * Given a number of milliseconds, converts that to a string containing
601  * the localized equivalent
602  *
603  * e.g. given formatDuration(60000), returns "1.0 minutes"
604  *
605  * @param mSec Time duration in milliseconds
606  * @return converted duration as a string - e.g. "5.5 seconds" "23.0 minutes"
607  */
608  QString formatDuration(unsigned long mSec) const;
609 
610  /**
611  * Given a number of milliseconds, converts that to a pretty string containing
612  * the localized equivalent.
613  *
614  * e.g. given prettyFormatDuration(60001) returns "1 minute"
615  * given prettyFormatDuration(62005) returns "1 minute and 2 seconds"
616  * given prettyFormatDuration(90060000) returns "1 day and 1 hour"
617  *
618  * @param mSec Time duration in milliseconds
619  * @return converted duration as a string.
620  * Units not interesting to the user, for example seconds or minutes when the first
621  * unit is day, are not returned because they are irrelevant. The same applies for
622  * seconds when the first unit is hour.
623  * @since 4.2
624  */
625  QString prettyFormatDuration(unsigned long mSec) const;
626 
627  /**
628  * @deprecated
629  *
630  * Use this to determine whether nouns are declined in
631  * locale's language. This property should remain
632  * read-only (no setter function)
633  *
634  * @return If nouns are declined
635  */
636  KDELIBS4SUPPORT_DEPRECATED bool nounDeclension() const;
637 
638  /**
639  * @since 4.6
640  *
641  * Available Calendar Systems
642  *
643  * @see setCalendarSystem()
644  * @see calendarSystem()
645  */
647  GregorianCalendar = 1, /**< KDE Default, proleptic Gregorian Calendar as used by QDate */
648  //BahaiCalendar = 2, /**< Baha'i Calendar */
649  //BuddhistLunarCalendar = 3, /**< Buddhist Lunar Calendar*/
650  //ChineseCalendar = 4, /**< Chinese Calendar */
651  CopticCalendar = 5, /**< Coptic Calendar as used Coptic Church and some parts of Egypt */
652  EthiopianCalendar = 6, /**< Ethiopian Calendar, aka Ethiopic Calendar */
653  //EthiopianAmeteAlemCalendar = 7, /**< Ethiopian Amete Alem version, aka Ethiopic Amete Alem */
654  HebrewCalendar = 9, /**< Hebrew Calendar, aka Jewish Calendar */
655  //HinduCalendar = 10, /**< Hindu Lunar Calendar */
656  //IslamicLunarCalendar = 11, /**< Islamic Lunar Calendar */
657  IslamicCivilCalendar = 12, /**< Islamic Civil Calendar, aka Hijri, not the Lunar Calendar */
658  //IslamicUmAlQuraCalendar = 13, /**< Islamic Lunar Calendar, Um Al Qura varient used in Saudi Arabia */
659  IndianNationalCalendar = 14, /**< Indian National Calendar, not the Lunar Calendar */
660  //Iso8601Calendar = 15, /**< ISO 8601 Standard Calendar */
661  JalaliCalendar = 16, /**< Jalali Calendar, aka Persian or Iranian, also used in Afghanistan */
662  //JalaliBirashkCalendar = 17, /**< Jalali Calendar, Birashk Algorythm variant */
663  //Jalali33YearCalendar = 18, /**< Jalali Calendar, 33 Year cycle variant */
664  JapaneseCalendar = 19, /**< Japanese Calendar, Gregorian calculation using Japanese Era (Nengô) */
665  //JucheCalendar = 20, /**< Juche Calendar, used in North Korea */
666  JulianCalendar = 21, /**< Julian Calendar, as used in Orthodox Churches */
667  MinguoCalendar = 22, /**< Minguo Calendar, aka ROC, Republic of China or Taiwanese */
668  ThaiCalendar = 23, /**< Thai Calendar, aka Buddhist or Thai Buddhist */
669 
670  QDateCalendar = GregorianCalendar /**< @deprecated Alias for GregorianCalendar */
671  };
672 
673  /**
674  * @since 4.6
675  *
676  * System used for Week Numbers
677  *
678  * @see setWeekNumberSystem()
679  * @see weekNumberSystem()
680  */
682  DefaultWeekNumber = -1, /**< The system locale default */
683  IsoWeekNumber = 0, /**< ISO Week Number */
684  FirstFullWeek = 1, /**< Week 1 starts on the first Week Start Day in year ends after 7 days */
685  FirstPartialWeek = 2, /**< Week 1 starts Jan 1st ends day before first Week Start Day in year */
686  SimpleWeek = 3 /**< Week 1 starts Jan 1st ends after 7 days */
687  };
688 
689  /**
690  * @since 4.4
691  *
692  * Standard used for Date Time Format String
693  */
695  KdeFormat, /**< KDE Standard */
696  PosixFormat, /**< POSIX Standard */
697  UnicodeFormat /**< UNICODE Standard (Qt/Java/OSX/Windows) */
698  };
699 
700  /**
701  * @since 4.6
702  *
703  * Mode to use when parsing a Date Time input string
704  */
706  LiberalParsing /**< Parse Date/Time liberally. So long as the
707  input string contains at least a reconizable
708  month and day the input will be accepted. */
709  //ModerateParsing, /**< Parse Date/Time with modeate tolerance.
710  // The date components in the format must all
711  // occur in the input and in the same order,
712  // but the spacing and the componants themselves
713  // may vary from the strict format. */
714  //StrictParsing /**< Parse Date/Time strictly to the format. */
715  };
716 
717  /**
718  * @since 4.6
719  *
720  * The various Components that make up a Date / Time
721  * In the future the Components may be combined as flags for dynamic
722  * generation of Date Formats.
723  *
724  * @see KCalendarSystem
725  * @see KLocalizedDate
726  * @see DateTimeComponentFormat
727  */
729  Year = 0x1, /**< The Year portion of a date, may be number or name */
730  YearName = 0x2, /**< The Year Name portion of a date */
731  Month = 0x4, /**< The Month portion of a date, may be number or name */
732  MonthName = 0x8, /**< The Month Name portion of a date */
733  Day = 0x10, /**< The Day portion of a date, may be number or name */
734  DayName = 0x20, /**< The Day Name portion of a date */
735  JulianDay = 0x40, /**< The Julian Day of a date */
736  EraName = 0x80, /**< The Era Name portion of a date */
737  EraYear = 0x100, /**< The Era and Year portion of a date */
738  YearInEra = 0x200, /**< The Year In Era portion of a date */
739  DayOfYear = 0x400, /**< The Day Of Year portion of a date, may be number or name */
740  DayOfYearName = 0x800, /**< The Day Of Year Name portion of a date */
741  DayOfWeek = 0x1000, /**< The Day Of Week / Weekday portion of a date, may be number or name */
742  DayOfWeekName = 0x2000, /**< The Day Of Week Name / Weekday Name portion of a date */
743  Week = 0x4000, /**< The Week Number portion of a date */
744  WeekYear = 0x8000, /**< The Week Year portion of a date */
745  MonthsInYear = 0x10000, /**< The Months In Year portion of a date */
746  WeeksInYear = 0x20000, /**< The Weeks In Year portion of a date */
747  DaysInYear = 0x40000, /**< The Days In Year portion of a date */
748  DaysInMonth = 0x80000, /**< The Days In Month portion of a date */
749  DaysInWeek = 0x100000, /**< The Days In Week portion of a date */
750  Hour = 0x200000, /**< The Hours portion of a date */
751  Minute = 0x400000, /**< The Minutes portion of a date */
752  Second = 0x800000, /**< The Seconds portion of a date */
753  Millisecond = 0x1000000, /**< The Milliseconds portion of a date */
754  DayPeriod = 0x2000000, /**< The Day Period portion of a date, e.g. AM/PM */
755  DayPeriodHour = 0x4000000, /**< The Day Period Hour portion of a date */
756  Timezone = 0x8000000, /**< The Time Zone portion of a date, may be offset or name */
757  TimezoneName = 0x10000000, /**< The Time Zone Name portion of a date */
758  UnixTime = 0x20000000 /**< The UNIX Time portion of a date */
759  };
760  Q_DECLARE_FLAGS(DateTimeComponents, DateTimeComponent)
761 
762  /**
763  * @since 4.6
764  *
765  * Format used for individual Date/Time Components when converted to/from a string
766  * Largely equivalent to the UNICODE CLDR format width definitions 1..5
767  *
768  * @see DateTimeComponentFormat
769  */
771  DefaultComponentFormat = -1, /**< The system locale default for the componant */
772  ShortNumber = 0, /**< Number at its natural width, e.g. 2 for the 2nd*/
773  LongNumber, /**< Number padded to a required width, e.g. 02 for the 2nd*/
774  //OrdinalNumber /**< Ordinal number format, e.g. "2nd" for the 2nd */
775  NarrowName = 3, /**< Narrow text format, may not be unique, e.g. M for Monday */
776  ShortName, /**< Short text format, e.g. Mon for Monday */
777  LongName /**< Long text format, e.g. Monday for Monday */
778  };
779 
780  /**
781  * Format for date string.
782  */
783  enum DateFormat {
784  ShortDate, /**< Locale Short date format, e.g. 08-04-2007 */
785  LongDate, /**< Locale Long date format, e.g. Sunday 08 April 2007 */
786  FancyShortDate, /**< Same as ShortDate for dates a week or more ago. For more
787  recent dates, it is represented as Today, Yesterday, or
788  the weekday name. */
789  FancyLongDate, /**< Same as LongDate for dates a week or more ago. For more
790  recent dates, it is represented as Today, Yesterday, or
791  the weekday name. */
792  IsoDate, /**< ISO-8601 Date format YYYY-MM-DD, e.g. 2009-12-31 */
793  IsoWeekDate, /**< ISO-8601 Week Date format YYYY-Www-D, e.g. 2009-W01-1 */
794  IsoOrdinalDate /**< ISO-8601 Ordinal Date format YYYY-DDD, e.g. 2009-001 */
795  };
796 
797  /**
798  * Returns a string formatted to the current locale's conventions
799  * regarding dates.
800  *
801  * @param date the date to be formatted
802  * @param format category of date format to use
803  *
804  * @return the date as a string
805  */
806  QString formatDate(const QDate &date, DateFormat format = LongDate) const;
807 
808  /**
809  * Returns a string formatted to the current locale's conventions
810  * regarding both date and time.
811  *
812  * @param dateTime the date and time to be formatted
813  * @param format category of date format to use
814  * @param includeSecs if @c true, the string will include the seconds part
815  * of the time; otherwise, the seconds will be omitted
816  *
817  * @return the date and time as a string
818  */
819  QString formatDateTime(const QDateTime &dateTime, DateFormat format = ShortDate,
820  bool includeSecs = false) const;
821 
822  /**
823  * Options for formatting date-time values.
824  */
826  TimeZone = 0x01, /**< Include a time zone string */
827  Seconds = 0x02 /**< Include the seconds value */
828  };
830 
831  /**
832  * Returns a string formatted to the current locale's conventions
833  * regarding both date and time.
834  *
835  * @param dateTime the date and time to be formatted
836  * @param format category of date format to use
837  * @param options additional output options
838  *
839  * @return The date and time as a string
840  */
841  QString formatDateTime(const KDateTime &dateTime, DateFormat format = ShortDate,
842  DateTimeFormatOptions options = {}) const;
843 
844  /**
845  * Use this to determine whether in dates a possessive form of month
846  * name is preferred ("of January" rather than "January")
847  *
848  * @return If possessive form should be used
849  */
850  bool dateMonthNamePossessive() const;
851 
852  /**
853  * @deprecated replaced by formatLocaleTime()
854  *
855  * Returns a string formatted to the current locale's conventions
856  * regarding times.
857  *
858  * @param pTime The time to be formatted.
859  * @param includeSecs if true, seconds are included in the output,
860  * otherwise only hours and minutes are formatted.
861  * @param isDuration if true, the given time is a duration, not a clock time.
862  * This means "am/pm" shouldn't be displayed.
863  *
864  * @return The time as a string
865  */
866  QString formatTime(const QTime &pTime, bool includeSecs = false, bool isDuration = false) const;
867 
868  /**
869  * @since 4.4
870  *
871  * Format flags for readLocaleTime() and formatLocaleTime()
872  */
874  TimeDefault = 0x0, ///< Default formatting using seconds and the format
875  ///< as specified by the locale.
876  TimeWithoutSeconds = 0x1, ///< Exclude the seconds part of the time from display
877  TimeWithoutAmPm = 0x2, ///< Read/format time string without am/pm suffix but
878  ///< keep the 12/24h format as specified by locale time
879  ///< format, eg. "07.33.05" instead of "07.33.05 pm" for
880  ///< time format "%I.%M.%S %p".
881  TimeDuration = 0x6, ///< Read/format time string as duration. This will strip
882  ///< the am/pm suffix and read/format times with an hour
883  ///< value of 0-23 hours, eg. "19.33.05" instead of
884  ///< "07.33.05 pm" for time format "%I.%M.%S %p".
885  ///< This automatically implies @c TimeWithoutAmPm.
886  TimeFoldHours = 0xE ///< Read/format time string as duration. This will not
887  ///< not output the hours part of the duration but will
888  ///< add the hours (times sixty) to the number of minutes,
889  ///< eg. "70.23" instead of "01.10.23" for time format
890  ///< "%I.%M.%S %p".
891  };
892  Q_DECLARE_FLAGS(TimeFormatOptions, TimeFormatOption)
893 
894  /**
895  * @since 4.4
896  *
897  * Returns a string formatted to the current locale's conventions
898  * regarding times.
899  *
900  * @param pTime the time to be formatted
901  * @param options format option to use when formatting the time
902  * @return The time as a string
903  */
904  QString formatLocaleTime(const QTime &pTime,
905  TimeFormatOptions options = KLocale::TimeDefault) const;
906 
907  /**
908  * @since 4.3
909  *
910  * Returns the identifier of the digit set used to display dates and time.
911  *
912  * @return the digit set identifier
913  * @see DigitSet
914  * @see digitSetToName
915  */
916  DigitSet dateTimeDigitSet() const;
917 
918  /**
919  * Use this to determine if the user wants a 12 hour clock.
920  *
921  * @return If the user wants 12h clock
922  * @deprecated. A possible equivalent would be:
923  * @code
924  * static bool use12Clock()
925  * {
926  * const QString str = QLocale().timeFormat();
927  * // 'A' or 'a' means am/pm is shown (and then 'h' uses 12-hour format)
928  * // but 'H' forces a 24-hour format anyway, even with am/pm shown.
929  * return str.contains(QLatin1Char('a'), Qt::CaseInsensitive) && !str.contains(QLatin1Char('H'));
930  * }
931  * @endcode
932  */
933  bool use12Clock() const;
934 
935  /**
936  * @since 4.6
937  *
938  * Returns the Day Period matching the time given
939  *
940  * @param time the time to return the day period for
941  * @param format the format to return teh day period in
942  * @return the Day Period for the given time
943  */
944  QString dayPeriodText(const QTime &time, DateTimeComponentFormat format = DefaultComponentFormat) const;
945 
946  /**
947  * Use this to determine which day is the first day of the week.
948  *
949  * @return an integer (Monday=1..Sunday=7)
950  */
951  int weekStartDay() const;
952 
953  /**
954  * Use this to determine which day is the first working day of the week.
955  *
956  * @since 4.2
957  * @return an integer (Monday=1..Sunday=7)
958  */
959  int workingWeekStartDay() const;
960 
961  /**
962  * Use this to determine which day is the last working day of the week.
963  *
964  * @since 4.2
965  * @return an integer (Monday=1..Sunday=7)
966  */
967  int workingWeekEndDay() const;
968 
969  /**
970  * Use this to determine which day is reserved for religious observance
971  *
972  * @since 4.2
973  * @return day number (None = 0, Monday = 1, ..., Sunday = 7)
974  */
975  int weekDayOfPray() const;
976 
977  /**
978  * Returns a pointer to the calendar system object.
979  *
980  * @return the current calendar system instance
981  */
982  const KCalendarSystem *calendar() const;
983 
984  /**
985  * @deprecated use calendarSystem() instead
986  *
987  * Returns the name of the calendar system that is currently being
988  * used by the system.
989  *
990  * @see calendarSystem()
991  * @return the name of the calendar system
992  */
993  KDELIBS4SUPPORT_DEPRECATED QString calendarType() const;
994 
995  /**
996  * @since 4.6
997  *
998  * Returns the type of Calendar System used in this Locale
999  *
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  */
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  */
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  */
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  };
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  */
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 [email protected]
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
MiB/MB/MB 2^20/10^06 bytes.
Definition: klocale.h:495
POSIX Standard.
Definition: klocale.h:696
MeasureSystem
The Metric system will give you information in mm, while the Imperial system will give you informatio...
Definition: klocale.h:1636
௦௧௨௩௪௫௬௭௮ (Tamil)
Definition: klocale.h:189
Locale Short date format, e.g.
Definition: klocale.h:784
PiB/PB/PB 2^50/10^15 bytes.
Definition: klocale.h:498
DateFormat
Format for date string.
Definition: klocale.h:783
੦੧੨੩੪੫੬੭੮੯ (Punjabi)
Definition: klocale.h:184
KDE Default, KiB, MiB, etc. 2^(10*n)
Definition: klocale.h:525
ISO-8601 Week Date format YYYY-Www-D, e.g.
Definition: klocale.h:793
BinarySizeUnits
These binary units are used in KDE by the formatByteSize() functions.
Definition: klocale.h:488
൦൧൨൩൪൫൬൭൮൯ (Malayalam)
Definition: klocale.h:187
KCalendarSystem abstract base class, provides support for local Calendar Systems in KDE...
DateTimeComponentFormat
Definition: klocale.h:770
DateTimeFormatOption
Options for formatting date-time values.
Definition: klocale.h:825
KDE 3.5 default, KB, MB, etc. 2^(10*n)
Definition: klocale.h:526
Auto-choose a unit such that the result is in the range [0, 1000 or 1024)
Definition: klocale.h:490
TiB/TB/TB 2^40/10^12 bytes.
Definition: klocale.h:497
ReadTimeFlags
Flags for the old version of readTime()
Definition: klocale.h:1155
CalendarSystem
Definition: klocale.h:646
Number padded to a required width, e.g.
Definition: klocale.h:773
YiB/YB/YB 2^80/10^24 bytes.
Definition: klocale.h:501
WeekNumberSystem
Definition: klocale.h:681
SI Units, kB, MB, etc. 10^(3*n)
Definition: klocale.h:527
୦୧୨୩୪୫୬୭୮୯ (Oriya)
Definition: klocale.h:188
ReadDateFlags
Flags for readDate()
Definition: klocale.h:1108
GiB/GB/GB 2^30/10^09 bytes.
Definition: klocale.h:496
TimeProcessingOption
Additional processing options for readLocaleTime().
Definition: klocale.h:1183
DateTimeComponent
Definition: klocale.h:728
౦౧౨౩౪౫౬౭౯ (Telugu)
Definition: klocale.h:190
KDE Standard.
Definition: klocale.h:695
০১২৩৪৫৬৭৮৯ (Bengali and Assamese)
Definition: klocale.h:182
A class representing a date and time with an associated time zone.
Definition: kdatetime.h:148
KiB/KB/kB 1024/1000 bytes.
Definition: klocale.h:494
Used if no specific preference.
Definition: klocale.h:524
Short text format, e.g.
Definition: klocale.h:776
ZiB/ZB/ZB 2^70/10^21 bytes.
Definition: klocale.h:500
KLocale provides support for language and country specific stuff.
Definition: klocale.h:75
DateTimeFormatStandard
Definition: klocale.h:694
SignPosition
Various positions for where to place the positive or negative sign when they are related to a monetar...
Definition: klocale.h:148
B 1 byte.
Definition: klocale.h:493
۰۱۲۳۴۵۶۷۸۹ (Persian and Urdu)
Definition: klocale.h:180
TimeFormatOption
Definition: klocale.h:873
೦೧೨೩೪೫೬೭೮೯ (Kannada)
Definition: klocale.h:185
ISO-8601 Date format YYYY-MM-DD, e.g.
Definition: klocale.h:792
Locale Long date format, e.g.
Definition: klocale.h:785
EiB/EB/EB 2^60/10^18 bytes.
Definition: klocale.h:499
BinaryUnitDialect
This enum chooses what dialect is used for binary units.
Definition: klocale.h:523
DigitSet
Definition: klocale.h:176
Metric system (used e.g. in Europe)
Definition: klocale.h:1637
០១២៣៤៥៦៧៨៩ (Khmer)
Definition: klocale.h:186
૦૧૨૩૪૫૬૭૮૯ (Gujarati)
Definition: klocale.h:183
٠١٢٣٤٥٦٧٨٩ (eastern Arabic dialects)
Definition: klocale.h:179
०१२३४५६७८९ (Hindi)
Definition: klocale.h:181
DateTimeParseMode
Definition: klocale.h:705
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Jun 18 2021 22:58:10 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.