QChar Class

See also Unicode, QString, QLatin1Char

This enum maps the Unicode character categories.

The following characters are normative in Unicode:

The following categories are informative in Unicode:

See Also▲

This enum type defines the Unicode decomposition attributes. See the Unicode standard for a description of the values.

See Also▲

This enum type defines the Unicode direction attributes. See the Unicode Standard for a description of the values.

In order to conform to C/C++ naming conventions "Dir" is prepended to the codes used in the Unicode Standard.

See Also▲

since 5.3

This enum type defines the Unicode joining type attributes. See the Unicode standard for a description of the values.

In order to conform to C/C++ naming conventions "Joining_" is prepended to the codes used in the Unicode Standard.

See Also▲

This enum type defines the Unicode script property values.

For details about the Unicode script property values see Unicode Standard Annex #24.

In order to conform to C/C++ naming conventions "Script_" is prepended to the codes used in the Unicode Standard.

This enum was introduced or modified in Qt 5.1.

See Also▲

Specifies which version of the Unicode standard introduced a certain character.

See Also▲

Constructs a null QChar ('\0').

See Also▲

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

Constructs a QChar for Unicode cell cell in row row.

See Also▲

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

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

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

Constructs a QChar for the predefined character value ch.

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

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

This function was introduced in Qt 5.10.

Constructs a QChar corresponding to the wide character ch.

This function was introduced in Qt 5.10.

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

See Also▲

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

See Also▲

Returns the character's category.

This is an overloaded function.

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

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

See Also▲

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.

This is an overloaded function.

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

Returns the most recent supported Unicode version.

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

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.

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

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.

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

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.

Returns the character's direction.

This is an overloaded function.

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

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▲

Constructs a QChar from UTF-16 character c.

This function was introduced in Qt 6.0.

See Also▲

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▲

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▲

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▲

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

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

See Also▲

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▲

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.

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.

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

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.

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

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.

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.

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.

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

See Also▲

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▲

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

See QChar::Category for more information regarding marks.

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.

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.

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.

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

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

See Also▲

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▲

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.

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.

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

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.

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

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.

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.

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.

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

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.

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

See Also▲

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▲

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

See Also▲

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▲

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.

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.

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

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

See Also▲

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▲

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.

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

See Also▲

Returns the Unicode script property value for this character.

This function was introduced in Qt 5.1.

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.

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

This is an overloaded function.

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

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

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

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

See Also▲

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

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.

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

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.

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

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.

Returns the numeric Unicode value of the QChar.

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

Returns the Unicode version that introduced this character.

This is an overloaded function.

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

Returns true if c1 and c2 are not the same Unicode character; otherwise returns false.

Returns true if the numeric Unicode value of c1 is less than that of c2; otherwise returns false.

Writes the char chr to the stream out.

See Also▲

Returns true if the numeric Unicode value of c1 is less than or equal to that of c2; otherwise returns false.

Returns true if c1 and c2 are the same Unicode character; otherwise returns false.

Returns true if the numeric Unicode value of c1 is greater than that of c2; otherwise returns false.

Returns true if the numeric Unicode value of c1 is greater than or equal to that of c2; otherwise returns false.

Reads a char from the stream in into char chr.

See Also▲

Defining this macro makes certain QChar constructors implicit rather than explicit. This is done to enforce safe conversions:

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

This macro is provided to keep existing code working; it is recommended to instead use explicit conversions and/or QLatin1Char. For instance:

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

This macro was introduced in Qt 6.0.

See Also▲