PySide6.QtCore.QStringConverter¶
- class QStringConverter¶
The
QStringConverter
class provides a base class for encoding and decoding text. More…Inherited by:
QStringEncoder
,QStringDecoder
Synopsis¶
Methods¶
def
__init__()
def
hasError()
def
isValid()
def
name()
def
resetState()
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.
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 theQStringEncoder
andQStringDecoder
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 aQString
) to the requested encoding.The following encodings are always supported:
UTF-8
UTF-16
UTF-16BE
UTF-16LE
UTF-32
UTF-32BE
UTF-32LE
ISO-8859-1 (Latin-1)
The system encoding
QStringConverter
may support more encodings depending on how Qt was compiled. If more codecs are supported, they can be listed usingavailableCodecs()
.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 aQStringDecoder
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 theQStringEncoder
class:string = "..." fromUtf16 = QStringEncoder(QStringEncoder.Utf8) encodedString = fromUtf16(string)
To read or write text files in various encodings, use
QTextStream
and itssetEncoding()
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
andQStringDecoder
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.See also
- class 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 little-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 little-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¶
- __init__()¶
- __init__(name, f)
- Parameters:
name – str
f – Combination of
Flag
- static availableCodecs()¶
- Return type:
list of strings
Returns a list of names of supported codecs. The names returned by this function can be passed to
QStringEncoder
‘s andQStringDecoder
‘s constructor to create a en- or decoder for the given codec.This function may be used to obtain a listing of additional codecs beyond the standard ones. Support for additional codecs requires Qt be compiled with support for the ICU library.
Note
The order of codecs is an internal implementation detail and not guaranteed to be stable.
- 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.
- 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.
- 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. The returned name is UTF-8 encoded.See also
Returns the canonical name for encoding
e
.- resetState()¶
Resets the internal state of the converter, clearing potential errors or partial conversions.