QLocale Class

The QLocale class converts between numbers, dates and their string representations in various languages. More…

List of all members, including inherited members

Public Types

Public Functions

Static Public Members

Detailed Description

A QLocale is initialized with a language, an optional script and a territory, or with a name such as "de_DE". It formats and parses numbers, dates and times, currency amounts and lists the way that locale writes them:

QLocale german(QLocale::German, QLocale::Germany);
QString s = german.toString(1234567.891, 'f', 2);   // "1.234.567,89"
double d = german.toDouble(u"1.234,5"_s);           // 1234.5
QString date = german.toString(QDate(2024, 5, 1));  // "Mittwoch, 1. Mai 2024"

The default-constructed QLocale is the default locale, which is the system locale (taken from the LC_ALL, LC_NUMERIC or LANG environment variables) unless setDefault() was called. QLocale::c() is the "C" locale, which formats numbers like QString::number().

See also QString::arg(), QCollator, QDate and QDateTime.

Differences from Qt

Member Type Documentation

typedef QLocale::Country

Same as Territory, the name used before Qt 6.2.

enum QLocale::CurrencySymbolFormat

enum QLocale::DataSizeFormat

This function was introduced in 5.10.

typedef QLocale::DataSizeFormats

The DataSizeFormats type is a typedef for QFlags<DataSizeFormat>. It stores an OR combination of DataSizeFormat values.

enum QLocale::FloatingPointPrecisionOption

This function was introduced in 5.7.

enum QLocale::FormatType

enum QLocale::Language

The language of a locale. Locale data exists only for some of them; see the class description.

enum QLocale::MeasurementSystem

enum QLocale::NumberOption

typedef QLocale::NumberOptions

The NumberOptions type is a typedef for QFlags<NumberOption>. It stores an OR combination of NumberOption values.

enum QLocale::QuotationStyle

This function was introduced in 4.8.

enum QLocale::Script

The script in which a language is written.

enum QLocale::TagSeparator

This function was introduced in 6.7.

enum QLocale::Territory

The territory (country or region) of a locale.

This function was introduced in 6.2.

Member Function Documentation

QLocale::QLocale()

Constructs a QLocale object initialized with the default locale: the locale set with setDefault(), or else the system locale.

See also setDefault() and system().

[explicit] QLocale::QLocale(const QString &name)

Constructs a locale from the name name, which has the format language[_script][_territory] (dashes may be used instead of underscores), such as "de", "de_CH" or "zh_Hant_TW". An encoding or modifier suffix, as in "de_DE.UTF-8", is ignored. If the name is not recognized or Nt has no data for it, the C locale is used.

[explicit] QLocale::QLocale(QStringView name)

This is an overloaded function.

Constructs a locale from the name viewed by name.

This function was introduced in 6.3.

QLocale::QLocale(Language language, Territory territory = AnyTerritory)

Constructs a locale for language and territory. If there is no data for the territory, the main territory of the language is used; if there is no data for the language, the C locale is used.

QLocale::QLocale(Language language, Script script, Territory territory)

Constructs a locale for language written in script in territory.

QLocale::QLocale(const QLocale &other)

Constructs a copy of other.

QLocale::~QLocale()

Destroys the locale.

QString QLocale::amText() const

Returns the text the locale uses for times before noon, such as "AM".

QString QLocale::bcp47Name(TagSeparator separator = TagSeparator::Dash) const

Returns the BCP 47 name of the locale, using separator between the parts. The territory is left out when it is the main territory of the language, so the name of en_US is "en" and that of en_GB is "en-GB".

See also name() and uiLanguages().

[static] QLocale QLocale::c()

Returns the "C" locale, which formats numbers like QString::number() and uses English names.

[static] Language QLocale::codeToLanguage(QStringView languageCode)

Returns the language with the ISO 639 code languageCode (case does not matter), or AnyLanguage if it is not known.

This function was introduced in 6.1.

[static] Script QLocale::codeToScript(QStringView scriptCode)

Returns the script with the ISO 15924 code scriptCode (case does not matter), or AnyScript if it is not known.

This function was introduced in 6.1.

[static] Territory QLocale::codeToTerritory(QStringView territoryCode)

Returns the territory with the ISO 3166 code territoryCode (case does not matter), or AnyTerritory if it is not known.

This function was introduced in 6.2.

QLocale QLocale::collation() const

Returns the locale to use for collation, which is this locale.

This function was introduced in 5.13.

See also QCollator.

