\brief The HbStringUtil class supports locale-based comparing and ordering of strings, and digit conversion.

    \section _hbstringutil_stringcomparison Comparing and ordering strings

    Using HbStringUtil, you can execute locale-aware operations on collated 

    strings, such as comparisons and finding data sequences in target strings. 

    HbStringUtil also provides similar functions for operations on folded data.

    Choose the right HbStringUtil functions for your purpose, depending on 

    whether you want to operate on collated or folded data:

    <ul>

    <li>Because different languages have different alphabets, they also require 

    different ways of ordering strings. The technical term for ordering and 

    comparing strings in a locale-specific manner is \b collating. When 

    comparing strings in natural languages, it is recommended that you use the 

    HbStringUtil collation functions: matchC(), compareC() and findC(), and 

    sort() for operations on multiple strings.

    For example, for languages using the Latin script, collation defines when 

    punctuation should be ignored, how accents are handled, and so on. A 

    locale's settings usually include rules for collation.

    As an example of handling accents, in German, the letter "o with umlaut" or 

    "ö" is just a variation of "o", whereas in Swedish it is the letter "ö", 

    which comes last in the alphabet. There can also be country-specific 

    variations within a language, for example, between Iberian Spanish and Latin 

    American Spanish.</li>

    <li>\b Folding normalises text for comparison, for example, by removing case 

    distinctions and accents from characters. This can be useful, for example, 

    if you need to determine if two file names are identical.

    Folding is not locale-aware. For example, folding is not able to handle 

    character relationships that are not one-to-one, for example, mapping from 

    the German uppercase SS to the lowercase ß. When you need to compare 

    strings in natural languages, use collation instead.</li>

    </ul>

    \section _hbstringutil_digitconversion Digit conversion

    Internal processing of numeric expressions uses Latin digits. To display 

    digits correctly to the user, you need to convert them to the appropriate 

    digit type.

    If you are inserting numbers into a localizable string at runtime using 

    arguments, you can localize the digit type used for the numbers using the \c 

    L notation in the placeholder in the string (see hbTrId()). However, this 

    only works for integers. When displaying more complex numeric expressions 

    such as dates and times, use HbStringUtil to convert the digits to the digit 

    type appropriate to the UI language.

    \note In internal processing, converting numbers from one digit type to 

    another is not always allowed. For example, native digits are filtered out 

    of IP addresses, and native digits in phone numbers are converted and sent 

    to the network as Latin digits. This is because different networks may not 

    be able to handle native digits.

    HbExtendedLocale, QLocale and HbNumberGrouping also provide functions for 

    locale-dependent number formatting.

    \sa HbLocaleUtil

    Defines the collation levels ('flags') for matchC() and compareC(). This is 

    based on the Symbian TCollationMethod enumeration, and it is not used on 

    other platforms.

    \var HbStringUtil::Default

    Use the default system flags.

*/

/*!     

    \var HbStringUtil::IgnoreNone

    Do not ignore any keys (by default, for example, punctuation marks and 

    spaces are ignored).

*/

/*!    

    \var HbStringUtil::SwapCase

    Reverse the normal order for characters that only differ in case.

*/

/*!    

    \var HbStringUtil::AccentsBackwards

    Compare secondary keys representing accents in reverse order (from right to 

    left). This is needed for French when comparing words that only differ in 

    accents.

*/

/*!    

    \var HbStringUtil::SwapKana

    Reverse the normal order for characters that only differ in whether they are 

    Katakana or Hiragana.

*/

/*!    

    \var HbStringUtil::FoldCase

    Fold all characters to lowercase before extracting keys. This is needed when 

    comparing file names; case is ignored but other Unicode collation level 2 

    distinctions are not.

*/

/*!    

    \var HbStringUtil::MatchingTable

    Specify a specific collation method to be used for matching purposes.

*/

/*!    

    \var HbStringUtil::IgnoreCombining

    Ignore a check for adjacent combining characters. A combining character 

    effectively changes the character it combines with into another character, 

    which means a match does not occur. Setting this flag allows character 

    matching regardless of any combining characters.

*/

