1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
30 \brief The QLocale class converts between numbers and their
31 string representations in various languages.
35 \ingroup string-processing
39 QLocale is initialized with a language/country pair in its
40 constructor and offers number-to-string and string-to-number
41 conversion functions similar to those in QString.
45 \snippet doc/src/snippets/code/src_corelib_tools_qlocale.cpp 0
47 QLocale supports the concept of a default locale, which is
48 determined from the system's locale settings at application
49 startup. The default locale can be changed by calling the
50 static member setDefault(). Setting the default locale has the
54 \i If a QLocale object is constructed with the default constructor,
55 it will use the default locale's settings.
56 \i QString::toInt(), QString::toDouble(), etc., interpret the
57 string according to the default locale. If this fails, it
58 falls back on the "C" locale.
59 \i QString::arg() uses the default locale to format a number when
60 its position specifier in the format string contains an 'L',
64 The following example illustrates how to use QLocale directly:
66 \snippet doc/src/snippets/code/src_corelib_tools_qlocale.cpp 1
68 When a language/country pair is specified in the constructor, one
69 of three things can happen:
72 \i If the language/country pair is found in the database, it is used.
73 \i If the language is found but the country is not, or if the country
74 is \c AnyCountry, the language is used with the most
75 appropriate available country (for example, Germany for German),
76 \i If neither the language nor the country are found, QLocale
77 defaults to the default locale (see setDefault()).
80 Use language() and country() to determine the actual language and
83 An alternative method for constructing a QLocale object is by
84 specifying the locale name.
86 \snippet doc/src/snippets/code/src_corelib_tools_qlocale.cpp 2
88 This constructor converts the locale name to a language/country
89 pair; it does not use the system locale database.
91 \note For the current keyboard input locale take a look at
92 QInputMethod::locale().
94 QLocale's data is based on Common Locale Data Repository v1.8.1.
96 The double-to-string and string-to-double conversion functions are
97 covered by the following licenses:
100 Copyright (c) 1991 by AT&T.
102 Permission to use, copy, modify, and distribute this software for any
103 purpose without fee is hereby granted, provided that this entire notice
104 is included in all copies of any software which is or includes a copy
105 or modification of this software and in all copies of the supporting
106 documentation for such software.
108 THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
109 WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY
110 REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
111 OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
113 This product includes software developed by the University of
114 California, Berkeley and its contributors.
116 \sa QString::arg(), QString::toInt(), QString::toDouble(),
117 QInputMethod::locale()
121 \enum QLocale::Language
123 This enumerated type is used to specify a language.
126 \value C The "C" locale is identical in behavior to English/UnitedStates.
215 \value NorwegianBokmal
216 \value Nynorsk Obsolete, please use NorwegianNynorsk
217 \value NorwegianNynorsk
343 \value CentralMoroccoTamazight
344 \value KoyraboroSenni
346 \omitvalue LastLanguage
348 \sa language(), languageToString()
352 \enum QLocale::Country
354 This enumerated type is used to specify a country.
365 \value AntiguaAndBarbuda
383 \value BosniaAndHerzegowina
387 \value BritishIndianOceanTerritory
388 \value BruneiDarussalam
397 \value CentralAfricanRepublic
401 \value ChristmasIsland
405 \value DemocraticRepublicOfCongo
406 \value PeoplesRepublicOfCongo
417 \value DominicanRepublic
422 \value EquatorialGuinea
426 \value FalklandIslands
431 \value MetropolitanFrance
433 \value FrenchPolynesia
434 \value FrenchSouthernTerritories
451 \value HeardAndMcDonaldIslands
469 \value DemocraticRepublicOfKorea
470 \value RepublicOfKorea
478 \value LibyanArabJamahiriya
490 \value MarshallIslands
508 \value NetherlandsAntilles
516 \value NorthernMarianaIslands
521 \value PalestinianTerritory
523 \value PapuaNewGuinea
534 \value RussianFederation
536 \value SaintKittsAndNevis
538 \value StVincentAndTheGrenadines
541 \value SaoTomeAndPrincipe
544 \value SerbiaAndMontenegro
550 \value SolomonIslands
553 \value SouthGeorgiaAndTheSouthSandwichIslands
557 \value StPierreAndMiquelon
560 \value SvalbardAndJanMayenIslands
564 \value SyrianArabRepublic
572 \value TrinidadAndTobago
576 \value TurksAndCaicosIslands
580 \value UnitedArabEmirates
583 \value UnitedStatesMinorOutlyingIslands
587 \value VaticanCityState
590 \value BritishVirginIslands
591 \value USVirginIslands
592 \value WallisAndFutunaIslands
600 \value SaintBarthelemy
602 \value LatinAmericaAndTheCaribbean
603 \omitvalue LastCountry
605 \sa country(), countryToString()
609 \enum QLocale::Script
611 This enumerated type is used to specify a script.
615 \value CyrillicScript
617 \value GurmukhiScript
618 \value SimplifiedHanScript same as SimplifiedChineseScript
619 \value SimplifiedChineseScript same as SimplifiedHanScript
620 \value TraditionalHanScript same as TraditionalChineseScript
621 \value TraditionalChineseScript same as TraditionalHanScript
623 \value MongolianScript
624 \value TifinaghScript
625 \omitvalue LastScript
627 \sa script(), scriptToString(), languageToString()
631 \enum QLocale::FormatType
633 This enum describes the types of format that can be used when
634 converting QDate and QTime objects to strings.
636 \value LongFormat The long version of day and month names; for
637 example, returning "January" as a month name.
639 \value ShortFormat The short version of day and month names; for
640 example, returning "Jan" as a month name.
642 \value NarrowFormat A special version of day and month names for
643 use when space is limited; for example, returning "J" as a month
644 name. Note that the narrow format might contain the same text for
645 different months and days or it can even be an empty string if the
646 locale doesn't support narrow names, so you should avoid using it
647 for date formatting. Also, for the system locale this format is
648 the same as ShortFormat.
652 \enum QLocale::NumberOption
654 This enum defines a set of options for number-to-string and string-to-number
655 conversions. They can be retrieved with numberOptions() and set with
658 \value OmitGroupSeparator If this option is set, the number-to-string functions
659 will not insert group separators in their return values. The default
660 is to insert group separators.
661 \value RejectGroupSeparator If this option is set, the string-to-number functions
662 will fail if they encounter group separators in their input. The default
663 is to accept numbers containing correctly placed group separators.
665 \sa setNumberOptions() numberOptions()
669 \enum QLocale::MeasurementSystem
671 This enum defines which units are used for measurement.
673 \value MetricSystem This value indicates metric units, such as meters,
674 centimeters and millimeters.
675 \value ImperialSystem This value indicates imperial units, such as inches and
676 miles. There are several distinct imperial systems in the world; this
677 value stands for the official United States imperial units.
684 \fn bool QLocale::operator==(const QLocale &other) const
686 Returns true if the QLocale object is the same as the \a other
687 locale specified; otherwise returns false.
691 \fn bool QLocale::operator!=(const QLocale &other) const
693 Returns true if the QLocale object is not the same as the \a other
694 locale specified; otherwise returns false.
698 \enum QLocale::QuotationStyle
700 This enum defines a set of possible styles for locale specific quotation.
702 \value StandardQuotation If this option is set, the standard quotation marks
703 will be used to quote strings.
704 \value AlternateQuotation If this option is set, the alternate quotation marks
705 will be used to quote strings.
715 \brief The QSystemLocale class can be used to finetune the system locale
721 \warning This class is only useful in very rare cases. Usually QLocale offers
722 all the functionality required for application development.
724 QSystemLocale allows to override the values provided by the system
725 locale (QLocale::system()).
731 \enum QSystemLocale::QueryType
733 Specifies the type of information queried by query(). For each value
734 the type of information to return from the query() method is listed.
736 \value LanguageId a uint specifying the language.
737 \value ScriptId a uint specifying the script.
738 \value CountryId a uint specifying the country.
739 \value DecimalPoint a QString specifying the decimal point.
740 \value GroupSeparator a QString specifying the group separator.
741 \value ZeroDigit a QString specifying the zero digit.
742 \value NegativeSign a QString specifying the minus sign.
743 \value PositiveSign a QString specifying the plus sign.
744 \value DateFormatLong a QString specifying the long date format
745 \value DateFormatShort a QString specifying the short date format
746 \value TimeFormatLong a QString specifying the long time format
747 \value TimeFormatShort a QString specifying the short time format
748 \value DayNameLong a QString specifying the name of a weekday. the in variant contains an integer between 1 and 7 (Monday - Sunday)
749 \value DayNameShort a QString specifying the short name of a weekday. the in variant contains an integer between 1 and 7 (Monday - Sunday)
750 \value MonthNameLong a QString specifying the name of a month. the in variant contains an integer between 1 and 12
751 \value MonthNameShort a QString specifying the short name of a month. the in variant contains an integer between 1 and 12
752 \value DateToStringLong converts the QDate stored in the in variant to a QString using the long date format
753 \value DateToStringShort converts the QDate stored in the in variant to a QString using the short date format
754 \value TimeToStringLong converts the QTime stored in the in variant to a QString using the long time format
755 \value TimeToStringShort converts the QTime stored in the in variant to a QString using the short time format
756 \value DateTimeFormatLong a QString specifying the long date time format
757 \value DateTimeFormatShort a QString specifying the short date time format
758 \value DateTimeToStringLong converts the QDateTime in the in variant to a QString using the long datetime format
759 \value DateTimeToStringShort converts the QDateTime in the in variant to a QString using the short datetime format
760 \value MeasurementSystem a QLocale::MeasurementSystem enum specifying the measurement system
761 \value AMText a string that represents the system AM designator associated with a 12-hour clock.
762 \value PMText a string that represents the system PM designator associated with a 12-hour clock.
763 \value FirstDayOfWeek a Qt::DayOfWeek enum specifiying the first day of the week
764 \value CurrencySymbol a string that represents a currency in a format QLocale::CurrencyFormat.
765 \value CurrencyToString a localized string representation of a number with a currency symbol. Converts a QSystemLocale::CurrencyToStringArgument stored in the in variant to a QString.
766 \value UILanguages a list of strings representing locale names that could be used for UI translation.
767 \value StringToStandardQuotation a QString containing a quoted version of the string ref stored in the in variant using standard quotes.
768 \value StringToAlternateQuotation a QString containing a quoted version of the string ref stored in the in variant using alternate quotes.
769 \value Weekdays a QList<Qt::DayOfWeek> specifying the regular weekdays
770 \value LocaleChanged this type is queried whenever the system locale is changed.
771 \value ListToSeparatedString a string that represents a join of a given QStringList with a locale-defined separator.
772 \value NativeLanguageName a string that represents the name of the native language.
773 \value NativeCountryName a string that represents the name of the native country.
777 \fn QLocale QSystemLocale::fallbackLocale() const
780 Returns the fallback locale obtained from the system.
784 \fn QVariant QSystemLocale::query(QueryType type, QVariant in = QVariant()) const
786 Generic query method for locale data. Provides indirection.
787 Denotes the \a type of the query
788 with \a in as input data depending on the query.
790 \sa QSystemLocale::QueryType
794 \class QSystemLocale::CurrencyToStringArgument
796 A helper class that provides arguments for the QSystemLocale::query()
797 function with query type QSystemLocale::CurrencyToString.
799 \sa QSystemLocale::QueryType
804 \fn QSystemLocale::CurrencyToStringArgument::CurrencyToStringArgument()
808 \variable QSystemLocale::CurrencyToStringArgument::value
810 An input value that should be converted to its string representation.
811 Contains one of QVariant::LongLong, QVariant::ULongLong or QVariant::Double
815 \variable QSystemLocale::CurrencyToStringArgument::symbol
817 An optional argument containing a currency symbol to be used in the
823 \fn QString QLocale::toString(short i) const
831 \fn QString QLocale::toString(ushort i) const
839 \fn QString QLocale::toString(int i) const
847 \fn QString QLocale::toString(uint i) const
855 \fn QString QLocale::toString(long i) const
863 \fn QString QLocale::toString(ulong i) const
871 \fn QString QLocale::toString(float i, char f = 'g', int prec = 6) const
875 \a f and \a prec have the same meaning as in QString::number(double, char, int).
881 \fn QString QLocale::toCurrencyString(short value, const QString &symbol) const
887 \fn QString QLocale::toCurrencyString(ushort value, const QString &symbol) const
893 \fn QString QLocale::toCurrencyString(int value, const QString &symbol) const
899 \fn QString QLocale::toCurrencyString(uint value, const QString &symbol) const
904 \fn QString QLocale::toCurrencyString(float value, const QString &symbol) const