QStringConverter

The QStringConverter class provides a base class for encoding and decoding text. More

Inheritance diagram of PySide6.QtCore.QStringConverter

Inherited by: QStringEncoder, QStringDecoder

Synopsis

Functions

Static functions

Detailed Description

Qt uses UTF-16 to store, draw and manipulate strings. In many situations you may wish to deal with data that uses a different encoding. Most text data transferred over files and network connections is encoded in UTF-8.

The QStringConverter class is a base class for the QStringEncoder and QStringDecoder classes that help with converting between different text encodings. QStringDecoder can decode a string from an encoded representation into UTF-16, the format Qt uses internally. QStringEncoder does the opposite operation, encoding UTF-16 encoded data (usually in the form of a QString ) to the requested encoding.

The supported encodings are:

  • UTF-8

  • UTF-16

  • UTF-16BE

  • UTF-16LE

  • UTF-32

  • UTF-32BE

  • UTF-32LE

  • ISO-8859-1 (Latin-1)

  • The system encoding

QStringConverter s can be used as follows to convert some encoded string to and from UTF-16.

Suppose you have some string encoded in UTF-8, and want to convert it to a QString . The simple way to do it is to use a QStringDecoder like this:

encodedString = "..."
toUtf16 = QStringDecoder(QStringDecoder.Utf8)
string = toUtf16(encodedString)

After this, string holds the text in decoded form. Converting a string from Unicode to the local encoding is just as easy using the QStringEncoder class:

string = "..."
fromUtf16 = QStringEncoder(QStringEncoder.Utf8)
encodedString = fromUtf16(encodedString)

To read or write text files in various encodings, use QTextStream and its setEncoding() function.

Some care must be taken when trying to convert the data in chunks, for example, when receiving it over a network. In such cases it is possible that a multi-byte character will be split over two chunks. At best this might result in the loss of a character and at worst cause the entire conversion to fail.

Both QStringEncoder and QStringDecoder make this easy, by tracking this in an internal state. So simply calling the encoder or decoder again with the next chunk of data will automatically continue encoding or decoding the data correctly:

toUtf16 = QStringDecoder(QStringDecoder.Utf8)
string = QString()
while new_data_available():
    chunk = get_new_data()
    string += toUtf16(chunk)

The QStringDecoder object maintains state between chunks and therefore works correctly even if a multi-byte character is split between chunks.

QStringConverter objects can’t be copied because of their internal state, but can be moved.

class PySide6.QtCore.QStringConverter

PySide6.QtCore.QStringConverter(encoding, f)

PySide6.QtCore.QStringConverter(name, f)

Parameters
  • fFlags

  • name – str

  • encodingEncoding

PySide6.QtCore.QStringConverter.Encoding

Constant

Description

QStringConverter.Utf8

Create a converter to or from UTF-8

QStringConverter.Utf16

Create a converter to or from UTF-16. When decoding, the byte order will get automatically detected by a leading byte order mark. If none exists or when encoding, the system byte order will be assumed.

QStringConverter.Utf16BE

Create a converter to or from big endian UTF-16.

QStringConverter.Utf16LE

Create a converter to or from litte endian UTF-16.

QStringConverter.Utf32

Create a converter to or from UTF-32. When decoding, the byte order will get automatically detected by a leading byte order mark. If none exists or when encoding, the system byte order will be assumed.

QStringConverter.Utf32BE

Create a converter to or from big endian UTF-32.

QStringConverter.Utf32LE

Create a converter to or from litte endian UTF-32.

QStringConverter.Latin1

Create a converter to or from ISO-8859-1 (Latin1).

QStringConverter.System

Create a converter to or from the underlying encoding of the operating systems locale. This is always assumed to be UTF-8 for Unix based systems. On Windows, this converts to and from the locale code page.

PySide6.QtCore.QStringConverter.state
PySide6.QtCore.QStringConverter.hasError()
Return type

bool

Returns true if a conversion could not correctly convert a character. This could for example get triggered by an invalid UTF-8 sequence or when a character can’t get converted due to limitations in the target encoding.

PySide6.QtCore.QStringConverter.isValid()
Return type

bool

Returns true if this is a valid string converter that can be used for encoding or decoding text.

Default constructed string converters or converters constructed with an unsupported name are not valid.

PySide6.QtCore.QStringConverter.name()
Return type

str

Returns the canonical name of the encoding this QStringConverter can encode or decode. Returns a nullptr if the converter is not valid.

See also

isValid()

static PySide6.QtCore.QStringConverter.nameForEncoding(e)
Parameters

eEncoding

Return type

str

Returns the canonical name for encoding e.

PySide6.QtCore.QStringConverter.resetState()

Resets the internal state of the converter, clearing potential errors or partial conversions.