Class TLocale

TLocale

Support

Supported from 5.0

Description

Sets and gets the system’s locale settings.

The operating system maintains the locale information internally. On construction, this object is initialized with the system information for all locale items.

Defined in TLocale:
AmPmSpaceBetween(), AmPmSymbolPosition(), ClockFormat(), CountryCode(), CurrencyDecimalPlaces(), CurrencyNegativeInBrackets(), CurrencySpaceBetween(), CurrencySymbolPosition(), CurrencyTriadsAllowed(), DateFormat(), DateSeparator(), DaylightSaving(), DecimalSeparator(), EInBrackets, EInterveningMinusSign, ELeadingMinusSign, ETrailingMinusSign, FormatCurrency(), HomeDaylightSavingZone(), NegativeCurrencyFormat(), NegativeCurrencySymbolOpposite(), NegativeLoseSpace(), QueryHomeHasDaylightSavingOn(), Refresh(), Set(), SetAmPmSpaceBetween(), SetAmPmSymbolPosition(), SetClockFormat(), SetCountryCode(), SetCurrencyDecimalPlaces(), SetCurrencyNegativeInBrackets(), SetCurrencySpaceBetween(), SetCurrencySymbolPosition(), SetCurrencyTriadsAllowed(), SetDateFormat(), SetDateSeparator(), SetDaylightSaving(), SetDecimalSeparator(), SetHomeDaylightSavingZone(), SetNegativeCurrencyFormat(), SetNegativeCurrencySymbolOpposite(), SetNegativeLoseSpace(), SetStartOfWeek(), SetThousandsSeparator(), SetTimeFormat(), SetTimeSeparator(), SetUnitsDistanceLong(), SetUnitsDistanceShort(), SetUnitsGeneral(), SetUniversalTimeOffset(), SetWorkDays(), StartOfWeek(), TLocale(), TNegativeCurrencyFormat, ThousandsSeparator(), TimeFormat(), TimeSeparator(), UnitsDistanceLong(), UnitsDistanceShort(), UnitsGeneral(), UniversalTimeOffset(), WorkDays()

TLocale();

Description

Constructs this object with settings which are taken from the system's locale settings.

Note that a single copy of the locale information is maintained by the system. When an application constructs a this object, it contains a copy of the system information. This copy may be refreshed under application control with TLocale::Refresh(), and the settings may be saved to the system with TLocale::Set(). However, the settings are never updated by the system apart from under application control. This enables applications to guarantee that consistent locale information is used.

void Refresh();

Description

Refreshes the contents of this object with the system’s locale settings.

void Set() const;

Description

Transfers the locale settings from this object to the system.

After this function has been called, other applications may use the new settings for newly-constructed TLocale objects, or if they use TLocale::Refresh(), to refresh their settings from the system copy.

TInt CountryCode() const;

Description

Returns the code which is used to select country-specific locale data. The country code is the code used as the international dialling prefix. This code is also used to identify a country by the dialling software.

Return value

TInt The country code

void SetCountryCode(TInt aCode);

Description

Sets the value which is used to select country-specific locale data. This value can be retrieved by using TLocale::CountryCode(). The country code is the code used as the international dialling prefix. This code is also used to identify a country by the dialling software.

Parameters

TInt aCode The country code

TLocalePos CurrencySymbolPosition() const;

Description

Returns the currency symbol position. The currency symbol can be located before or after the currency value.

Note:

For negative currency values, this position may be reversed using SetNegativeCurrencySymbolOpposite().

Return value

TLocalePos The currency symbol position.

void SetCurrencySymbolPosition(TLocalePos aPos);

Description

Sets the currency symbol position. The currency symbol can be located either before or after the currency value.

Parameters

TLocalePos aPos The currency symbol position.

TBool CurrencySpaceBetween() const;

Description

Returns whether or not a space is inserted between the currency symbol and the currency value.

Note:

For negative currency values, the space can be removed using SetNegativeLoseSpace().

Return value

TBool True, if a space is inserted; false, otherwise

