diff -r 7516d6d86cf5 -r ed14f46c0e55 src/hbcore/i18n/hbstringutil.cpp --- a/src/hbcore/i18n/hbstringutil.cpp Mon Oct 04 17:49:30 2010 +0300 +++ b/src/hbcore/i18n/hbstringutil.cpp Mon Oct 18 18:23:13 2010 +0300 @@ -45,61 +45,185 @@ @stable @hbcore \class HbStringUtil - \brief The HbStringUtil class can be used to execute operations on strings, - such as comparisons and finding data sequences. + \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: + + + + \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. - \sa HbStringUtil + \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 */ /*! \enum HbStringUtil::Option - This enum describes the way collation is done for matchC, compareC - Pass one of these values to setReadChannel() to set the - current read channel of QProcess. - - \value Default Use the default System flags. - - \value IgnoreNone Don't ignore anything. - - \value SwapCase Reverse case ordering. + 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. - \value AccentsBackwards Compare secondary keys which represent accents in reverse order. - - \value SwapKana Reverse order for katakana/hiragana. - - \value FoldCase Fold to lower case, file comparisons. - - \value MatchingTable Table used for matching. - - \value IgnoreCombining Ignore check for adjacent combining characters. - - \sa compareC, matchC */ /*! - Searches source string's collated data for a - match with collated data supplied in pattern string - - \attention Cross-Platform API + \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 - \param strFrom Source string. - \param strToMatch Pattern string. - \param maxLevel Determines the tightness of the collation. - Level 0 - Character identity; - Level 1 - Character identity and accents; - Level 2 - Character identity, accents and case; - Level 3 - Character identity, accents, case and Unicode value; - \param flags The flags that will be used. Default value is Default. - \param wildChar Wild card character. - \param wildSequenceChar Wild card sequence character. - \param escapeChar The escape character, for example, '?', '*'. + 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 - \return If a match is found the offset within source string's - data where the match first occurs. -1 if match is not found. + 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. Example: \snippet{unittest_hbstringutil/unittest_hbstringutil.cpp,3} + + \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() */ int HbStringUtil::matchC( const QString &strFrom, const QString &strToMatch, int maxLevel, Options flags, @@ -109,9 +233,9 @@ TPtrC s1Ptr( strFrom.utf16() ); TPtrC s2Ptr( strToMatch.utf16() ); - if ( (maxLevel < 0) || (maxLevel > 3) ) { - maxLevel = 0; - } + if ( (maxLevel < 0) || (maxLevel > 3) ) { + maxLevel = 0; + } if ( (flags < 0) || (flags > 127) ) { flags = Default; } @@ -130,7 +254,7 @@ // if no regular expressions defined do standard MatchF return strFrom.indexOf( strToMatch, 0, Qt::CaseSensitive ); #else - // works with standard wildcards is not correct + // works with standard wildcards QRegExp locStrToMatch( strToMatch, Qt::CaseSensitive, QRegExp::Wildcard ); return strFrom.indexOf( locStrToMatch, 0 ); #endif @@ -139,25 +263,36 @@ } /*! - Compares source string's data with the other string's - data using the specified collation method. - - \attention Cross-Platform API + + 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 Source string. - \param string2 String whose data is to be compared with the source string. - \param maxLevel Maximum level to use for comparing. - Level 0 - Character identity; - Level 1 - Character identity and accents; - Level 2 - Character identity, accents and case; - Level 3 - Character identity, accents, case and Unicode value; - \param flags The flags that will be used. Default value is Default. - - \return Positive if source string is greater, negative if it is less and - zero if the content of both strings match. + \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. Example: \snippet{unittest_hbstringutil/unittest_hbstringutil.cpp,1} + + \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() */ int HbStringUtil::compareC( const QString &string1, const QString &string2, int maxLevel, Options flags ) @@ -166,9 +301,9 @@ TPtrC s1Ptr(string1.utf16()); TPtrC s2Ptr(string2.utf16()); - if ( (maxLevel < 0) || (maxLevel > 3) ) { - maxLevel = 3; - } + if ( (maxLevel < 0) || (maxLevel > 3) ) { + maxLevel = 3; + } if ( (flags < 0) || (flags > 127) ) { flags = Default; } @@ -185,25 +320,34 @@ } /*! - Searches for the first occurrence of the specified collated - data sequence in the aStrFrom to the specified maximum - collation level. - - \attention Cross-Platform API + + 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 Source string. - \param strToFind String whose data is to be compared with the source string. - \param maxLevel The maximum collation level. - Level 0 - Character identity; - Level 1 - Character identity and accents; - Level 2 - Character identity, accents and case; - Level 3 - Character identity, accents, case and Unicode value; + \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 Offset of the data sequence from the beginning of the - aStrFrom. -1 if the data sequence cannot be found. + \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. Example: \snippet{unittest_hbstringutil/unittest_hbstringutil.cpp,5} + + \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() */ int HbStringUtil::findC( const QString &strFrom, const QString &strToFind, @@ -213,9 +357,9 @@ TPtrC s1Ptr( strFrom.utf16() ); TPtrC s2Ptr( strToFind.utf16() ); - if ( (maxLevel < 0) || (maxLevel > 3) ) { - maxLevel = 0; - } + if ( (maxLevel < 0) || (maxLevel > 3) ) { + maxLevel = 0; + } return s1Ptr.FindC( s2Ptr.Ptr(), s2Ptr.Length(), maxLevel ); @@ -226,19 +370,26 @@ } /*! - Searches source string's folded data for a - match with folded data supplied in pattern string - - \attention Cross-Platform API + + Searches the folded data in \a strFrom for a match with the folded data in + \a strToMatch. - \param strFrom Source string. - \param strToMatch Pattern string. + \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 If a match is found the offset within source string's - data where the match first occurs. -1 if match is not found. + \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. Example: \snippet{unittest_hbstringutil/unittest_hbstringutil.cpp,4} + + \attention On the Symbian platform, this class uses a Symbian-specific + folding match. On other platforms, the search is not locale-based. + + \sa findF() */ int HbStringUtil::matchF( const QString &strFrom, const QString &strToMatch ) @@ -261,20 +412,25 @@ } /*! - Searches for the first occurrence of the specified folded - data sequence in the strFrom. - - \attention Cross-Platform API + + Searches the folded data in \a strFrom for the first occurrence of the + folded data in \a strToFind. - \param strFrom Source string. - \param strToFind String whose data is to be compared with the source string. + \param strFrom The source string. + \param strToFind The string whose data is to be searched within the source string. - \return Offset of the data sequence from the beginning of the - strFrom. -1 if the data sequence cannot be found. Zero, - if the length of search data sequence is zero. + \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. Example: \snippet{unittest_hbstringutil/unittest_hbstringutil.cpp,6} + + \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() */ int HbStringUtil::findF( const QString &strFrom, const QString &strToFind ) @@ -290,19 +446,23 @@ } /*! - Compares source string's folded data with the other string's - folded data. - - \attention Cross-Platform API + + Compares the folded data in \a string1 with the folded data in \a string2. - \param string1 Source string. - \param string2 String whose data is to be compared with the source string. + \param string1 The source string. + \param string2 The string whose data is to be compared with the source string. - \return Positive if source string is greater, negative if it is less and - zero if the content of both strings match. + \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. Example: \snippet{unittest_hbstringutil/unittest_hbstringutil.cpp,2} + + \attention On the Symbian platform, this class uses Symbian-specific folding + comparison. On other platforms, the comparison is not locale-based. + + \sa compareC() */ int HbStringUtil::compareF( const QString &string1, const QString &string2 ) @@ -318,9 +478,11 @@ } /*! - Returns the starting digit range of the native digit - \param ch native digit - \return starting digit range + + Returns the starting digit range of the native digit. + + \param ch The native digit. + */ static QChar nativeDigitBase(QChar ch) { @@ -335,32 +497,65 @@ } /*! - Converts digits to native digits based on current UI language. + + Converts digits to the native digits based on the current UI language. + + \param str The digits to be converted. + + For example: - \attention Cross-Platform API + \code + QString date = "07.09.2010"; + QString result = HbStringUtil::convertDigits(date); + \endcode - \param str digits to be converted. + \sa convertDigitsTo(), QLocale::toString() */ QString HbStringUtil::convertDigits( const QString str ) { - HbExtendedLocale locale = HbExtendedLocale::system(); - DigitType digitType = WesternDigit; - if (locale.language() == HbExtendedLocale::Arabic) { - digitType = ArabicIndicDigit; - } else if (locale.language() == HbExtendedLocale::Persian || locale.language() == HbExtendedLocale::Urdu) { - digitType = EasternArabicIndicDigit; - } - QString converted = HbStringUtil::convertDigitsTo(str, digitType); - return converted; + DigitType digitType = WesternDigit; +#if defined( Q_OS_SYMBIAN ) + TExtendedLocale extLocale; + extLocale.LoadSystemSettings(); + TDigitType type = extLocale.GetLocale()->DigitType(); + switch (type) + { + case EDigitTypeArabicIndic: + digitType = ArabicIndicDigit; + break; + case EDigitTypeEasternArabicIndic: + digitType = EasternArabicIndicDigit; + break; + default: + break; + }; +#else + HbExtendedLocale locale = HbExtendedLocale::system(); + QChar zero = locale.zeroDigit(); + if (zero == 0x660) { + digitType = ArabicIndicDigit; + } + if (zero == 0x6F0) { + digitType = EasternArabicIndicDigit; + } +#endif + QString converted = HbStringUtil::convertDigitsTo(str, digitType); + return converted; } /*! - Converts the digit from Latin to native or native to latin or native to native + + Returns digits converted into the specified digit type. If you need to + process an integer, use QLocale::toString() to first convert it to a string. - \attention Cross-Platform API + \param str The digits to be converted. + \param digitType The digit type that the given digits are to be converted to. Possible values: + - \c WesternDigit - Latin digits + - \c ArabicIndicDigit - Arabic-Indic digits + - \c EasternArabicIndicDigit - Eastern Arabic-Indic digits + - \c DevanagariDigit - Devanagari digits - \param str digits to be converted. - \param digitType type of the digit to be converted to + \sa convertDigits(), QLocale::toString() */ QString HbStringUtil::convertDigitsTo( const QString str, const DigitType digitType ) { @@ -382,7 +577,7 @@ convDigit[i] = QChar(convertedDigit); break; default: - convDigit[i] = QChar(digit); + convDigit[i] = QChar(digit); break; }; } @@ -390,29 +585,33 @@ } /*! - Sorts QStrings into alphabetically order (overwrites the strList's original content) - \attention Cross-Platform API + Sorts QString objects into alphabetical order based on the locale's + collation settings. This overwrites the original content of \a strList. - \param strList List of QStrings which need to be sorted. + \param strList The list of QStrings that need to be sorted. Example: \snippet{unittest_hbstringutil/unittest_hbstringutil.cpp,7} + + \attention Locale-specific collation settings are used, and the return value + may vary on different platforms. + */ void HbStringUtil::sort( QStringList &strList ) { - if ( strList.size() > 1 ) { - qSort(strList.begin(), strList.end(), hbStringUtil_SortHelper); - } + if ( strList.size() > 1 ) { + qSort(strList.begin(), strList.end(), hbStringUtil_SortHelper); + } } bool hbStringUtil_SortHelper( const QString &s1, const QString &s2 ) { - if ( HbStringUtil::compareC(s1, s2) < 0 ) { - // s1 is before s2 - return true; - } else { - // s1 is after s2 (or they are equal) - return false; - } + if ( HbStringUtil::compareC(s1, s2) < 0 ) { + // s1 is before s2 + return true; + } else { + // s1 is after s2 (or they are equal) + return false; + } }