1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clean up the QCollator code and comments

Browse Source 
Broke over-long lines.  Reflowed documentation, refined a phrasing,
corrected some out of date details and typos.

Change-Id: Ic3835bb198bd062f85b3c466b56dc9636d4d3fe4
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
This commit is contained in:
Edward Welbourne 2018-12-11 17:41:24 +01:00
parent cdd3bd1d2c
commit 830e06a3f8
4 changed files with 69 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
src/corelib/tools/qcollator.cpp
View File

@ -59,20 +59,21 @@ QT_BEGIN_NAMESPACE
\ingroup string-processing \ingroup string-processing
\ingroup shared \ingroup shared
QCollator is initialized with a QLocale and an optional collation strategy. It tries to QCollator is initialized with a QLocale and an optional collation strategy.
initialize the collator with the specified values. The collator can then be used to compare It tries to initialize the collator with the specified values. The collator
and sort strings in a locale dependent fashion. can then be used to compare and sort strings in a locale dependent fashion.
A QCollator object can be used together with template based sorting algorithms such as std::sort A QCollator object can be used together with template based sorting
to sort a list of QStrings. algorithms such as std::sort to sort a list of QStrings.
In addition to the locale and collation strategy, several optional flags can be set that influence In addition to the locale and collation strategy, several optional flags can
the result of the collation. be set that influence the result of the collation.
*/ */
/*! /*!
Constructs a QCollator from \a locale. If \a locale is not specified Constructs a QCollator for \a locale.
the system's default locale is used.
If \a locale is not specified, the system's default locale is used.
\sa setLocale() \sa setLocale()
*/ */
@ -128,9 +129,9 @@ QCollator &QCollator::operator=(const QCollator &other)
Move constructor. Moves from \a other into this collator. Move constructor. Moves from \a other into this collator.
Note that a moved-from QCollator can only be destroyed or assigned Note that a moved-from QCollator can only be destroyed or assigned to.
to. The effect of calling other functions than the destructor or The effect of calling other functions than the destructor or one of the
one of the assignment operators is undefined. assignment operators is undefined.
*/ */
/*! /*!
@ -138,9 +139,9 @@ QCollator &QCollator::operator=(const QCollator &other)
Move-assigns from \a other to this collator. Move-assigns from \a other to this collator.
Note that a moved-from QCollator can only be destroyed or assigned Note that a moved-from QCollator can only be destroyed or assigned to.
to. The effect of calling other functions than the destructor or The effect of calling other functions than the destructor or one of the
one of the assignment operators is undefined. assignment operators is undefined.
*/ */
/*! /*!
@ -218,7 +219,8 @@ Qt::CaseSensitivity QCollator::caseSensitivity() const
Enables numeric sorting mode when \a on is set to true. Enables numeric sorting mode when \a on is set to true.
This will enable proper sorting of numeric digits, so that e.g. 100 sorts after 99. This will enable proper sorting of numeric digits, so that e.g. 100 sorts
after 99.
By default this mode is off. By default this mode is off.
@ -248,11 +250,13 @@ bool QCollator::numericMode() const
/*! /*!
\fn void QCollator::setIgnorePunctuation(bool on) \fn void QCollator::setIgnorePunctuation(bool on)
If \a on is set to true, punctuation characters and symbols are ignored when determining sort order. If \a on is set to true, punctuation characters and symbols are ignored when
determining sort order.
The default is locale dependent. The default is locale dependent.
\note This method is not currently supported if Qt is configured to not use ICU on Linux. \note This method is not currently supported if Qt is configured to not use
ICU on Linux.
\sa ignorePunctuation() \sa ignorePunctuation()
*/ */
@ -268,7 +272,8 @@ void QCollator::setIgnorePunctuation(bool on)
/*! /*!
\fn bool QCollator::ignorePunctuation() const \fn bool QCollator::ignorePunctuation() const
Returns \c true if punctuation characters and symbols are ignored when determining sort order. Returns \c true if punctuation characters and symbols are ignored when
determining sort order.
\sa setIgnorePunctuation() \sa setIgnorePunctuation()
*/ */
@ -287,9 +292,11 @@ bool QCollator::ignorePunctuation() const
\since 5.13 \since 5.13
\fn int QCollator::compare(QStringView s1, QStringView s2) const \fn int QCollator::compare(QStringView s1, QStringView s2) const
Compares \a s1 with \a s2. Returns an integer less than, equal to, or greater than zero Compares \a s1 with \a s2.
depending on whether \a s1 sorts before, with or after \a s2.
*/ Returns an integer less than, equal to, or greater than zero depending on
whether \a s1 sorts before, with or after \a s2.
*/
#if QT_STRINGVIEW_LEVEL < 2 #if QT_STRINGVIEW_LEVEL < 2
/*! /*!
\fn bool QCollator::operator()(const QString &s1, const QString &s2) const \fn bool QCollator::operator()(const QString &s1, const QString &s2) const
@ -299,9 +306,11 @@ bool QCollator::ignorePunctuation() const
/*! /*!
\overload \overload
Compares \a s1 with \a s2. Returns an integer less than, equal to, or greater than zero Compares \a s1 with \a s2.
depending on whether \a s1 sorts before, with or after \a s2.
*/ Returns an integer less than, equal to, or greater than zero depending on
whether \a s1 sorts before, with or after \a s2.
*/
int QCollator::compare(const QString &s1, const QString &s2) const int QCollator::compare(const QString &s1, const QString &s2) const
{ {
return compare(QStringView(s1), QStringView(s2)); return compare(QStringView(s1), QStringView(s2));
@ -310,8 +319,10 @@ int QCollator::compare(const QString &s1, const QString &s2) const
/*! /*!
\overload \overload
Compares \a s1 with \a s2. Returns an integer less than, equal to, or greater than zero Compares \a s1 with \a s2.
depending on whether \a s1 sorts before, with or after \a s2.
Returns an integer less than, equal to, or greater than zero depending on
whether \a s1 sorts before, with or after \a s2.
*/ */
int QCollator::compare(const QStringRef &s1, const QStringRef &s2) const int QCollator::compare(const QStringRef &s1, const QStringRef &s2) const
{ {
@ -321,11 +332,11 @@ int QCollator::compare(const QStringRef &s1, const QStringRef &s2) const
/*! /*!
\overload \overload
Compares \a s1 with \a s2. \a len1 and \a len2 specify the length of the Compares \a s1 with \a s2. \a len1 and \a len2 specify the lengths of the
QChar arrays pointer to by \a s1 and \a s2. QChar arrays pointed to by \a s1 and \a s2.
Returns an integer less than, equal to, or greater than zero Returns an integer less than, equal to, or greater than zero depending on
depending on whether \a s1 sorts before, with or after \a s2. whether \a s1 sorts before, with or after \a s2.
*/ */
int QCollator::compare(const QChar *s1, int len1, const QChar *s2, int len2) const int QCollator::compare(const QChar *s1, int len1, const QChar *s2, int len2) const
{ {
@ -339,9 +350,9 @@ int QCollator::compare(const QChar *s1, int len1, const QChar *s2, int len2) con
Returns a sortKey for \a string. Returns a sortKey for \a string.
Creating the sort key is usually somewhat slower, than using the compare() Creating the sort key is usually somewhat slower, than using the compare()
methods directly. But if the string is compared repeatedly (e.g. when sorting methods directly. But if the string is compared repeatedly (e.g. when
a whole list of strings), it's usually faster to create the sort keys for each sorting a whole list of strings), it's usually faster to create the sort
string and then sort using the keys. keys for each string and then sort using the keys.
\note Not supported with the C (a.k.a. POSIX) locale on Darwin. \note Not supported with the C (a.k.a. POSIX) locale on Darwin.
*/ */
@ -353,8 +364,8 @@ int QCollator::compare(const QChar *s1, int len1, const QChar *s2, int len2) con
\since 5.2 \since 5.2
The QCollatorSortKey class is always created by QCollator::sortKey() The QCollatorSortKey class is always created by QCollator::sortKey() and is
and is used for fast strings collation, for example when collating many strings. used for fast strings collation, for example when collating many strings.
\reentrant \reentrant
\ingroup i18n \ingroup i18n
@ -423,9 +434,11 @@ QCollatorSortKey& QCollatorSortKey::operator=(const QCollatorSortKey &other)
/*! /*!
\fn int QCollatorSortKey::compare(const QCollatorSortKey &otherKey) const \fn int QCollatorSortKey::compare(const QCollatorSortKey &otherKey) const
Compares the key to \a otherKey. Returns a negative value if the key Compares this key to \a otherKey.
is less than \a otherKey, 0 if the key is equal to \a otherKey or a
positive value if the key is greater than \a otherKey. Returns a negative value if the key is less than \a otherKey, 0 if the key
is equal to \a otherKey or a positive value if the key is greater than \a
otherKey.
\sa operator<() \sa operator<()
*/ */

6
src/corelib/tools/qcollator_icu.cpp
View File

@ -78,7 +78,8 @@ void QCollatorPrivate::init()
// and does case sensitive comparison. // and does case sensitive comparison.
// UCOL_QUATERNARY is used as default in a few languages such as Japanese to take care of some // UCOL_QUATERNARY is used as default in a few languages such as Japanese to take care of some
// additional differences in those languages. // additional differences in those languages.
UColAttributeValue val = (caseSensitivity == Qt::CaseSensitive) ? UCOL_DEFAULT_STRENGTH : UCOL_SECONDARY; UColAttributeValue val = (caseSensitivity == Qt::CaseSensitive)
? UCOL_DEFAULT_STRENGTH : UCOL_SECONDARY;
status = U_ZERO_ERROR; status = U_ZERO_ERROR;
ucol_setAttribute(collator, UCOL_STRENGTH, val, &status); ucol_setAttribute(collator, UCOL_STRENGTH, val, &status);
@ -91,7 +92,8 @@ void QCollatorPrivate::init()
qWarning("ucol_setAttribute: numeric collation failed: %d", status); qWarning("ucol_setAttribute: numeric collation failed: %d", status);
status = U_ZERO_ERROR; status = U_ZERO_ERROR;
ucol_setAttribute(collator, UCOL_ALTERNATE_HANDLING, ignorePunctuation ? UCOL_SHIFTED : UCOL_NON_IGNORABLE, &status); ucol_setAttribute(collator, UCOL_ALTERNATE_HANDLING,
ignorePunctuation ? UCOL_SHIFTED : UCOL_NON_IGNORABLE, &status);
if (U_FAILURE(status)) if (U_FAILURE(status))
qWarning("ucol_setAttribute: Alternate handling failed: %d", status); qWarning("ucol_setAttribute: Alternate handling failed: %d", status);

12
src/corelib/tools/qcollator_macx.cpp
View File

@ -71,7 +71,6 @@ void QCollatorPrivate::init()
qWarning("Couldn't initialize the locale (%d)", int(status)); qWarning("Couldn't initialize the locale (%d)", int(status));
UInt32 options = 0; UInt32 options = 0;
if (caseSensitivity == Qt::CaseInsensitive) if (caseSensitivity == Qt::CaseInsensitive)
options |= kUCCollateCaseInsensitiveMask; options |= kUCCollateCaseInsensitiveMask;
if (numericMode) if (numericMode)
@ -125,13 +124,14 @@ QCollatorSortKey QCollator::sortKey(const QString &string) const
//Documentation recommends having it 5 times as big as the input //Documentation recommends having it 5 times as big as the input
QVector<UCCollationValue> ret(string.size() * 5); QVector<UCCollationValue> ret(string.size() * 5);
ItemCount actualSize; ItemCount actualSize;
int status = UCGetCollationKey(d->collator, reinterpret_cast<const UniChar *>(string.constData()), string.count(), int status = UCGetCollationKey(d->collator,
ret.size(), &actualSize, ret.data()); reinterpret_cast<const UniChar *>(string.constData()),
string.count(), ret.size(), &actualSize, ret.data());
ret.resize(actualSize+1); ret.resize(actualSize + 1);
if (status == kUCOutputBufferTooSmall) { if (status == kUCOutputBufferTooSmall) {
UCGetCollationKey(d->collator, reinterpret_cast<const UniChar *>(string.constData()), string.count(), UCGetCollationKey(d->collator, reinterpret_cast<const UniChar *>(string.constData()),
ret.size(), &actualSize, ret.data()); string.count(), ret.size(), &actualSize, ret.data());
} }
ret[actualSize] = 0; ret[actualSize] = 0;
return QCollatorSortKey(new QCollatorSortKeyPrivate(std::move(ret))); return QCollatorSortKey(new QCollatorSortKeyPrivate(std::move(ret)));

11
src/corelib/tools/qcollator_win.cpp
View File

@ -94,9 +94,10 @@ int QCollator::compare(QStringView s1, QStringView s2) const
d->init(); d->init();
//* from Windows documentation * //* from Windows documentation *
// Returns one of the following values if successful. To maintain the C runtime convention of // Returns one of the following values if successful. To maintain the C
// comparing strings, the value 2 can be subtracted from a nonzero return value. Then, the // runtime convention of comparing strings, the value 2 can be subtracted
// meaning of <0, ==0, and >0 is consistent with the C runtime. // from a nonzero return value. Then, the meaning of <0, ==0, and >0 is
// consistent with the C runtime.
#ifndef USE_COMPARESTRINGEX #ifndef USE_COMPARESTRINGEX
return CompareString(d->localeID, d->collator, return CompareString(d->localeID, d->collator,
@ -137,7 +138,9 @@ QCollatorSortKey QCollator::sortKey(const QString &string) const
NULL, NULL, 0); NULL, NULL, 0);
#endif #endif
if (finalSize == 0) { if (finalSize == 0) {
qWarning() << "there were problems when generating the ::sortKey by LCMapStringW with error:" << GetLastError(); qWarning()
<< "there were problems when generating the ::sortKey by LCMapStringW with error:"
<< GetLastError();
} }
return QCollatorSortKey(new QCollatorSortKeyPrivate(std::move(ret))); return QCollatorSortKey(new QCollatorSortKeyPrivate(std::move(ret)));
} }