QCollator Class

The QCollator class compares strings according to a localized collation algorithm. More...

Header: #include <QCollator>
CMake: find_package(Qt6 COMPONENTS Core REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Since: Qt 5.2

Note: All functions in this class are reentrant.

Public Functions

QCollator(QCollator &&other)
QCollator(const QCollator &other)
QCollator(const QLocale &locale)
QCollator()
QCollator &operator=(QCollator &&other)
QCollator &operator=(const QCollator &other)
~QCollator()
Qt::CaseSensitivity caseSensitivity() const
int compare(QStringView s1, QStringView s2) const
int compare(const QString &s1, const QString &s2) const
int compare(const QChar *s1, int len1, const QChar *s2, int len2) const
bool ignorePunctuation() const
QLocale locale() const
bool numericMode() const
void setCaseSensitivity(Qt::CaseSensitivity cs)
void setIgnorePunctuation(bool on)
void setLocale(const QLocale &locale)
void setNumericMode(bool on)
QCollatorSortKey sortKey(const QString &string) const
void swap(QCollator &other)
bool operator()(QStringView s1, QStringView s2) const
bool operator()(const QString &s1, const QString &s2) const

Detailed Description

QCollator is initialized with a QLocale. It can then be used to compare and sort strings in using the ordering appropriate to the locale.

A QCollator object can be used together with template-based sorting algorithms, such as std::sort(), to sort a list with QString entries.

QStringList sortedStrings(QStringList seq)
{
    QCollator order;
    std::sort(seq.begin(), seq.end(), order);
    return seq;
}

In addition to the locale, several optional flags can be set that influence the result of the collation.

Note: On Linux, Qt is normally compiled to use ICU. When it isn't, all options are ignored and the only supported locales are the system default (that setlocale(LC_COLLATE, nullptr) would report) and the "C" locale.

Member Function Documentation

QCollator::QCollator(QCollator &&other)

Move constructor. Moves from 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.

QCollator::QCollator(const QCollator &other)

Creates a copy of other.

QCollator::QCollator(const QLocale &locale)

Constructs a QCollator using the given locale.

See also setLocale().

[since 5.13] QCollator::QCollator()

Constructs a QCollator using the system's default collation locale.

This function was introduced in Qt 5.13.

See also setLocale() and QLocale::collation().

QCollator &QCollator::operator=(QCollator &&other)

Move-assigns from 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.

QCollator &QCollator::operator=(const QCollator &other)

Assigns other to this collator.

QCollator::~QCollator()

Destroys this collator.

Qt::CaseSensitivity QCollator::caseSensitivity() const

Returns case sensitivity of the collator.

This defaults to case-sensitive until set.

Note: In the C locale, when case-sensitive, all lower-case letters sort after all upper-case letters, where most locales sort each lower-case letter either immediately before or immediately after its upper-case partner. Thus "Zap" sorts before "ape" in the C locale but after in most others.

See also setCaseSensitivity().

[since 5.13] int QCollator::compare(QStringView s1, QStringView s2) const

Compares s1 with s2.

Returns an integer less than, equal to, or greater than zero depending on whether s1 sorts before, with or after s2.

This function was introduced in Qt 5.13.

[since 5.2] int QCollator::compare(const QString &s1, const QString &s2) const

This is an overloaded function.

This function was introduced in Qt 5.2.

[since 5.2] int QCollator::compare(const QChar *s1, int len1, const QChar *s2, int len2) const

This is an overloaded function.

Compares s1 with s2. len1 and len2 specify the lengths of the QChar arrays pointed to by s1 and s2.

Returns an integer less than, equal to, or greater than zero depending on whether s1 sorts before, with or after s2.

This function was introduced in Qt 5.2.

bool QCollator::ignorePunctuation() const

Returns whether punctuation and symbols are ignored when collating.

When true, strings are compared as if all punctuation and symbols were removed from each string.

See also setIgnorePunctuation().

QLocale QCollator::locale() const

Returns the locale of the collator.

Unless supplied to the constructor or by calling setLocale(), the system's default collation locale is used.

See also setLocale() and QLocale::collation().

bool QCollator::numericMode() const

Returns true if numeric sorting is enabled, false otherwise.

When true, numerals are recognized as numbers and sorted in arithmetic order; for example, 100 sortes after 99. When false, numbers are sorted in lexical order, so that 100 sorts before 99 (because 1 is before 9). By default, this option is disabled.

See also setNumericMode().

void QCollator::setCaseSensitivity(Qt::CaseSensitivity cs)

Sets the case-sensitivity of the collator to cs.

See also caseSensitivity().

void QCollator::setIgnorePunctuation(bool on)

Ignores punctuation and symbols if on is true, attends to them if false.

See also ignorePunctuation().

void QCollator::setLocale(const QLocale &locale)

Sets the locale of the collator to locale.

See also locale().

void QCollator::setNumericMode(bool on)

Enables numeric sorting mode when on is true.

See also numericMode().

QCollatorSortKey QCollator::sortKey(const QString &string) const

Returns a sortKey for 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.

Note: Not supported with the C (a.k.a. POSIX) locale on Darwin.

void QCollator::swap(QCollator &other)

Swaps this collator with other. This function is very fast and never fails.

[since 5.13] bool QCollator::operator()(QStringView s1, QStringView s2) const

A QCollator can be used as the comparison function of a sorting algorithm. It returns true if s1 sorts before s2, otherwise false.

This function was introduced in Qt 5.13.

See also compare().

[since 5.2] bool QCollator::operator()(const QString &s1, const QString &s2) const

This is an overloaded function.

This function was introduced in Qt 5.2.

© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.