void SetCurrencySpaceBetween(TBool aSpace);

Description

Sets whether a space must be inserted between the currency symbol and the currency amount.

Parameters

TBool aSpace ETrue if a space must be inserted; EFalse otherwise

TInt CurrencyDecimalPlaces() const;

Description

Returns the number of decimal places to which currency values are set.

Return value

TInt The number of decimal places.

void SetCurrencyDecimalPlaces(TInt aPlaces);

Description

Sets the number of decimal places to which currency values should be set.

Parameters

TInt aPlaces The number of decimal places.

TBool CurrencyNegativeInBrackets() const;

Support

Withdrawn in 6.1

Description

Returns whether negative currency values are enclosed in brackets rather than being preceded by a minus sign.

Note:

From v6.1 onwards, use NegativeCurrencyFormat() instead.

Return value

TBool True if negative currency is enclosed in brackets and has no minus sign; false, if negative currency has a minus sign and is not enclosed in brackets.

void SetCurrencyNegativeInBrackets(TBool aBool);

Support

Withdrawn in 6.1

Description

Sets whether negative currency values are enclosed in brackets rather than being preceded by a minus sign.

Note:

From v6.1 onwards, use SetNegativeCurrencyFormat() instead.

Parameters

TBool aBool ETrue, if a negative currency value must be enclosed in brackets without a minus sign; EFalse, if a negative currency value is preceded by a minus sign without any enclosing brackets.

TBool CurrencyTriadsAllowed() const;

Description

Returns whether triads are allowed in currency values. Triads are groups of three digits separated by the thousands separator.

Return value

TBool True, if triads are allowed; false, otherwise

void SetCurrencyTriadsAllowed(TBool aBool);

Description

Sets whether triads are allowed in currency values.

Parameters

TBool aBool ETrue, if triads are allowed; EFalse, if triads not allowed.

void FormatCurrency(TDes& aText, TInt aAmount);

Support

Supported from 6.1

Description

Renders a currency value as text, based on the locale's currency and numeric format settings.

These settings include the currency symbol, the symbol's position and the way negative values are formatted. If the descriptor aText is not long enough to hold the formatted value, a panic (USER 11) occurs.

Parameters

TDes& aText On return, contains the currency value as text, formatted according to the locale's currency format settings. TInt aAmount The currency value that is to be formatted.

void FormatCurrency(TDes& aText, TInt64 aAmount);

Support

Supported from 6.1

Description

Renders a currency value as text, based on the locale's currency and numeric format settings.

These settings include the currency symbol, the symbol's position and the way negative values are formatted. If the descriptor aText is not long enough to hold the formatted value, a panic (USER 11) occurs. This function is provided for very large currency values.

Parameters

TDes& aText On return, contains the currency value as text, formatted according to the locale's currency format settings. TInt64 aAmount The currency value that is to be formatted.

void FormatCurrency(TDes& aText, TDesOverflow& aOverflowHandler, TInt aAmount);

Support

Supported from 6.1

Description

Renders a currency value as text, based on the locale's currency and numeric format settings.

These settings include the currency symbol, the symbol's position and the way negative values are formatted. If aText is not long enough to hold the formatted currency value, the overflow handler's Overflow() function is called.

Parameters

TDes& aText On return, contains the currency value as text, formatted according to the locale's currency format settings. TDesOverflow& aOverflowHandler An object derived from TDesOverflow which handles descriptor overflows. TInt aAmount The currency value that is to be formatted.

void FormatCurrency(TDes& aText, TDesOverflow& aOverflowHandler, TInt64 aAmount);

Support

Supported from 6.1

Description

Renders a currency value as text, based on the locale's currency and numeric format settings.

These settings include the currency symbol, the symbol's position and the way negative values are formatted. If aText is not long enough to hold the formatted currency value, the overflow handler's Overflow() function is called. This function is provided for very large currency values.

Parameters

TDes& aText On return, contains the currency value as text, formatted according to the locale's currency format settings. TDesOverflow& aOverflowHandler An object derived from TDesOverflow which handles descriptor overflows. TInt64 aAmount The currency value that is to be formatted.

