QChar Class

Member Function Documentation

QChar::QChar(uchar ch)

Constructs a QChar corresponding to ASCII/Latin-1 character ch.

See also QT_NO_CAST_FROM_ASCII and QT_RESTRICTED_CAST_FROM_ASCII.

QChar::QChar(char ch)

Constructs a QChar corresponding to ASCII/Latin-1 character ch.

See also QT_NO_CAST_FROM_ASCII.

[since 5.10] QChar::QChar(wchar_t ch)

Constructs a QChar corresponding to the wide character ch.

This function was introduced in Qt 5.10.

[since 5.10] QChar::QChar(char16_t ch)

Constructs a QChar corresponding to the UTF-16 character ch.

This function was introduced in Qt 5.10.

QChar::QChar(QLatin1Char ch)

Constructs a QChar corresponding to ASCII/Latin-1 character ch.

QChar::QChar(QChar::SpecialCharacter ch)

Constructs a QChar for the predefined character value ch.

QChar::QChar(int code)

Constructs a QChar for the character with Unicode code point code.

QChar::QChar(uint code)

Constructs a QChar for the character with Unicode code point code.

QChar::QChar(short code)

Constructs a QChar for the character with Unicode code point code.

QChar::QChar(uchar cell, uchar row)

Constructs a QChar for Unicode cell cell in row row.

See also cell() and row().

QChar::QChar(ushort code)

Constructs a QChar for the character with Unicode code point code.

QChar::QChar()

Constructs a null QChar ('\0').

See also isNull().

QChar::Category QChar::category() const

Returns the character's category.

[static] QChar::Category QChar::category(char32_t ucs4)

This is an overloaded function.

Returns the category of the UCS-4-encoded character specified by ucs4.

uchar QChar::cell() const

Returns the cell (least significant byte) of the Unicode character.

See also row().

unsigned char QChar::combiningClass() const

Returns the combining class for the character as defined in the Unicode standard. This is mainly useful as a positioning hint for marks attached to a base character.

The Qt text rendering engine uses this information to correctly position non-spacing marks around a base character.

[static] unsigned char QChar::combiningClass(char32_t ucs4)

This is an overloaded function.

Returns the combining class for the UCS-4-encoded character specified by ucs4, as defined in the Unicode standard.

[static] QChar::UnicodeVersion QChar::currentUnicodeVersion()

Returns the most recent supported Unicode version.

QString QChar::decomposition() const

Decomposes a character into it's constituent parts. Returns an empty string if no decomposition exists.

[static] QString QChar::decomposition(char32_t ucs4)

This is an overloaded function.

Decomposes the UCS-4-encoded character specified by ucs4 into it's constituent parts. Returns an empty string if no decomposition exists.

QChar::Decomposition QChar::decompositionTag() const

Returns the tag defining the composition of the character. Returns QChar::NoDecomposition if no decomposition exists.

[static] QChar::Decomposition QChar::decompositionTag(char32_t ucs4)

This is an overloaded function.

Returns the tag defining the composition of the UCS-4-encoded character specified by ucs4. Returns QChar::NoDecomposition if no decomposition exists.

int QChar::digitValue() const

Returns the numeric value of the digit, or -1 if the character is not a digit.

[static] int QChar::digitValue(char32_t ucs4)

This is an overloaded function.

Returns the numeric value of the digit specified by the UCS-4-encoded character, ucs4, or -1 if the character is not a digit.

QChar::Direction QChar::direction() const

Returns the character's direction.

[static] QChar::Direction QChar::direction(char32_t ucs4)

This is an overloaded function.

Returns the direction of the UCS-4-encoded character specified by ucs4.

[static] QChar QChar::fromLatin1(char c)

Converts the Latin-1 character c to its equivalent QChar. This is mainly useful for non-internationalized software.

An alternative is to use QLatin1Char.

See also toLatin1() and unicode().

[static, since 6.0] QChar QChar::fromUcs2(char16_t c)

Constructs a QChar from UTF-16 character c.

This function was introduced in Qt 6.0.

See also fromUcs4().

[static, since 6.0] R QChar::fromUcs4(char32_t c)

Returns an anonymous struct that

• contains a char16_t chars[2] array,
• can be implicitly converted to a QStringView, and
• iterated over with a C++11 ranged for loop.

