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 \li If a QLocale object is constructed with the default constructor,
55 it will use the default locale's settings.
56 \li 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 \li 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 \li If the language/country pair is found in the database, it is used.
73 \li 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 \li 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.9.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 ImperialUSSystem This value indicates imperial units, such as inches and
676 miles as they are used in the United States.
677 \value ImperialUKSystem This value indicates imperial units, such as inches and
678 miles as they are used in the United Kingdom.
679 \value ImperialSystem Provided for compatibility. Same as ImperialUSSystem
686 \fn bool QLocale::operator==(const QLocale &other) const
688 Returns true if the QLocale object is the same as the \a other
689 locale specified; otherwise returns false.
693 \fn bool QLocale::operator!=(const QLocale &other) const
695 Returns true if the QLocale object is not the same as the \a other
696 locale specified; otherwise returns false.
700 \enum QLocale::QuotationStyle
702 This enum defines a set of possible styles for locale specific quotation.
704 \value StandardQuotation If this option is set, the standard quotation marks
705 will be used to quote strings.
706 \value AlternateQuotation If this option is set, the alternate quotation marks
707 will be used to quote strings.
717 \brief The QSystemLocale class can be used to finetune the system locale
723 \warning This class is only useful in very rare cases. Usually QLocale offers
724 all the functionality required for application development.
726 QSystemLocale allows to override the values provided by the system
727 locale (QLocale::system()).
733 \enum QSystemLocale::QueryType
735 Specifies the type of information queried by query(). For each value
736 the type of information to return from the query() method is listed.
738 \value LanguageId a uint specifying the language.
739 \value ScriptId a uint specifying the script.
740 \value CountryId a uint specifying the country.
741 \value DecimalPoint a QString specifying the decimal point.
742 \value GroupSeparator a QString specifying the group separator.
743 \value ZeroDigit a QString specifying the zero digit.
744 \value NegativeSign a QString specifying the minus sign.
745 \value PositiveSign a QString specifying the plus sign.
746 \value DateFormatLong a QString specifying the long date format
747 \value DateFormatShort a QString specifying the short date format
748 \value TimeFormatLong a QString specifying the long time format
749 \value TimeFormatShort a QString specifying the short time format
750 \value DayNameLong a QString specifying the name of a weekday. the in variant contains an integer between 1 and 7 (Monday - Sunday)
751 \value DayNameShort a QString specifying the short name of a weekday. the in variant contains an integer between 1 and 7 (Monday - Sunday)
752 \value MonthNameLong a QString specifying the name of a month. the in variant contains an integer between 1 and 12
753 \value MonthNameShort a QString specifying the short name of a month. the in variant contains an integer between 1 and 12
754 \value DateToStringLong converts the QDate stored in the in variant to a QString using the long date format
755 \value DateToStringShort converts the QDate stored in the in variant to a QString using the short date format
756 \value TimeToStringLong converts the QTime stored in the in variant to a QString using the long time format
757 \value TimeToStringShort converts the QTime stored in the in variant to a QString using the short time format
758 \value DateTimeFormatLong a QString specifying the long date time format
759 \value DateTimeFormatShort a QString specifying the short date time format
760 \value DateTimeToStringLong converts the QDateTime in the in variant to a QString using the long datetime format
761 \value DateTimeToStringShort converts the QDateTime in the in variant to a QString using the short datetime format
762 \value MeasurementSystem a QLocale::MeasurementSystem enum specifying the measurement system
763 \value AMText a string that represents the system AM designator associated with a 12-hour clock.
764 \value PMText a string that represents the system PM designator associated with a 12-hour clock.
765 \value FirstDayOfWeek a Qt::DayOfWeek enum specifiying the first day of the week
766 \value CurrencySymbol a string that represents a currency in a format QLocale::CurrencyFormat.
767 \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.
768 \value UILanguages a list of strings representing locale names that could be used for UI translation.
769 \value StringToStandardQuotation a QString containing a quoted version of the string ref stored in the in variant using standard quotes.
770 \value StringToAlternateQuotation a QString containing a quoted version of the string ref stored in the in variant using alternate quotes.
771 \value Weekdays a QList<Qt::DayOfWeek> specifying the regular weekdays
772 \value LocaleChanged this type is queried whenever the system locale is changed.
773 \value ListToSeparatedString a string that represents a join of a given QStringList with a locale-defined separator.
774 \value NativeLanguageName a string that represents the name of the native language.
775 \value NativeCountryName a string that represents the name of the native country.
779 \fn QLocale QSystemLocale::fallbackLocale() const
782 Returns the fallback locale obtained from the system.
786 \fn QVariant QSystemLocale::query(QueryType type, QVariant in = QVariant()) const
788 Generic query method for locale data. Provides indirection.
789 Denotes the \a type of the query
790 with \a in as input data depending on the query.
792 \sa QSystemLocale::QueryType
796 \class QSystemLocale::CurrencyToStringArgument
798 A helper class that provides arguments for the QSystemLocale::query()
799 function with query type QSystemLocale::CurrencyToString.
801 \sa QSystemLocale::QueryType
806 \fn QSystemLocale::CurrencyToStringArgument::CurrencyToStringArgument()
810 \variable QSystemLocale::CurrencyToStringArgument::value
812 An input value that should be converted to its string representation.
813 Contains one of QVariant::LongLong, QVariant::ULongLong or QVariant::Double
817 \variable QSystemLocale::CurrencyToStringArgument::symbol
819 An optional argument containing a currency symbol to be used in the
825 \fn QString QLocale::toString(short i) const
833 \fn QString QLocale::toString(ushort i) const
841 \fn QString QLocale::toString(int i) const
849 \fn QString QLocale::toString(uint i) const
857 \fn QString QLocale::toString(long i) const
865 \fn QString QLocale::toString(ulong i) const
873 \fn QString QLocale::toString(float i, char f = 'g', int prec = 6) const
877 \a f and \a prec have the same meaning as in QString::number(double, char, int).
883 \fn QString QLocale::toCurrencyString(short value, const QString &symbol) const
889 \fn QString QLocale::toCurrencyString(ushort value, const QString &symbol) const
895 \fn QString QLocale::toCurrencyString(int value, const QString &symbol) const
901 \fn QString QLocale::toCurrencyString(uint value, const QString &symbol) const
906 \fn QString QLocale::toCurrencyString(float value, const QString &symbol) const