TNegativeCurrencyFormat NegativeCurrencyFormat() const;

Support

Supported from 6.1

Description

Gets the negative currency format.

Return value

TNegativeCurrencyFormat How negative currency values are formatted.

See also:

• TNegativeCurrencyFormat

void SetNegativeCurrencyFormat(TNegativeCurrencyFormat aNegativeCurrencyFormat);

Support

Supported from 6.1

Description

Sets the negative currency format.

Parameters

TNegativeCurrencyFormat aNegativeCurrencyFormat How negative currency values are formatted.

See also:

• TNegativeCurrencyFormat

TBool NegativeLoseSpace()

Support

Supported from 6.1

Description

Returns whether negative currency values lose the space between the currency symbol and the value.

Return value

TBool ETrue if negative currency values lose the space between the value and the symbol. EFalse if not.

void SetNegativeLoseSpace(TBool aBool);

Support

Supported from 6.1

Description

Sets whether negative currency values lose the space between the currency symbol and the value.

Parameters

TBool aBool ETrue to set a flag which indicates that negative currency values should lose the space between the value and the symbol. EFalse to unset it.

TBool NegativeCurrencySymbolOpposite() const;

Support

Supported from 6.1

Description

Returns whether in negative currency values, the position of the currency symbol is set to be the opposite of the position used for non-negative values (before or after the value — as set by SetCurrencySymbolPosition()).

Return value

TBool ETrue if the currency symbol position for negative currency values is the opposite of the position set by SetCurrencySymbolPosition(). EFalse if not.

void SetNegativeCurrencySymbolOpposite(TBool aBool);

Support

Supported from 6.1

Description

Sets whether the position of the currency symbol for negative currency values should be the opposite of the position used for non-negative values (before or after the value — as set by SetCurrencySymbolPosition()).

Parameters

TBool aBool ETrue to set the position of the currency symbol in negative currency values to be the opposite of the position as set using SetCurrencySymbolPosition(). EFalse to leave the position unchanged.

TChar ThousandsSeparator() const;

Description

Returns the character used to separate groups of three digits to the left of the decimal separator.

Notes:

A thousands separator character is only displayed in currency values if currency triads are allowed.

Return value

TChar The character used as the thousands separator

void SetThousandsSeparator(const TChar& aChar);

Description

Sets the character to be used to separate groups of three digits to the left of the decimal separator.

Notes

A thousands separator character is only displayed in currency values if currency triads are allowed.

Parameters

const TChar& aChar The character to be used as the thousands separator.

TChar DecimalSeparator() const;

Description

Returns the character used to separate a whole number from its fractional part.

Return value

TChar The character used as the decimal separator.

void SetDecimalSeparator(const TChar& aChar);

Description

Sets the character to be used to separate a whole number from its fractional part.

Parameters

const TChar& aChar The character to be used as the decimal separator.

TChar DateSeparator(TInt aIndex) const;

Description

Returns one of the four characters used to separate the day, month and year components of the date.

If the four separators are represented by S0, S1, S2 and S3 and the three date components are represented by XX, YY and ZZ, then the separators are located: S0 XX S1 YY S2 ZZ S3.

Parameters

TInt aIndex An index indicating which of the four separators is being accessed. This must be a value between zero and three inclusive.

Return value

TChar A date separator character as determined by the value of aIndex.

void SetDateSeparator(const TChar& aChar,TInt aIndex);

Description

Sets one of the four characters used to separate the day, month and year components of the date.

If the four separators are represented by S0, S1, S2 and S3 and the three date components are represented by XX, YY and ZZ, then the separators are located: S0 XX S1 YY S2 ZZ S3.

Parameters

const TChar& aChar A date separator character to be used. TInt aIndex An index indicating which of the four separators is being accessed. This must be a value between zero and three inclusive.

TDateFormat DateFormat() const;

Description

Returns the date format.

Return value

TDateFormat The date format

void SetDateFormat(TDateFormat aFormat);

Description

Sets the date format.

Parameters