Country QLocale::country() const

Same as territory().

[static] QString QLocale::countryToString(Country country)

Same as territoryToString(country).

QString QLocale::createSeparatedList(const QStringList &list) const

Returns the strings of list joined as the locale writes a list, such as "a, b, and c" in American English.

This function was introduced in 4.8.

QString QLocale::currencySymbol(CurrencySymbolFormat format = CurrencySymbol) const

Returns the currency symbol of the locale in the form format. The C locale has no currency, so all forms are empty.

This function was introduced in 4.8.

QString QLocale::dateFormat(FormatType format = LongFormat) const

Returns the date format of the locale for format, such as "dddd, MMMM d, yyyy" for the long format of en_US.

See also timeFormat() and toString().

QString QLocale::dateTimeFormat(FormatType format = LongFormat) const

Returns the date and time format of the locale for format: the date format and the time format separated by a space.

QString QLocale::dayName(int day, FormatType format = LongFormat) const

Returns the name of day (1 is Monday, 7 is Sunday) in the form format. Returns an empty string for an invalid day.

QString QLocale::decimalPoint() const

Returns the decimal separator of the locale.

See also groupSeparator() and toString().

QString QLocale::exponential() const

Returns the exponent separator of the locale, which is always "e" in Nt.

Qt::DayOfWeek QLocale::firstDayOfWeek() const

Returns the first day of the week in the locale, such as Qt::Sunday in the United States and Qt::Monday in most of Europe.

This function was introduced in 4.8.

QString QLocale::formattedDataSize(qint64 bytes, int precision = 2, DataSizeFormats format = DataSizeIecFormat) const

Returns bytes as a size with a unit, such as "1.50 MiB", with precision digits after the decimal point. format selects powers of 1024 or 1000 and the IEC or SI prefixes. Sizes below the first unit are written in bytes. The unit names are not translated.

This function was introduced in 5.10.

QString QLocale::groupSeparator() const

Returns the digit group separator of the locale.

See also decimalPoint() and numberOptions().

Language QLocale::language() const

Returns the language of the locale.

[static] QString QLocale::languageToCode(Language language)

Returns the ISO 639 code of language, such as "de".

This function was introduced in 6.1.

See also codeToLanguage().

[static] QString QLocale::languageToString(Language language)

Returns the English name of language.

[static] QList<QLocale> QLocale::matchingLocales(Language language, Script script, Territory territory)

Returns the locales with data that match language, script and territory. AnyLanguage, AnyScript and AnyTerritory match everything.

This function was introduced in 4.8.

MeasurementSystem QLocale::measurementSystem() const

Returns the measurement system of the locale.

QString QLocale::monthName(int month, FormatType format = LongFormat) const

Returns the name of month (1 to 12) in the form format, as used in dates. In some languages, such as Russian or Polish, this is a different grammatical form from standaloneMonthName(). Returns an empty string for an invalid month.

QString QLocale::name(TagSeparator separator = TagSeparator::Underscore) const

Returns the name of the locale as language_territory, such as "de_DE", using separator between the parts, or "C".

See also bcp47Name().

QString QLocale::nativeCountryName() const

Same as nativeTerritoryName().

QString QLocale::nativeLanguageName() const

Returns the name of the language in that language, such as "Deutsch".

This function was introduced in 4.8.

QString QLocale::nativeTerritoryName() const

Returns the name of the territory in the language of the locale, such as "Deutschland".

This function was introduced in 6.2.

QString QLocale::negativeSign() const

Returns the negative sign of the locale. Some locales, such as Swedish, use U+2212 MINUS SIGN.

NumberOptions QLocale::numberOptions() const

Returns the number options of this locale. They are OmitGroupSeparator for the C locale and DefaultNumberOptions for the others.

See also setNumberOptions().

QLocale & QLocale::operator=(const QLocale &other)

Assigns other to this locale and returns a reference to this locale.

QString QLocale::percent() const

Returns the percent sign of the locale.

QString QLocale::pmText() const

Returns the text the locale uses for times after noon, such as "PM".

QString QLocale::positiveSign() const

Returns the positive sign of the locale.

QString QLocale::quoteString(QStringView str, QuotationStyle style = StandardQuotation) const

Returns str enclosed in the quotation marks of the locale, in the style style.

This function was introduced in 4.8.

Script QLocale::script() const

Returns the script of the locale.

[static] QString QLocale::scriptToCode(Script script)

Returns the ISO 15924 code of script, such as "Latn".