If c requires surrogates, chars[0] contains the high surrogate and chars[1] the low surrogate, and the QStringView has size 2. Otherwise, chars[0] contains c and chars[1] is null, and the QStringView has size 1.

This allows easy use of the result:

QString s;
s += QChar::fromUcs4(ch);

for (char16_t c16 : QChar::fromUcs4(ch))
    use(c16);

This function was introduced in Qt 6.0.

See also fromUcs2() and requiresSurrogates().

bool QChar::hasMirrored() const

Returns true if the character should be reversed if the text direction is reversed; otherwise returns false.

A bit faster equivalent of (ch.mirroredChar() != ch).

See also mirroredChar().

[static, since 5.0] bool QChar::hasMirrored(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 should be reversed if the text direction is reversed; otherwise returns false.

A bit faster equivalent of (QChar::mirroredChar(ucs4) != ucs4).

This function was introduced in Qt 5.0.

See also mirroredChar().

[static] char16_t QChar::highSurrogate(char32_t ucs4)

Returns the high surrogate part of a UCS-4-encoded code point. The returned result is undefined if ucs4 is smaller than 0x10000.

bool QChar::isDigit() const

Returns true if the character is a decimal digit (Number_DecimalDigit); otherwise returns false.

See also isNumber().

[static, since 5.0] bool QChar::isDigit(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a decimal digit (Number_DecimalDigit); otherwise returns false.

This function was introduced in Qt 5.0.

See also isNumber().

bool QChar::isHighSurrogate() const

Returns true if the QChar is the high part of a UTF16 surrogate (for example if its code point is in range [0xd800..0xdbff]); false otherwise.

[static] bool QChar::isHighSurrogate(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is the high part of a UTF16 surrogate (for example if its code point is in range [0xd800..0xdbff]); false otherwise.

bool QChar::isLetter() const

Returns true if the character is a letter (Letter_* categories); otherwise returns false.

[static, since 5.0] bool QChar::isLetter(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a letter (Letter_* categories); otherwise returns false.

This function was introduced in Qt 5.0.

bool QChar::isLetterOrNumber() const

Returns true if the character is a letter or number (Letter_* or Number_* categories); otherwise returns false.

[static, since 5.0] bool QChar::isLetterOrNumber(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a letter or number (Letter_* or Number_* categories); otherwise returns false.

This function was introduced in Qt 5.0.

bool QChar::isLowSurrogate() const

Returns true if the QChar is the low part of a UTF16 surrogate (for example if its code point is in range [0xdc00..0xdfff]); false otherwise.

[static] bool QChar::isLowSurrogate(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is the low part of a UTF16 surrogate (for example if its code point is in range [0xdc00..0xdfff]); false otherwise.

bool QChar::isLower() const

Returns true if the character is a lowercase letter, for example category() is Letter_Lowercase.

See also isUpper(), toLower(), and toUpper().

[static, since 5.0] bool QChar::isLower(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a lowercase letter, for example category() is Letter_Lowercase.

This function was introduced in Qt 5.0.

See also isUpper(), toLower(), and toUpper().

bool QChar::isMark() const

Returns true if the character is a mark (Mark_* categories); otherwise returns false.

See QChar::Category for more information regarding marks.

[static, since 5.0] bool QChar::isMark(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a mark (Mark_* categories); otherwise returns false.

This function was introduced in Qt 5.0.

[since 5.0] bool QChar::isNonCharacter() const

Returns true if the QChar is a non-character; false otherwise.

Unicode has a certain number of code points that are classified as "non-characters:" that is, they can be used for internal purposes in applications but cannot be used for text interchange. Those are the last two entries each Unicode Plane ([0xfffe..0xffff], [0x1fffe..0x1ffff], etc.) as well as the entries in range [0xfdd0..0xfdef].

This function was introduced in Qt 5.0.

[static, since 5.0] bool QChar::isNonCharacter(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a non-character; false otherwise.

Unicode has a certain number of code points that are classified as "non-characters:" that is, they can be used for internal purposes in applications but cannot be used for text interchange. Those are the last two entries each Unicode Plane ([0xfffe..0xffff], [0x1fffe..0x1ffff], etc.) as well as the entries in range [0xfdd0..0xfdef].

This function was introduced in Qt 5.0.

bool QChar::isNull() const

Returns true if the character is the Unicode character 0x0000 ('\0'); otherwise returns false.

bool QChar::isNumber() const

Returns true if the character is a number (Number_* categories, not just 0-9); otherwise returns false.

See also isDigit().

[static, since 5.0] bool QChar::isNumber(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a number (Number_* categories, not just 0-9); otherwise returns false.

This function was introduced in Qt 5.0.

See also isDigit().

bool QChar::isPrint() const

Returns true if the character is a printable character; otherwise returns false. This is any character not of category Other_*.

Note that this gives no indication of whether the character is available in a particular font.

[static, since 5.0] bool QChar::isPrint(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a printable character; otherwise returns false. This is any character not of category Other_*.

Note that this gives no indication of whether the character is available in a particular font.

This function was introduced in Qt 5.0.

bool QChar::isPunct() const

Returns true if the character is a punctuation mark (Punctuation_* categories); otherwise returns false.

[static, since 5.0] bool QChar::isPunct(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a punctuation mark (Punctuation_* categories); otherwise returns false.

This function was introduced in Qt 5.0.

bool QChar::isSpace() const

Returns true if the character is a separator character (Separator_* categories or certain code points from Other_Control category); otherwise returns false.

[static, since 5.0] bool QChar::isSpace(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a separator character (Separator_* categories or certain code points from Other_Control category); otherwise returns false.

This function was introduced in Qt 5.0.

[since 5.0] bool QChar::isSurrogate() const

Returns true if the QChar contains a code point that is in either the high or the low part of the UTF-16 surrogate range (for example if its code point is in range [0xd800..0xdfff]); false otherwise.

This function was introduced in Qt 5.0.

[static, since 5.0] bool QChar::isSurrogate(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 contains a code point that is in either the high or the low part of the UTF-16 surrogate range (for example if its code point is in range [0xd800..0xdfff]); false otherwise.

This function was introduced in Qt 5.0.

bool QChar::isSymbol() const

Returns true if the character is a symbol (Symbol_* categories); otherwise returns false.

[static, since 5.0] bool QChar::isSymbol(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a symbol (Symbol_* categories); otherwise returns false.

This function was introduced in Qt 5.0.

bool QChar::isTitleCase() const

Returns true if the character is a titlecase letter, for example category() is Letter_Titlecase.

See also isLower(), toUpper(), toLower(), and toTitleCase().

[static, since 5.0] bool QChar::isTitleCase(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is a titlecase letter, for example category() is Letter_Titlecase.

This function was introduced in Qt 5.0.

See also isLower(), toUpper(), toLower(), and toTitleCase().

bool QChar::isUpper() const

Returns true if the character is an uppercase letter, for example category() is Letter_Uppercase.

See also isLower(), toUpper(), and toLower().

[static, since 5.0] bool QChar::isUpper(char32_t ucs4)

This is an overloaded function.

Returns true if the UCS-4-encoded character specified by ucs4 is an uppercase letter, for example category() is Letter_Uppercase.

This function was introduced in Qt 5.0.

See also isLower(), toUpper(), and toLower().

[since 5.3] QChar::JoiningType QChar::joiningType() const

Returns information about the joining type attributes of the character (needed for certain languages such as Arabic or Syriac).

This function was introduced in Qt 5.3.

[static, since 5.3] QChar::JoiningType QChar::joiningType(char32_t ucs4)

This is an overloaded function.

Returns information about the joining type attributes of the UCS-4-encoded character specified by ucs4 (needed for certain languages such as Arabic or Syriac).

This function was introduced in Qt 5.3.

[static] char16_t QChar::lowSurrogate(char32_t ucs4)

Returns the low surrogate part of a UCS-4-encoded code point. The returned result is undefined if ucs4 is smaller than 0x10000.

QChar QChar::mirroredChar() const

Returns the mirrored character if this character is a mirrored character; otherwise returns the character itself.

See also hasMirrored().

[static] char32_t QChar::mirroredChar(char32_t ucs4)

This is an overloaded function.

Returns the mirrored character if the UCS-4-encoded character specified by ucs4 is a mirrored character; otherwise returns the character itself.

See also hasMirrored().

[static] bool QChar::requiresSurrogates(char32_t ucs4)

Returns true if the UCS-4-encoded character specified by ucs4 can be split into the high and low parts of a UTF16 surrogate (for example if its code point is greater than or equals to 0x10000); false otherwise.

uchar QChar::row() const

Returns the row (most significant byte) of the Unicode character.

See also cell().

[since 5.1] QChar::Script QChar::script() const

Returns the Unicode script property value for this character.

This function was introduced in Qt 5.1.

[static, since 5.1] QChar::Script QChar::script(char32_t ucs4)

This is an overloaded function.

Returns the Unicode script property value for the character specified in its UCS-4-encoded form as ucs4.

This function was introduced in Qt 5.1.

[static] char32_t QChar::surrogateToUcs4(char16_t high, char16_t low)

Converts a UTF16 surrogate pair with the given high and low values to it's UCS-4-encoded code point.

[static] char32_t QChar::surrogateToUcs4(QChar high, QChar low)

This is an overloaded function.

Converts a UTF16 surrogate pair (high, low) to it's UCS-4-encoded code point.

QChar QChar::toCaseFolded() const

Returns the case folded equivalent of the character. For most Unicode characters this is the same as toLower().

[static] char32_t QChar::toCaseFolded(char32_t ucs4)

This is an overloaded function.

Returns the case folded equivalent of the UCS-4-encoded character specified by ucs4. For most Unicode characters this is the same as toLower().

char QChar::toLatin1() const

Returns the Latin-1 character equivalent to the QChar, or 0. This is mainly useful for non-internationalized software.

See also unicode().

QChar QChar::toLower() const

Returns the lowercase equivalent if the character is uppercase or titlecase; otherwise returns the character itself.

[static] char32_t QChar::toLower(char32_t ucs4)

This is an overloaded function.

Returns the lowercase equivalent of the UCS-4-encoded character specified by ucs4 if the character is uppercase or titlecase; otherwise returns the character itself.

QChar QChar::toTitleCase() const

Returns the title case equivalent if the character is lowercase or uppercase; otherwise returns the character itself.

[static] char32_t QChar::toTitleCase(char32_t ucs4)

This is an overloaded function.

Returns the title case equivalent of the UCS-4-encoded character specified by ucs4 if the character is lowercase or uppercase; otherwise returns the character itself.

QChar QChar::toUpper() const

Returns the uppercase equivalent if the character is lowercase or titlecase; otherwise returns the character itself.

[static] char32_t QChar::toUpper(char32_t ucs4)

This is an overloaded function.

Returns the uppercase equivalent of the UCS-4-encoded character specified by ucs4 if the character is lowercase or titlecase; otherwise returns the character itself.

char16_t QChar::unicode() const

Returns the numeric Unicode value of the QChar.

char16_t &QChar::unicode()

Returns a reference to the numeric Unicode value of the QChar.

QChar::UnicodeVersion QChar::unicodeVersion() const

Returns the Unicode version that introduced this character.

[static] QChar::UnicodeVersion QChar::unicodeVersion(char32_t ucs4)

This is an overloaded function.

Returns the Unicode version that introduced the character specified in its UCS-4-encoded form as ucs4.

QString str = getString();
if (str == 123) {
    // Oops, meant str == "123". By default does not compile,
    // *unless* this macro is defined, in which case, it's interpreted
    // as `if (str == QChar(123))`, that is, `if (str == '{')`.
    // Likely, not what we meant.
}

QChar c1 =  'x'; // OK, unless QT_NO_CAST_FROM_ASCII is defined
QChar c2 = u'x'; // always OK, recommended
QChar c3 = QLatin1Char('x'); // always OK, recommended

// from int to 1 UTF-16 code unit: must guarantee that the input is <= 0xFFFF
QChar c4 = 120;        // compile error, unless QT_IMPLICIT_QCHAR_CONSTRUCTION is defined
QChar c5(120);         // OK (direct initialization)
auto  c6 = QChar(120); // ditto

// from int/char32_t to 1/2 UTF-16 code units:
// 𝄞 'MUSICAL SYMBOL G CLEF' (U+1D11E)
auto c7 = QChar(0x1D11E);           // compiles, but undefined behavior at runtime
auto c8 = QChar::fromUcs4(0x1D11E);       // always OK
auto c9 = QChar::fromUcs4(U'\U0001D11E'); // always OK
// => use c8/c9 as QStringView objects