TDateFormat aFormat The date format to be used

TTimeFormat TimeFormat() const;

Description

Returns the time format. This indicates whether the 12 or 24 hour clock format is used.

Return value

TTimeFormat The time format

void SetTimeFormat(TTimeFormat aFormat);

Description

Sets the time format. This indicates whether the 12 or 24 hour clock format is to be used.

Parameters

TTimeFormat aFormat The time format to be used

TChar TimeSeparator(TInt aIndex) const;

Description

Returns one of the four characters used to separate the hour, second and minute components of the time.

If the four separators are represented by S0, S1, S2 and S3 and the three time components are represented by XX, YY and ZZ, then the separators are located: S0 XX S1 YY S2 ZZ S3.

Parameters

TInt aIndex An index indicating which of the four separators is being accessed. This must be a value between zero and three inclusive.

Return value

TChar A time separator character as determined by the value of aIndex.

void SetTimeSeparator(const TChar& aChar,TInt aIndex);

Description

Sets one of the four characters used to separate the hour, minute and second components of the date.

If the four separators are represented by S0, S1, S2 and S3 and the three time components are represented by XX, YY and ZZ, then the separators are located: S0 XX S1 YY S2 ZZ S3.

Parameters

const TChar& aChar A time separator character to be used. TInt aIndex An index indicating which of the four separators is being accessed. This must be a value between zero and three inclusive.

TBool AmPmSpaceBetween() const;

Description

Determines whether or not a space is inserted between the time and preceding or trailing am/pm text.

Return value

TBool True, if a space is inserted between the time and am/pm text; false, otherwise

void SetAmPmSpaceBetween(TBool aSpace);

Description

Sets whether a space must be inserted between the time and preceding or trailing am/pm text.

Parameters

TBool aSpace ETrue if a space must be inserted between the time and am/pm text;EFalse otherwise

TLocalePos AmPmSymbolPosition() const;

Description

Returns the am/pm text position. The am/pm text is located before or after the time value.

Return value

TLocalePos The am/pm text position

void SetAmPmSymbolPosition(TLocalePos aPos);

Description

Sets the am/pm text position. The am/pm text can be located either before or after the time value.

Parameters

TLocalePos aPos The am/pm text position

TClockFormat ClockFormat() const;

Description

Returns the clock display format.

Return value

TClockFormat The clock display format.

void SetClockFormat(TClockFormat aFormat);

Description

Sets the clock display format.

Parameters

TClockFormat aFormat The clock display format.

TUint WorkDays() const;

Description

Returns a bit mask representing the days of the week which are considered as working days.

Return value

TUint A bit mask of seven bits indicating (by being set) which days are to be considered workdays. The least significant bit corresponds to Monday, the next bit to Tuesday and so on.

void SetWorkDays(TUint aMask);

Description

Sets the days of the week which are considered as working days.

Parameters

TUint aMask A mask of seven bits indicating (by being set) which days are to be considered workdays. The least significant bit corresponds to Monday, the next bit is Tuesday and so on.

TDay StartOfWeek() const;

Description

Returns the day which is considered the first day of the week.

Return value

TDay The first day of the week.

void SetStartOfWeek(TDay aDay);

Description

Sets the day which is considered to be the first day of the week.

Parameters

TDay aDay The first day of the week.

TTimeIntervalSeconds UniversalTimeOffset() const;

Description

Returns the locale’s universal time offset.

Return value

TTimeIntervalSeconds Offset in seconds from universal time. Time zones east of universal time have positive offsets. Time zones west of universal time have negative offsets.

void SetUniversalTimeOffset(const TTimeIntervalSeconds& anOffset);

Description

Sets the locale’s universal time offset.

Parameters

const TTimeIntervalSeconds& anOffset Offset in seconds from universal time. Time zones east of universal time have positive offsets. Time zones west of universal time have negative offsets.

TUint DaylightSaving() const;

Description

Returns the daylight saving zones in which daylight saving is in effect. The function returns a bit mask in which the three least significant bits are defined. These bits represent Northern (non-European countries in the northern hemisphere), Southern (southern hemisphere), and European.