This function was introduced in 6.1.

See also codeToScript().

[static] QString QLocale::scriptToString(Script script)

Returns the English name of script.

[static] void QLocale::setDefault(const QLocale &locale)

Sets the default locale, which default-constructed QLocale objects use, to locale. It does not change locales that already exist.

See also system().

void QLocale::setNumberOptions(NumberOptions options)

Sets the number options of this locale to options.

See also numberOptions().

QString QLocale::standaloneDayName(int day, FormatType format = LongFormat) const

Returns the name of day (1 is Monday, 7 is Sunday) in the form format, as used on its own.

QString QLocale::standaloneMonthName(int month, FormatType format = LongFormat) const

Returns the name of month (1 to 12) in the form format, as used on its own, for example in a calendar heading.

void QLocale::swap(QLocale &other)

Swaps this locale with other.

[static] QLocale QLocale::system()

Returns the system locale, taken from the first of the LC_ALL, LC_NUMERIC and LANG environment variables that is set.

See also setDefault().

Territory QLocale::territory() const

Returns the territory of the locale.

This function was introduced in 6.2.

[static] QString QLocale::territoryToCode(Territory territory)

Returns the ISO 3166 code of territory, such as "DE".

This function was introduced in 6.2.

See also codeToTerritory().

[static] QString QLocale::territoryToString(Territory territory)

Returns the English name of territory.

This function was introduced in 6.2.

Qt::LayoutDirection QLocale::textDirection() const

Returns the direction in which the language of the locale is written. All locales with data in Nt are written left to right.

This function was introduced in 4.7.

QString QLocale::timeFormat(FormatType format = LongFormat) const

Returns the time format of the locale for format.

See also dateFormat().

QString QLocale::toCurrencyString(qlonglong value, const QString &symbol = QString()) const

Returns value as a currency amount in the locale, with symbol or, if it is empty, the currency symbol of the locale. Integers are written without decimals.

This function was introduced in 4.8.

See also currencySymbol().

QString QLocale::toCurrencyString(qulonglong value, const QString &symbol = QString()) const

This is an overloaded function.

Returns the unsigned value as a currency amount with symbol.

QString QLocale::toCurrencyString(int value, const QString &symbol = QString()) const

This is an overloaded function.

QString QLocale::toCurrencyString(uint value, const QString &symbol = QString()) const

This is an overloaded function.

QString QLocale::toCurrencyString(double value, const QString &symbol = QString(), int precision = -1) const

This is an overloaded function.

Returns value as a currency amount with symbol and precision digits after the decimal point. A negative precision uses the number of digits of the currency, such as 2 for the euro and 0 for the yen.

This function was introduced in 5.7.

QDate QLocale::toDate(const QString &string, FormatType format = LongFormat) const

Returns the date in string, which must be in the date format format of the locale, or an invalid date.

See also toString() and dateFormat().

QDate QLocale::toDate(const QString &string, const QString &format) const

This is an overloaded function.

Returns the date in string, which must follow the format string format, or an invalid date. Month and day names are those of the locale and are matched regardless of case. Missing fields default to 1900-01-01.

QDateTime QLocale::toDateTime(const QString &string, FormatType format = LongFormat) const

Returns the date and time in string, which must be in the date and time format format of the locale, or an invalid QDateTime.

QDateTime QLocale::toDateTime(const QString &string, const QString &format) const

This is an overloaded function.

Returns the date and time in string, which must follow the format string format, or an invalid QDateTime. A t field accepts UTC, UTC+hh:mm and Z; any other zone name is skipped and the result is in local time.

double QLocale::toDouble(QStringView s, bool *ok = nullptr) const

Returns the floating-point number in s, written with the decimal separator of the locale, or 0 if it is not valid. If ok is not nullptr, it is set to whether the conversion succeeded.

See also toString() and toInt().

float QLocale::toFloat(QStringView s, bool *ok = nullptr) const

Returns the number in s as a float, or 0 if it is not valid or out of the range of float; sets ok as toDouble() does.

int QLocale::toInt(QStringView s, bool *ok = nullptr) const

Returns the number in s as an int; sets ok as toShort() does.

long QLocale::toLong(QStringView s, bool *ok = nullptr) const

Returns the number in s as a long; sets ok as toShort() does.

qlonglong QLocale::toLongLong(QStringView s, bool *ok = nullptr) const

Returns the number in s as a qlonglong; sets ok as toShort() does.

QString QLocale::toLower(const QString &str) const