/*!

    Searches \a strFrom for a match of \a strToMatch based on the locale's 

    collation settings. You can optionally specify the level of collation with 

    \a maxLevel and \a flags, and the wild card and escape characters for the 

    search with \a wildChar, \a wildSequenceChar and \a escapeChar. If the 

    parameters are not specified, the default values are used.

    \param strFrom The source string.    

    \param strToMatch The string whose data is to be searched within the source 

    string. The value can contain the wildcard characters "*" and "?", where "*" 

    matches zero or more consecutive occurrences of any character, and "?" 

    matches a single occurrence of any character (default).

    \param maxLevel (optional) The level of collation. Possible values:

    - \c 0: Only character identities are distinguished.

    - \c 1: Character identities and accents are distinguished.

    - \c 2: Character identities, accents, and case are distinguished.    

    - \c 3: All valid Unicode characters are considered different.

    - For details, see Symbian documentation on collation, for example, as used 

    by TDesC16::MatchC().

    \param flags A list of (comma-separated) HbStringUtil::Option flags that 

    will be used. The default value is \c Default.

    \param wildChar (optional) Wild card character ('?' by default).

    \param wildSequenceChar (optional) Wild card sequence character ('*' by default).

    \param escapeChar (optional) The escape character, for example, '?', '*' or '\\\\' (default).

    \return The offset from the beginning of \a strFrom where the match first 

    occurs. If the data sequence in \a strToMatch is not found, returns -1.

    \attention On the Symbian platform, this class uses a Symbian-specific 

    collation match. On other platforms, the search is not locale-based, and 

    only the \a strFrom and \a strToMatch parameters are used.

    \sa findC()

    if ( (maxLevel < 0) || (maxLevel > 3) ) {

        maxLevel = 0;

    }

    // works with standard wildcards

    Compares \a string1 with \a string2 based on the locale's collation 

    settings. You can optionally specify the level of collation with \a maxLevel 

    and \a flags. If the parameters are not specified, the default values are 

    used.

    \param string1 The source string.

    \param string2 The string whose data is to be compared with the source string.

    \param maxLevel (optional) The level of collation. Possible values:

    - \c 0: Only character identities are distinguished.

    - \c 1: Character identities and accents are distinguished.

    - \c 2: Character identities, accents, and case are distinguished.    

    - \c 3: All valid Unicode characters are considered different (default).

    - For details, see Symbian documentation on collation, for example, as used 

    by TDesC16::CompareC().

    \param flags (optional) A list of (comma-separated) HbStringUtil::Option flags that 

    will be used. The default value is \c Default.

    \return Positive if the \a string1 is greater (that is, comes after \a 

    string2 when the strings are ordered), negative if \a string2 is greater, 

    and zero if the content of the strings matches.

    \attention Locale-specific collation settings are used, and the return value 

    may vary on different platforms. The \a maxLevel and \a flags parameters are 

    not used.

    \sa compareF()

    if ( (maxLevel < 0) || (maxLevel > 3) ) {

        maxLevel = 3;

    }

    Searches \a strFrom for the first occurrence of \a strToFind based on the 

    locale's collation settings. You can optionally specify the collation level 

    with \a maxLevel. If the parameter is not specified, the default value is 

    used.

    \param strFrom The source string.

    \param strToFind The string whose data is to be searched within the source string.

    \param maxLevel (optional) The level of collation. Possible values:

    - \c 0: Only character identities are distinguished (default).

    - \c 1: Character identities and accents are distinguished.

    - \c 2: Character identities, accents, and case are distinguished.    

    - \c 3: All valid Unicode characters are considered different.

    - For details, see Symbian documentation on collation, for example, as used 

    by TDesC16::FindC().

    \return The offset from the beginning of \a strFrom where the match first 

    occurs. If the data sequence in \a strToFind cannot be found, returns -1. If 

    the length of \a strToFind is zero, returns zero.

    \attention On the Symbian platform, this class uses a Symbian-specific 

    collation search. On other platforms, the search is not locale-based, and 

    the \a maxLevel parameter is not used.

    \sa matchC()

    if ( (maxLevel < 0) || (maxLevel > 3) ) {

        maxLevel = 0;

    }

    Searches the folded data in \a strFrom for a match with the folded data in 

    \a strToMatch.

    \param strFrom The source string.    

    \param strToMatch The string whose data is to be searched within the source 

    string. The value can contain the wildcard characters "*" and "?", where "*" 

    matches zero or more consecutive occurrences of any character, and "?" 

    matches a single occurrence of any character.

    \return The offset from the beginning of \a strFrom where the match first 

    occurs. If the data sequence in \a strToMatch is not found, returns -1.

    \attention On the Symbian platform, this class uses a Symbian-specific 

    folding match. On other platforms, the search is not locale-based.

    \sa findF()

    Searches the folded data in \a strFrom for the first occurrence of the 

    folded data in \a strToFind.

    \param strFrom The source string.

    \param strToFind The string whose data is to be searched within the source string.

    \return The offset from the beginning of \a strFrom where the match first 

    occurs. If the data sequence in \a strToFind cannot be found, returns -1. If 

    the length of \a strToFind is zero, returns zero.

    \attention On the Symbian platform, this class uses a Symbian-specific 

    folding search. On other platforms, the search is not locale-based, and the 

    \a maxLevel parameter is not used.

    \sa matchF()

    Compares the folded data in \a string1 with the folded data in \a string2.

    \param string1 The source string.

    \param string2 The string whose data is to be compared with the source string.

    \return Positive if \a string1 is greater (that is, comes after \a string2 

    when the strings are ordered), negative if \a string2 is greater, and zero 

    if the content of the strings matches.

    \attention On the Symbian platform, this class uses Symbian-specific folding 

    comparison. On other platforms, the comparison is not locale-based.

    \sa compareC()

    Returns the starting digit range of the native digit.

    \param ch The native digit.

    Converts digits to the native digits based on the current UI language.

    \param str The digits to be converted.