class QCollator#

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

Synopsis#

Methods#

Static functions#

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description#

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

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.

def sortedStrings(seq):

    order = QCollator()
    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 c() and 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.

__init__(arg__1)#
Parameters:

arg__1 – QCollator

Creates a copy of other.

__init__(locale)
Parameters:

locale – QLocale

Constructs a QCollator using the given locale.

See also

setLocale()

__init__()

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.

caseSensitivity()#
Return type:

CaseSensitivity

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

compare(s1, s2)#
Parameters:

  • s1 – str

  • s2 – str

Return type:

int

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.

compare(s1, len1, s2, len2)
Parameters:

  • s1 – QChar

  • len1 – int

  • s2 – QChar

  • len2 – int

Return type:

int

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

compare(s1, s2)
Parameters:

  • s1 – str

  • s2 – str

Return type:

int

This is an overloaded function.

static defaultCompare(s1, s2)#
Parameters:

  • s1 – str

  • s2 – str

Return type:

int

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

static defaultSortKey(key)#
Parameters:

key – str

Return type:

QCollatorSortKey

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

ignorePunctuation()#
Return type:

bool

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.

locale()#
Return type:

QLocale

Returns the locale of the collator.

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

numericMode()#
Return type:

bool

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

__call__(s1, s2)#
Parameters:

  • s1 – str

  • s2 – str

Return type:

bool

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

__call__(s1, s2)
Parameters:

  • s1 – str

  • s2 – str

Return type:

bool

This is an overloaded function.

setCaseSensitivity(cs)#
Parameters:

cs – CaseSensitivity

Sets the case-sensitivity of the collator to cs.

setIgnorePunctuation(on)#
Parameters:

on – bool

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

setLocale(locale)#
Parameters:

locale – QLocale

Sets the locale of the collator to locale.

See also

locale()

setNumericMode(on)#
Parameters:

on – bool

Enables numeric sorting mode when on is true.

See also

numericMode()

sortKey(string)#
Parameters:

string – str

Return type:

QCollatorSortKey

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.

swap(other)#
Parameters:

other – QCollator

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