Returns str converted to lowercase, using the simple case mappings of Unicode.

This function was introduced in 4.8.

short QLocale::toShort(QStringView s, bool *ok = nullptr) const

Returns the number in s as a short, or 0 if it is not a valid number for the locale or out of range. If ok is not nullptr, it is set to whether the conversion succeeded. Group separators are accepted in the right places unless numberOptions() contains RejectGroupSeparator; leading and trailing white space is ignored.

QString QLocale::toString(qlonglong i) const

Returns the integer i formatted for the locale, with group separators unless numberOptions() contains OmitGroupSeparator.

See also toLongLong() and toCurrencyString().

QString QLocale::toString(qulonglong i) const

This is an overloaded function.

Returns the unsigned integer i formatted for the locale.

QString QLocale::toString(long i) const

This is an overloaded function.

QString QLocale::toString(ulong i) const

This is an overloaded function.

QString QLocale::toString(int i) const

This is an overloaded function.

QString QLocale::toString(uint i) const

This is an overloaded function.

QString QLocale::toString(short i) const

This is an overloaded function.

QString QLocale::toString(ushort i) const

This is an overloaded function.

QString QLocale::toString(double f, char format = 'g', int precision = 6) const

This is an overloaded function.

Returns the floating-point number f formatted for the locale. format is one of 'e', 'E', 'f', 'g' and 'G', as for QString::number(), and precision is the number of digits after the decimal point ('e', 'f') or of significant digits ('g'), or FloatingPointShortest.

See also toDouble().

QString QLocale::toString(float f, char format = 'g', int precision = 6) const

This is an overloaded function.

QString QLocale::toString(QDate date, const QString &format) const

This is an overloaded function.

Returns date formatted with the format string format, using the month and day names of the locale. The format uses the expressions of QDate::toString(): d, dd, ddd, dddd, M, MM, MMM, MMMM, yy, yyyy and quoted text.

QString QLocale::toString(QTime time, const QString &format) const

This is an overloaded function.

Returns time formatted with the format string format: h, hh, H, HH, m, mm, s, ss, z, zzz, AP, ap, t and quoted text. AM and PM are the texts of the locale.

QString QLocale::toString(const QDateTime &dateTime, const QString &format) const

This is an overloaded function.

Returns dateTime formatted with the format string format, which may use the date and the time expressions.

QString QLocale::toString(QDate date, FormatType format = LongFormat) const

This is an overloaded function.

Returns date in the date format format of the locale.

See also dateFormat().

QString QLocale::toString(QTime time, FormatType format = LongFormat) const

This is an overloaded function.

Returns time in the time format format of the locale.

See also timeFormat().

QString QLocale::toString(const QDateTime &dateTime, FormatType format = LongFormat) const

This is an overloaded function.

Returns dateTime in the date and time format format of the locale.

See also dateTimeFormat().

QTime QLocale::toTime(const QString &string, FormatType format = LongFormat) const

Returns the time in string, which must be in the time format format of the locale, or an invalid time.

QTime QLocale::toTime(const QString &string, const QString &format) const

This is an overloaded function.

Returns the time in string, which must follow the format string format, or an invalid time.

uint QLocale::toUInt(QStringView s, bool *ok = nullptr) const

Returns the number in s as an unsigned int; sets ok as toShort() does.

ulong QLocale::toULong(QStringView s, bool *ok = nullptr) const

Returns the number in s as an unsigned long; sets ok as toShort() does.

qulonglong QLocale::toULongLong(QStringView s, bool *ok = nullptr) const

Returns the number in s as a qulonglong; sets ok as toShort() does.

QString QLocale::toUpper(const QString &str) const

Returns str converted to uppercase, using the simple case mappings of Unicode.

This function was introduced in 4.8.

ushort QLocale::toUShort(QStringView s, bool *ok = nullptr) const

Returns the number in s as an unsigned short; sets ok as toShort() does.

QStringList QLocale::uiLanguages(TagSeparator separator = TagSeparator::Dash) const

Returns the languages to use for translations in this locale, most preferred first, with separator between the parts of each name: the full name with the territory, then the language alone.

This function was introduced in 4.8.

See also bcp47Name() and QTranslator::load().

QList<Qt::DayOfWeek> QLocale::weekdays() const

Returns the working days of the week in the locale, Monday to Friday for all locales that Nt knows.

This function was introduced in 4.8.

QString QLocale::zeroDigit() const

Returns the zero digit of the locale. It is always "0" in Nt.