Notes

If daylight saving is in effect, one hour is added to the time.

Use TLocale::QueryHomeHasDaylightSavingOn() rather than this function to get whether daylight saving is in effect for the home city. This is because the daylight saving setting for the home city may differ from that of the zone in which home is located.

Return value

TUint A bit mask indicating which of the three daylight saving zones should be adjusted for daylight saving. For more information, see the TDaylightSavingZone enumeration.

void SetDaylightSaving(TUint aDaylightSaving);

Description

Sets the daylight saving zones in which daylight saving is in effect. The function uses a bit mask in which the three least significant bits are defined plus a fourth bit for home. These bits represent European, Northern (non-European countries in the northern hemisphere) and Southern (southern hemisphere).

Notes

The daylight saving setting for the home city normally corresponds to the setting for the zone in which home is located. However they may differ.

Assuming home is located in Europe,

• to set home and unset Europe, use TLocale::SetDaylightSaving(EDstHome). In this case, the home bit overrides the Europe bit.

• to unset home and set Europe, home must be removed from the Europe daylight saving zone. First set both home and Europe by using TLocale::SetDaylightSaving(EDstEurope). Then, remove home from Europe by using TLocale::SetHomeDaylightSavingZone(EDstNone). Home daylight saving is now unset while Europe remains set.

Parameters

TUint aMask A bit mask indicating which of four daylight saving zones should be adjusted for daylight saving. To unset all daylight saving zones, specify EDstNone. For more information, see the TDaylightSavingZone enumeration.

TBool QueryHomeHasDaylightSavingOn() const;

Description

Determines whether or not daylight saving is set for the home city.

Return value

TBool True, if home daylight saving is set; false, otherwise.

TDaylightSavingZone HomeDaylightSavingZone() const;

Description

Returns the daylight saving zone in which the home city is located.

Return value

TDaylightSavingZone European, non European in the northern hemisphere, southern hemisphere, or none.

void SetHomeDaylightSavingZone(TDaylightSavingZone aZone);

Description

Sets the daylight saving zone in which the home city is located.

Parameters

TDaylightSavingZone aZone European, non European in the Northern hemisphere, Southern hemisphere, or none.

TUnitsFormat UnitsGeneral() const;

Description

Returns the general units of measurement. This function should be used when both short and long distances use the same units of measurement.

Return value

TUnitsFormat General units of measurement.

void SetUnitsGeneral(TUnitsFormat aFormat);

Description

Sets the general units of measurement. This function should be used when both short and long distances use the same units of measurement.

Parameters

TUnitsFormat aFormat General units of measurement.

TUnitsFormat UnitsDistanceShort() const;

Description

Returns the units of measurement for short distances. Short distances are those which would normally be represented by either meters and centimetres or feet and inches.

Return value

TUnitsFormat Units of measurement for short distances.

void SetUnitsDistanceShort(TUnitsFormat aFormat);

Description

Sets the units of measurement for short distances. Short distances are those which would normally be represented by either meters and centimetres or feet and inches.

Parameters

TUnitsFormat aFormat Units of measurement for short distances.

TUnitsFormat UnitsDistanceLong() const;

Description

Returns the units of measurement for long distances. Long distances are those which would normally be represented by either miles or kilometres.

Return value

TUnitsFormat Units of measurement for long distances.

void SetUnitsDistanceLong(TUnitsFormat aFormat);

Description

Sets the units of measurement for long distances. Long distances are those which would normally be represented by either miles or kilometres.

Parameters

TUnitsFormat aFormat Units of measurement for long distances.

TNegativeCurrencyFormat

Support

Supported from 6.1

Description

Indicates how negative currency values are formatted.

ELeadingMinusSign A minus sign is inserted before the currency value and symbol. EInBrackets The currency value and symbol are enclosed in brackets (no minus sign is used). ETrailingMinusSign A minus sign is inserted after the currency value and symbol. EInterveningMinusSign A minus sign is inserted between the currency symbol and the value.