- Qt 6.9
- Qt Core
- C++ Classes
- QCollator
- Qt 6.9.3 Reference Documentation

# QCollator Class

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

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

- List of all members, including inherited members
- QCollator is part of Classes for string data and Implicitly Shared Classes.

Note: All functions in this class are reentrant.

## Public Functions

| QCollator()
| QCollator(const QLocale &locale)
| QCollator(const QCollator &other)
| QCollator(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, qsizetype len1, const QChar *s2, qsizetype 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
QCollator & | operator=(QCollator &&other)
QCollator & | operator=(const QCollator &other)

## Static Public Members

`(since 6.3)` int | defaultCompare(QStringView s1, QStringView s2)
`(since 6.3)` QCollatorSortKey | defaultSortKey(QStringView key)

## Detailed Description

QCollator is initialized with a QLocale. It can then be used to compare and sort strings by using the ordering appropriate for that 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.

### POSIX fallback implementation

On Unix systems, Qt is normally compiled to use ICU (except for macOS, where Qt defaults to using an equivalent Apple API). However, if ICU was not available at compile time or explicitly disabled, Qt will use a fallback backend that uses the POSIX API only. This backend has several limitations:

- Only the QLocale::c() and QLocale::system() locales are supported. Consult the POSIX and C Standard Library manuals for the `<locale.h>` header for more information on the system locale.
- caseSensitivity() is not supported: only case-sensitive collation can be performed.
- numericMode() and ignorePunctuation() are not supported.

The use of any of the unsupported options will cause a warning to be printed to the application's output.

## Member Function Documentation

### QCollator::QCollator()

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

The system locale, when used as default locale, may have a collation locale other than itself (e.g. on Unix, if LC_COLLATE is set differently to LANG in the environment). All other locales are their own collation locales.

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

### `[explicit]` QCollator::QCollator(const QLocale &locale)

Constructs a QCollator using the given locale.

See also setLocale().

### QCollator::QCollator(const QCollator &other)

Creates a copy of other.

### `[noexcept]` QCollator::QCollator(QCollator &&other)

Move constructor. Moves from other into this collator.

Note: The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.

### `[noexcept]` 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().

### int QCollator::compare(QStringView s1, QStringView s2) const

Compares s1 with s2.

Returns a negative integer if s1 is less than s2, a positive integer if it is greater than s2, and zero if they are equal.

### int QCollator::compare(const QString &s1, const QString &s2) const

This is an overloaded function.

### int QCollator::compare(const QChar *s1, qsizetype len1, const QChar *s2, qsizetype len2) const

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

Returns a negative integer if s1 is less than s2, a positive integer if it is greater than s2, and zero if they are equal.

Note: In Qt versions prior to 6.4, the length arguments were of type `int`, not `qsizetype`.

This is an overloaded function.

### `[static, since 6.3]` int QCollator::defaultCompare(QStringView s1, QStringView s2)

Compares the strings s1 and s2, returning their sorting order. This function performs the same operation as compare() on a default-constructed QCollator object.

This function was introduced in Qt 6.3.

See also compare() and defaultSortKey().

### `[static, since 6.3]` QCollatorSortKey QCollator::defaultSortKey(QStringView key)

Returns the sort key for the string key. This function performs the same operation as sortKey() on a default-constructed QCollator object.

This function was introduced in Qt 6.3.

See also sortKey() and defaultCompare().

### 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.

### `[noexcept]` void QCollator::swap(QCollator &other)

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

### 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`.

See also compare().

### bool QCollator::operator()(const QString &s1, const QString &s2) const

This is an overloaded function.

### `[noexcept]` QCollator &QCollator::operator=(QCollator &&other)

Move-assigns other to this QCollator instance.

Note: The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.

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

Assigns other to this collator.