\brief The HbExtendedLocale class is an extension class to Qlocale.

    Your application must be able to format language- and region-dependent 

    elements correctly (for example, dates, times, and currencies) based on the 

    active locale settings. HbExtendedLocale is inherited from the QLocale 

    class, and extends the %Qt locale model by providing access to Symbian 

    platform locale data. The HbStringUtil, HbNumberGrouping, and HbLocaleUtil 

    classes also provide some locale-related functionality.

    In Symbian devices, users can modify some locale settings, such as the time 

    and date format and the separator characters used, or the digits used. If 

    the user changes the device language, the changes made for the previous 

    language are saved, and will be restored when the user switches back to that 

    language. For example, if the user often switches between two languages that 

    use a different date format, the user can define a different date format to 

    be used for each device language. The device may also modify some locale-

    related settings automatically, for example, update the date from the 

    network due to a daylight savings change, or if the user moves to a 

    different time zone.

    With HbExtendedLocale, you access the active locale data in the device, 

    whether it is the predefined locale data provided by the platform, or data 

    modified by the user or the device.

    HbExtendedLocale also provides functions for mapping Symbian language codes 

    to corresponding ISO and RFC 3066 codes.

    \section _hbextendedlocale_localedependentelements Language- and country-dependent elements to be formatted

    \subsection _hbextendedlocale_calendarformatting Calendar

    The Western (Gregorian) calendar is perhaps the most common calendar system 

    in use, but there are also other calendars in use worldwide, such as the 

    Japanese, Buddhist era, Hijri, Hebrew lunar, and Taiwan calendars.

    The following calendars are supported:

    \li Gregorian calendar

    \li Chinese lunar calendar

    \li  Vietnamese lunar calendar

    \li  Thai Buddhist calendar

    The Symbian platform also provides an API for integrating an Arabic 

    calendar.

    When implementing calendar formatting, take into account the use of 

    different calendars and the differences they may have. For example, there 

    may be differences in the year values, the length of the year and months, 

    whether or not week numbers are used, and the way leap years are handled. 

    Even the same calendar may have locale-specific differences, for example, 

    the first day of the week in the Gregorian calendar (usually Sunday or 

    Monday). Handling week numbers locale-dependently is not supported.

    For calendar formatting, use HbExtendedLocale workDays(), setWorkDays(), 

    startOfWeek() and setStartOfWeek().

    \subsection _hbextendedlocale_datetimeformatting Date and time

    Date and time formatting often varies per locale. Examples of differences 

    are the order of the day, month, and year components in the date, the first 

    day of the week, whether a 12-hour or 24-hour clock is used, and the 

    separators used in the date and time formats.

    For example, January 30th in 2009 can be displayed in the following ways:

    - Danish: 30-01-09

    - Hungarian: 2009.01.30.

    - Swedish: 09/01/30

    - English (US): 1/30/09

    And examples of differences in time formatting:

    - USA: 9:35 pm

    - France: 21:35

    - Canada (French): 21 h 35

    - Finland: 21.35

    It is possible to also include seconds in the time format, but Symbian-based 

    applications usually only use hours and minutes.

    To format dates, use:

    \li HbExtendedLocale format(const QDate &, const QString &), dateStyle(), 

    setDateStyle(), dateSeparator(), setDateSeparator(), symbianDateTimeToQt()

    \li QLocale::dayName(), QLocale::monthName()

    To format times, use:

    \li HbExtendedLocale format(const QTime &, const QString &), timeStyle(), 

    setTimeStyle(), timeSeparator(), setTimeSeparator(), amPmSymbolPosition(), 

    setAmPmSymbolPosition(), amPmSpace(), setAmPmSpace(), 

    homeDaylightSavingZone(), homeHasDaylightSavingOn(), universalTimeOffset(), 

    symbianDateTimeToQt()

    \li QLocale::amText(), QLocale::pmText()

    \subsection _hbextendedlocale_numberformatting Numbers

    Possible differences in number formatting include the digit type used, and 

    the decimal separator.

    For example:

    - Finnish: 13,5

    - US English: 38.6

    - Japanese: 1,300.500

    To format numbers, use:

    \li HbExtendedLocale setDecimalPoint(), setGroupSeparator(), setZeroDigit()

    \li QLocale::decimalPoint(), QLocale::groupSeparator(), QLocale::zeroDigit()

    \li HbStringUtil::convertDigits(), HbStringUtil::convertDigitsTo()

    \li HbNumberGrouping::formatGeneric()

    \subsection _hbextendedlocale_currencyformatting Currencies

    Possible differences in the currency formats include the currency symbol and 

    its position, the number of characters used in the currency symbol, and the 

    formatting of negative currencies.

    For example:

    - France: 20,15 €

    - Denmark: kr-20,15 - negative currency is indicated by a minus sign

    - United States: ($20.15) - negative currency is indicated by brackets

    To format currencies, use:

    \li HbExtendedLocale formatCurrency(), currencySymbol(), 

    setCurrencySymbol(), currencySpace(), setCurrencySpace(), 

    currencySymbolPosition(), setCurrencySymbolPosition(), 

    currencyDecimalPlaces(), setCurrencyDecimalPlaces(), 

    currencyTriadsAllowed(), setCurrencyTriadsAllowed(), 

    negativeCurrencyFormat(), setNegativeCurrencyFormat(), 

    negativeCurrencySpace(), setNegativeCurrencySpace(), 

    negativeCurrencySymbolOpposite(), setNegativeCurrencySymbolOpposite()

    \li QLocale::decimalPoint(), QLocale::groupSeparator()

    \li HbNumberGrouping::formatCurrency()

    \subsection _hbextendedlocale_unitofmeasurementformatting Units of measurement

    Units of measurement must be formatted correctly using either metric or 

    imperial units.

    To format units of measurement, use:

    \li HbExtendedLocale unitsDistanceLong(), setUnitsDistanceLong(), 

    unitsDistanceShort(), setUnitsDistanceShort(), setUnitsGeneral()

    \li QLocale::measurementSystem(), QLocale::groupSeparator(), 

    QLocale::decimalPoint()

    \note To display locale-specific names of measurement units (for example, 

    kB), you need to localize this data in the <tt>.ts</tt> translations files, 

    and use the global hbTrId() function to display the correct translation. 

    Alternatively, you can enable users to set the unit. For user-changeable 

    settings, there must be a localizable default.

    \section _usecases_hbextendedlocale Using the HbExtendedLocale class

    \sa QLocale, HbStringUtil, HbNumberGrouping, HbLocaleUtil

    Returns the date separator from the system locale. The separator is one of 

    the four characters (space, '.', '-' or '/') used to separate the day, month 

    and year components in a date expression.

    If the current locale uses no separator in the specified position, an empty 

    character is returned.

    \param index The position of the separator in the date expression (0-3).

    - \c 0 - at the beginning of the expression

    - \c 1 - between the first and second component

    - \c 2 - between the second and third component

    - \c 3 - at the end of the expression

    \attention Only fully implemented on the Symbian platform. On other 

    platforms, returns '/' for index values 0-3, otherwise an empty QChar.

    \sa setDateSeparator()

    _symbianLocale.LoadSystemSettings();    

    Sets the date separator.

    \param ch The separator character to set.

    \param index The position of the separator in the date expression (0-3).

    \return \c true if successful, otherwise \c false.

    \attention Only fully implemented on the Symbian platform. On other 

    platforms, always returns \c false.

    \sa dateSeparator()

    _symbianLocale.LoadSystemSettings();    

    Returns the time separator from the system locale. The separator is one of 

    the four characters (':', '.', '-' and '/') used to separate the hour, 

    minute and second components in a time expression.

    \param index The position of the separator in the time expression (0-3).

    - \c 0 - at the beginning of the expression

    - \c 1 - between the first and second component

    - \c 2 - between the second and third component

    - \c 3 - at the end of the expression

    \attention Only fully implemented on the Symbian platform. On other 

    platforms,  returns ':' for index values 0-3, otherwise an empty QChar.

    \sa setTimeSeparator()

    Sets the time separator.

    \param ch The character to set.

    \param index The position of the separator in the time expression (0-3).

    \return \c true if successful, otherwise \c false.

    \attention Only fully implemented on the Symbian platform. On other 

    platforms, always returns \c false.

    \sa timeSeparator()

    Defines the order of the date components in a date.

    \sa dateStyle(), setDateStyle()

*/

/*! 

    \var HbExtendedLocale::American

    The format 'month-day-year' (mm/dd/yyyy), which is mostly used in the U.S. 

    and Canada.

*/

/*! 

    \var HbExtendedLocale::European

    The most commonly used format 'day-month-year' (dd/mm/yyyy).

*/

/*! 

    \var HbExtendedLocale::Japanese

    The format 'year-month-day' (yyyy/mm/dd), which is used, for example, in the 

    Japanese, Chinese and Swedish locales.

    Returns the date style from the system locale according to 

    HbExtendedLocale::DateStyle.

    \attention Only fully implemented on the Symbian platform. On other 

    platforms, always returns HbExtendedLocale::American.

    \sa setDateStyle()

    Sets the date style specified in \a style to the system locale.

    \return \c true if successful, otherwise \c false.

    \attention Only fully implemented on the Symbian platform. On other 

    platforms, always returns \c false.

    \sa dateStyle(), HbExtendedLocale::DateStyle