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

#include <qcollator.h>

Public Member Functions
	QCollator ()

	QCollator (const QLocale &locale)

	QCollator (const QCollator &)

	~QCollator ()

QCollator &	operator= (const QCollator &)

	QCollator (QCollator &&other) noexcept

void	swap (QCollator &other) noexcept

void	setLocale (const QLocale &locale)

QLocale	locale () const

Qt::CaseSensitivity	caseSensitivity () const

void	setCaseSensitivity (Qt::CaseSensitivity cs)

void	setNumericMode (bool on)

bool	numericMode () const

void	setIgnorePunctuation (bool on)

bool	ignorePunctuation () const

int	compare (const QString &s1, const QString &s2) const

int	compare (const QChar s1, int len1, const QChar s2, int len2) const

bool	operator() (const QString &s1, const QString &s2) const

int	compare (QStringView s1, QStringView s2) const

bool	operator() (QStringView s1, QStringView s2) const

QCollatorSortKey	sortKey (const QString &string) const

Static Public Member Functions
static int	defaultCompare (QStringView s1, QStringView s2)

static QCollatorSortKey	defaultSortKey (QStringView key)

Detailed Description

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

\inmodule QtCore

Since: 5.2

\reentrant

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.

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.

Definition at line 77 of file qcollator.h.

Constructor & Destructor Documentation

◆ QCollator() [1/4]

QCollator::QCollator ( )

Since: 5.13

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(), QLocale::setDefault()

Definition at line 112 of file qcollator.cpp.

◆ QCollator() [2/4]

QCollator::QCollator ( const QLocale & locale )

explicit

Constructs a QCollator using the given locale.

See also: setLocale()

Definition at line 123 of file qcollator.cpp.

◆ QCollator() [3/4]

QCollator::QCollator ( const QCollator & other )

Creates a copy of other.

Definition at line 131 of file qcollator.cpp.

Here is the call graph for this function:

◆ ~QCollator()

QCollator::~QCollator ( )

Destroys this collator.

Definition at line 145 of file qcollator.cpp.

Here is the call graph for this function:

◆ QCollator() [4/4]

QCollator::QCollator ( QCollator && other )

inlinenoexcept

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.

Definition at line 85 of file qcollator.h.

Here is the call graph for this function:

Member Function Documentation

◆ caseSensitivity()

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()

Definition at line 265 of file qcollator.cpp.

◆ compare() [1/3]

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

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Since: 5.2

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.

Definition at line 107 of file qcollator.h.

Here is the call graph for this function:

◆ compare() [2/3]

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

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Since: 5.2

Definition at line 105 of file qcollator.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ compare() [3/3]

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

Since: 5.13

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.

Definition at line 110 of file qcollator_icu.cpp.

Here is the call graph for this function:

◆ defaultCompare()

int QCollator::defaultCompare	(	QStringView	s1,
		QStringView	s2
	)

static

Since: 6.3

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

See also: compare(), defaultSortKey()

Definition at line 380 of file qcollator.cpp.

◆ defaultSortKey()

QCollatorSortKey QCollator::defaultSortKey ( QStringView key )

static

Since: 6.3

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

See also: sortKey(), defaultCompare()

Definition at line 393 of file qcollator.cpp.

◆ ignorePunctuation()

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()

Definition at line 321 of file qcollator.cpp.

◆ locale()

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(), QLocale::collation()

Definition at line 234 of file qcollator.cpp.

Here is the caller graph for this function:

◆ numericMode()

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()

Definition at line 294 of file qcollator.cpp.

◆ operator()() [1/2]

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

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Since: 5.2

Definition at line 110 of file qcollator.h.

Here is the call graph for this function:

◆ operator()() [2/2]

bool QCollator::operator()	(	QStringView	s1,
		QStringView	s2
	)		const

inline

Since: 5.13

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()

Definition at line 115 of file qcollator.h.

Here is the call graph for this function:

◆ operator=()

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

Assigns other to this collator.

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.

Definition at line 154 of file qcollator.cpp.

Here is the call graph for this function:

◆ setCaseSensitivity()

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

Sets the case-sensitivity of the collator to cs.

See also: caseSensitivity()

Definition at line 244 of file qcollator.cpp.

Here is the caller graph for this function:

◆ setIgnorePunctuation()

void QCollator::setIgnorePunctuation ( bool on )

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

See also: ignorePunctuation()

Definition at line 304 of file qcollator.cpp.

◆ setLocale()

void QCollator::setLocale ( const QLocale & locale )

Sets the locale of the collator to locale.

See also: locale()

Definition at line 217 of file qcollator.cpp.

Here is the call graph for this function:

◆ setNumericMode()

void QCollator::setNumericMode ( bool on )

Enables numeric sorting mode when on is true.

See also: numericMode()

Definition at line 275 of file qcollator.cpp.

Here is the caller graph for this function:

◆ sortKey()

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.

Definition at line 129 of file qcollator_icu.cpp.

Here is the call graph for this function:

◆ swap()

void QCollator::swap ( QCollator & other )

inlinenoexcept

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

Definition at line 89 of file qcollator.h.

Here is the call graph for this function:

The documentation for this class was generated from the following files:

src/corelib/text/qcollator.h
src/corelib/text/qcollator.cpp
src/corelib/text/qcollator_icu.cpp
src/corelib/text/qcollator_macx.cpp
src/corelib/text/qcollator_posix.cpp
src/corelib/text/qcollator_win.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ QCollator() [1/4]

◆ QCollator() [2/4]

◆ QCollator() [3/4]

◆ ~QCollator()

◆ QCollator() [4/4]

Member Function Documentation

◆ caseSensitivity()

◆ compare() [1/3]

◆ compare() [2/3]

◆ compare() [3/3]

◆ defaultCompare()

◆ defaultSortKey()

◆ ignorePunctuation()

◆ locale()

◆ numericMode()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ operator=()

◆ setCaseSensitivity()

◆ setIgnorePunctuation()

◆ setLocale()

◆ setNumericMode()

◆ sortKey()

◆ swap()