\inmodule QtCore More...

#include <qcollator.h>

Collaboration diagram for QCollator:

Public Types
enum class	CollationOption { CaseInsensitive = 0x1 , IgnorePunctuation = 0x2 , NumericSort = 0x4 , DiacriticInsensitive = 0x8 }

Public Member Functions
	QCollator ()
	QCollator (const QLocale &locale)
	Constructs a QCollator using the given locale.
	QCollator (const QCollator &)
	Creates a copy of other.
	~QCollator ()
	Destroys this collator.
QCollator &	operator= (const QCollator &)
	Assigns other to this collator.
	QCollator (QCollator &&other) noexcept
void	swap (QCollator &other) noexcept
	\memberswap{collator}
void	setLocale (const QLocale &locale)
	Sets the locale of the collator to locale.
QLocale	locale () const
	Returns the locale of the collator.
Qt::CaseSensitivity	caseSensitivity () const
	Returns case sensitivity of the collator.
void	setCaseSensitivity (Qt::CaseSensitivity cs)
	Sets the case-sensitivity of the collator to cs.
void	setNumericMode (bool on)
	Enables numeric sorting mode when on is `true`.
bool	numericMode () const
	Returns `true` if numeric sorting is enabled, `false` otherwise.
void	setIgnorePunctuation (bool on)
	Ignores punctuation and symbols if on is `true`, attends to them if `false`.
bool	ignorePunctuation () const
	Returns whether punctuation and symbols are ignored when collating.
void	setOptions (CollationOptions options)
CollationOptions	options () const
int	compare (const QString &s1, const QString &s2) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
int	compare (const QChar s1, qsizetype len1, const QChar s2, qsizetype len2) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
bool	operator() (const QString &s1, const QString &s2) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
int	compare (QStringView s1, QStringView s2) const
bool	operator() (QStringView s1, QStringView s2) const
QCollatorSortKey	sortKey (const QString &string) const
	Returns a sortKey for string.

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

Friends
Q_CORE_EXPORT bool	comparesEqual (const QCollator &lhs, const QCollator &rhs)

Detailed Description

\inmodule QtCore

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

Since: 5.2

\reentrant

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.

Definition at line 48 of file qcollator.h.

Member Enumeration Documentation

◆ CollationOption

enum class QCollator::CollationOption

strong

Since: 6.13

Options that control how strings are compared by \l QCollator.

The \macos, Windows, and ICU backends support all options, with variations where indicated. On non-\macos Unix (including Linux), if ICU is not available a fallback (POSIX) backend is used, which supports none of these options.

\value CaseInsensitive Ignore case differences when comparing strings.

\value IgnorePunctuation Ignore punctuation and symbols when comparing strings.

\value NumericSort Sort strings containing numbers by their numeric value, so that for example "file10" sorts after "file9" instead of between "file1" and "file2".

\value DiacriticInsensitive Ignore diacritical marks when comparing strings, so that for example "e" and "é" compare as equal. Depending on the locale, this may also include ligature folding such as æ == ae. See \l {DiacriticInsensitive behavior details} below.

Enumerator
CaseInsensitive
IgnorePunctuation
NumericSort
DiacriticInsensitive

Definition at line 51 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 155 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 165 of file qcollator.cpp.

◆ QCollator() [3/4]

QCollator::QCollator ( const QCollator & other )

Creates a copy of other.

Definition at line 173 of file qcollator.cpp.

◆ ~QCollator()

QCollator::~QCollator ( )

Destroys this collator.

Definition at line 186 of file qcollator.cpp.

◆ QCollator() [4/4]

QCollator::QCollator ( QCollator && other )

inlinenoexcept

Definition at line 64 of file qcollator.h.

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 326 of file qcollator.cpp.

◆ compare() [1/3]

int QCollator::compare	(	const QChar *	s1,
		qsizetype	len1,
		const QChar *	s2,
		qsizetype	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 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}.

Definition at line 92 of file qcollator.h.

◆ 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 86 of file qcollator.h.

◆ compare() [3/3]

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

Since: 5.13

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.

Definition at line 95 of file qcollator_icu.cpp.

◆ 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 474 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 487 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 383 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 295 of file qcollator.cpp.

◆ 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 356 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 95 of file qcollator.h.

◆ 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 99 of file qcollator.h.

◆ operator=()

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

Assigns other to this collator.

Move-assigns other to this QCollator instance.

\fn QCollator::QCollator(QCollator &&other)

Move constructor. Moves from \a other into this collator.

! [partially-formed]

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. ! [partially-formed]

partially-formed

Definition at line 195 of file qcollator.cpp.

◆ options()

QCollator::CollationOptions QCollator::options ( ) const

Since: 6.13 Returns the collation options currently set on the collator.

See also: setOptions(), CollationOption

Definition at line 412 of file qcollator.cpp.

Referenced by testing.tools.test_runner._TestCaseRunner::_NewImageArtifact(), testing.tools.test_runner._TestCaseRunner::_RegenerateIfNeeded(), testing.tools.test_runner.TestRunner::IsSkiaGoldEnabled(), testing.tools.test_runner._TestCaseRunner::TestPixel(), and testing.tools.test_runner._TestCaseRunner::TestText().

Here is the caller 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 305 of file qcollator.cpp.

◆ 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 366 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 278 of file qcollator.cpp.

◆ setNumericMode()

void QCollator::setNumericMode ( bool on )

Enables numeric sorting mode when on is true.

See also: numericMode()

Definition at line 337 of file qcollator.cpp.

◆ setOptions()

void QCollator::setOptions ( CollationOptions options )

Since: 6.13 Sets the collation options to options. This allows configuring multiple collation settings at once.

Note: In the C locale, the collation options have no effect. Use a specific locale to enable locale-aware collation.

See also: options(), CollationOption

Definition at line 398 of file qcollator.cpp.

◆ 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 117 of file qcollator_icu.cpp.

◆ swap()

void QCollator::swap ( QCollator & other )

inlinenoexcept

\memberswap{collator}

Definition at line 68 of file qcollator.h.

◆ comparesEqual

Q_CORE_EXPORT bool comparesEqual	(	const QCollator &	lhs,
		const QCollator &	rhs )

friend

Definition at line 244 of file qcollator.cpp.

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

qtbase/src/corelib/text/qcollator.h (b054014d58114ec2a7e51444785406e10528ba5b)
qtbase/src/corelib/text/qcollator.cpp (b054014d58114ec2a7e51444785406e10528ba5b)
qtbase/src/corelib/text/qcollator_icu.cpp (b054014d58114ec2a7e51444785406e10528ba5b)
qtbase/src/corelib/text/qcollator_macx.cpp (b054014d58114ec2a7e51444785406e10528ba5b)
qtbase/src/corelib/text/qcollator_posix.cpp (b054014d58114ec2a7e51444785406e10528ba5b)
qtbase/src/corelib/text/qcollator_win.cpp (b054014d58114ec2a7e51444785406e10528ba5b)

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ CollationOption

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

◆ options()

◆ setCaseSensitivity()

◆ setIgnorePunctuation()

◆ setLocale()

◆ setNumericMode()

◆ setOptions()

◆ sortKey()

◆ swap()

Friends And Related Symbol Documentation

◆ comparesEqual