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 shared
QCollator is initialized with a QLocale and an optional collation strategy. It tries to
initialize the collator with the specified values. The collator can then be used to compare
and sort strings in a locale dependent fashion.
QCollator is initialized with a QLocale and an optional collation strategy.
It tries to initialize the collator with the specified values. The collator
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
to sort a list of QStrings.
A QCollator object can be used together with template based sorting
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
the result of the collation.
In addition to the locale and collation strategy, several optional flags can
be set that influence the result of the collation.
*/
/*!
Constructs a QCollator from \a locale. If \a locale is not specified
the system's default locale is used.
Constructs a QCollator for \a locale.
If \a locale is not specified, the system's default locale is used.
\sa setLocale()
*/
@ -128,9 +129,9 @@ QCollator &QCollator::operator=(const QCollator &other)
Move constructor. Moves from \a other into this collator.
Note that a moved-from QCollator can only be destroyed or assigned
to. The effect of calling other functions than the destructor or
one of the assignment operators is undefined.
Note that a moved-from QCollator can only be destroyed or assigned to.
The effect of calling other functions than the destructor or one of the
assignment operators is undefined.
*/
/*!
@ -138,9 +139,9 @@ QCollator &QCollator::operator=(const QCollator &other)
Move-assigns from \a other to this collator.
Note that a moved-from QCollator can only be destroyed or assigned
to. The effect of calling other functions than the destructor or
one of the assignment operators is undefined.
Note that a moved-from QCollator can only be destroyed or assigned to.
The effect of calling other functions than the destructor or one of the
assignment operators is undefined.
*/
/*!
@ -218,7 +219,8 @@ Qt::CaseSensitivity QCollator::caseSensitivity() const
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.
@ -248,11 +250,13 @@ bool QCollator::numericMode() const
/*!
\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.
\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()
*/
@ -268,7 +272,8 @@ void QCollator::setIgnorePunctuation(bool on)
/*!
\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()
*/
@ -287,9 +292,11 @@ bool QCollator::ignorePunctuation() const
\since 5.13
\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
depending on whether \a s1 sorts before, with or after \a s2.
*/
Compares \a s1 with \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
/*!
\fn bool QCollator::operator()(const QString &s1, const QString &s2) const
@ -299,9 +306,11 @@ bool QCollator::ignorePunctuation() const
/*!
\overload
Compares \a s1 with \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.
*/
Compares \a s1 with \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
{
return compare(QStringView(s1), QStringView(s2));
@ -310,8 +319,10 @@ int QCollator::compare(const QString &s1, const QString &s2) const
/*!
\overload
Compares \a s1 with \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.
Compares \a s1 with \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
{
@ -321,11 +332,11 @@ int QCollator::compare(const QStringRef &s1, const QStringRef &s2) const
/*!
\overload
Compares \a s1 with \a s2. \a len1 and \a len2 specify the length of the
QChar arrays pointer to by \a s1 and \a s2.
Compares \a s1 with \a s2. \a len1 and \a len2 specify the lengths of the
QChar arrays pointed to by \a s1 and \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.
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 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.
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
a whole list of strings), it's usually faster to create the sort keys for each
string and then sort using the keys.
methods directly. But if the string is compared repeatedly (e.g. when
sorting a whole list of strings), it's usually faster to create the sort
keys for each string and then sort using the keys.
\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
The QCollatorSortKey class is always created by QCollator::sortKey()
and is used for fast strings collation, for example when collating many strings.
The QCollatorSortKey class is always created by QCollator::sortKey() and is
used for fast strings collation, for example when collating many strings.
\reentrant
\ingroup i18n
@ -423,9 +434,11 @@ QCollatorSortKey& QCollatorSortKey::operator=(const QCollatorSortKey &other)
/*!
\fn int QCollatorSortKey::compare(const QCollatorSortKey &otherKey) const
Compares the key to \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.
Compares this key to \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<()
*/

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

@ -78,7 +78,8 @@ void QCollatorPrivate::init()
// and does case sensitive comparison.
// UCOL_QUATERNARY is used as default in a few languages such as Japanese to take care of some
// 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;
ucol_setAttribute(collator, UCOL_STRENGTH, val, &status);
@ -91,7 +92,8 @@ void QCollatorPrivate::init()
qWarning("ucol_setAttribute: numeric collation failed: %d", status);
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))
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));
UInt32 options = 0;
if (caseSensitivity == Qt::CaseInsensitive)
options |= kUCCollateCaseInsensitiveMask;
if (numericMode)
@ -125,13 +124,14 @@ QCollatorSortKey QCollator::sortKey(const QString &string) const
//Documentation recommends having it 5 times as big as the input
QVector<UCCollationValue> ret(string.size() * 5);
ItemCount actualSize;
int status = UCGetCollationKey(d->collator, reinterpret_cast<const UniChar *>(string.constData()), string.count(),
ret.size(), &actualSize, ret.data());
int status = UCGetCollationKey(d->collator,
reinterpret_cast<const UniChar *>(string.constData()),
string.count(), ret.size(), &actualSize, ret.data());
ret.resize(actualSize+1);
ret.resize(actualSize + 1);
if (status == kUCOutputBufferTooSmall) {
UCGetCollationKey(d->collator, reinterpret_cast<const UniChar *>(string.constData()), string.count(),
ret.size(), &actualSize, ret.data());
UCGetCollationKey(d->collator, reinterpret_cast<const UniChar *>(string.constData()),
string.count(), ret.size(), &actualSize, ret.data());
}
ret[actualSize] = 0;
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();
//* from Windows documentation *
// Returns one of the following values if successful. To maintain the C runtime convention of
// comparing strings, the value 2 can be subtracted from a nonzero return value. Then, the
// meaning of <0, ==0, and >0 is consistent with the C runtime.
// Returns one of the following values if successful. To maintain the C
// runtime convention of comparing strings, the value 2 can be subtracted
// from a nonzero return value. Then, the meaning of <0, ==0, and >0 is
// consistent with the C runtime.
#ifndef USE_COMPARESTRINGEX
return CompareString(d->localeID, d->collator,
@ -137,7 +138,9 @@ QCollatorSortKey QCollator::sortKey(const QString &string) const
NULL, NULL, 0);
#endif
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)));
}