QStringConverter Class
Die Klasse QStringConverter bietet eine Basisklasse für die Kodierung und Dekodierung von Text. Mehr...
| Kopfzeile: | #include <QStringConverter> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Vererbt von: |
Hinweis: Alle Funktionen in dieser Klasse sind reentrant.
Öffentliche Typen
| enum | Encoding { Utf8, Utf16, Utf16BE, Utf16LE, Utf32, …, System } |
| enum class | Flag { Default, ConvertInvalidToNull, WriteBom, ConvertInitialBom, Stateless } |
| flags | Flags |
Öffentliche Funktionen
| bool | hasError() const |
| bool | isValid() const |
| const char * | name() const |
| void | resetState() |
Statische öffentliche Mitglieder
| QStringList | availableCodecs() |
| std::optional<QStringConverter::Encoding> | encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0) |
| std::optional<QStringConverter::Encoding> | encodingForHtml(QByteArrayView data) |
| std::optional<QStringConverter::Encoding> | encodingForName(QAnyStringView name) |
| const char * | nameForEncoding(QStringConverter::Encoding e) |
Detaillierte Beschreibung
Qt verwendet UTF-16, um Strings zu speichern, zu zeichnen und zu manipulieren. In vielen Situationen werden Sie mit Daten umgehen wollen, die eine andere Kodierung verwenden. Die meisten Textdaten, die über Dateien und Netzwerkverbindungen übertragen werden, sind in UTF-8 kodiert.
Die Klasse QStringConverter ist eine Basisklasse für die Klassen QStringEncoder und QStringDecoder, die bei der Konvertierung zwischen verschiedenen Textkodierungen helfen. QStringDecoder kann eine Zeichenkette von einer kodierten Darstellung in UTF-16 dekodieren, das Format, das Qt intern verwendet. QStringEncoder führt den umgekehrten Vorgang aus, indem es UTF-16 kodierte Daten (normalerweise in Form einer QString) in die gewünschte Kodierung kodiert.
Die folgenden Kodierungen werden immer unterstützt:
- UTF-8
- UTF-16
- UTF-16BE
- UTF-16LE
- UTF-32
- UTF-32BE
- UTF-32LE
- ISO-8859-1 (Latein-1)
- Die Systemkodierung
QStringConverter kann weitere Kodierungen unterstützen, je nachdem wie Qt kompiliert wurde. Wenn mehr Codecs unterstützt werden, können diese mit availableCodecs() aufgelistet werden.
QStringConverters kann wie folgt verwendet werden, um eine kodierte Zeichenkette nach und von UTF-16 zu konvertieren.
Nehmen wir an, Sie haben eine Zeichenkette, die in UTF-8 kodiert ist, und wollen sie in QString konvertieren. Der einfache Weg, dies zu tun, ist die Verwendung von QStringDecoder wie hier:
QByteArray encodedString = "..."; auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); QString string = toUtf16(encodedString);
Danach enthält string den Text in dekodierter Form. Die Konvertierung einer Zeichenkette von Unicode in die lokale Kodierung ist mit der Klasse QStringEncoder genauso einfach:
QString string = "..."; auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8); QByteArray encodedString = fromUtf16(string);
Um Textdateien in verschiedenen Kodierungen zu lesen oder zu schreiben, verwenden Sie QTextStream und seine Funktion setEncoding().
Etwas Vorsicht ist geboten, wenn Sie versuchen, die Daten stückweise zu konvertieren, z. B. wenn Sie sie über ein Netzwerk empfangen. In solchen Fällen ist es möglich, dass ein Multi-Byte-Zeichen auf zwei Chunks aufgeteilt wird. Im besten Fall kann dies zum Verlust eines Zeichens führen, im schlimmsten Fall zum Scheitern der gesamten Konvertierung.
Sowohl QStringEncoder als auch QStringDecoder machen dies einfach, indem sie dies in einem internen Status verfolgen. Wenn Sie also den Encoder oder Decoder mit dem nächsten Datenpaket erneut aufrufen, werden die Daten automatisch korrekt weiter kodiert oder dekodiert:
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); QString string; while (new_data_available()) { QByteArray chunk = get_new_data(); string += toUtf16(chunk); }
Das QStringDecoder -Objekt behält den Zustand zwischen den Chunks bei und arbeitet daher auch dann korrekt, wenn ein Multi-Byte-Zeichen zwischen den Chunks aufgeteilt wird.
QStringConverter-Objekte können aufgrund ihres internen Zustands nicht kopiert werden, aber sie können verschoben werden.
Siehe auch QTextStream, QStringDecoder, und QStringEncoder.
Dokumentation der Mitgliedstypen
enum QStringConverter::Encoding
| Konstante | Wert | Beschreibung |
|---|---|---|
QStringConverter::Utf8 | 0 | Konverter nach oder von UTF-8 erstellen |
QStringConverter::Utf16 | 1 | Erzeugt einen Konverter nach oder von UTF-16. Bei der Dekodierung wird die Bytereihenfolge automatisch durch eine führende Byte Order Mark erkannt. Wenn keine vorhanden ist oder bei der Kodierung, wird die System-Byte-Reihenfolge angenommen. |
QStringConverter::Utf16BE | 3 | Erstellen Sie einen Konverter von oder nach Big-Endian UTF-16. |
QStringConverter::Utf16LE | 2 | Erstellen Sie einen Konverter von oder nach Little-Endian UTF-16. |
QStringConverter::Utf32 | 4 | Erstellen Sie einen Konverter nach oder von UTF-32. Bei der Dekodierung wird die Bytereihenfolge automatisch durch eine führende Byte Order Mark erkannt. Wenn keine vorhanden ist oder bei der Kodierung, wird die System-Byte-Reihenfolge angenommen. |
QStringConverter::Utf32BE | 6 | Erstellen Sie einen Konverter von oder nach Big-Endian UTF-32. |
QStringConverter::Utf32LE | 5 | Erstellen Sie einen Konverter von oder nach Little-Endian UTF-32. |
QStringConverter::Latin1 | 7 | Erstellen Sie einen Konverter von oder nach ISO-8859-1 (Latin1). |
QStringConverter::System | 8 | Erstellen Sie einen Konverter nach oder von der zugrunde liegenden Kodierung des Gebietsschemas des Betriebssystems. Für Unix-basierte Systeme wird immer UTF-8 angenommen. Unter Windows erfolgt die Konvertierung in und aus der Codepage des Gebietsschemas. |
enum class QStringConverter::Flag
flags QStringConverter::Flags
| Konstante | Wert | Beschreibung |
|---|---|---|
QStringConverter::Flag::Default | 0 | Es gelten die Standardkonvertierungsregeln. |
QStringConverter::Flag::ConvertInvalidToNull | 0x2 | Wenn dieses Flag gesetzt ist, wird jedes ungültige Eingabezeichen als Nullzeichen ausgegeben. Wenn es nicht gesetzt ist, werden ungültige Eingabezeichen als QChar::ReplacementCharacter dargestellt, wenn die Ausgabekodierung dieses Zeichen darstellen kann, andernfalls als Fragezeichen. |
QStringConverter::Flag::WriteBom | 0x4 | Bei der Konvertierung von einer QString in eine Ausgabekodierung schreiben Sie ein QChar::ByteOrderMark als erstes Zeichen, wenn die Ausgabekodierung dies unterstützt. Dies ist bei den Kodierungen UTF-8, UTF-16 und UTF-32 der Fall. |
QStringConverter::Flag::ConvertInitialBom | 0x8 | Bei der Konvertierung von einer Eingabekodierung in eine QString überspringt die QStringDecoder normalerweise ein führendes QChar::ByteOrderMark. Wenn dieses Flag gesetzt ist, wird die Byte-Order-Marke nicht übersprungen, sondern nach UTF-16 konvertiert und am Anfang des erzeugten QString eingefügt. |
QStringConverter::Flag::Stateless | 0x1 | Ignorieren Sie mögliche Konverterzustände zwischen verschiedenen Funktionsaufrufen zur Kodierung oder Dekodierung von Strings. Dies führt auch dazu, dass QStringConverter einen Fehler auslöst, wenn eine unvollständige Sequenz von Daten angetroffen wird. |
Der Typ Flags ist ein Typedef für QFlags<Flag>. Er speichert eine OR-Kombination von Flag-Werten.
Dokumentation der Mitgliedsfunktionen
[static] QStringList QStringConverter::availableCodecs()
Gibt eine Liste der Namen der unterstützten Codecs zurück. Die von dieser Funktion zurückgegebenen Namen können an den Konstruktor von QStringEncoder und QStringDecoder übergeben werden, um einen En- oder Decoder für den angegebenen Codec zu erstellen.
Diese Funktion kann verwendet werden, um eine Auflistung zusätzlicher Codecs neben den Standard-Codecs zu erhalten. Die Unterstützung für zusätzliche Codecs erfordert, dass Qt mit Unterstützung für die ICU-Bibliothek kompiliert wurde.
Hinweis: Die Reihenfolge der Codecs ist ein internes Implementierungsdetail und garantiert nicht, dass sie stabil ist.
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0)
Gibt die Kodierung für den Inhalt von data zurück, sofern sie ermittelt werden kann. expectedFirstCharacter kann als zusätzlicher Hinweis zur Ermittlung der Kodierung übergeben werden.
Das zurückgegebene Optional ist leer, wenn die Kodierung unklar ist.
[static] std::optional<QStringConverter::Encoding> QStringConverter::encodingForHtml(QByteArrayView data)
Versucht, die Kodierung des HTML in data zu bestimmen, indem er führende Byte-Order-Marken oder einen Zeichensatzbezeichner im HTML-Meta-Tag betrachtet. Wenn der optionale Parameter leer ist, wird die angegebene Kodierung von QStringConverter nicht unterstützt. Wenn keine Kodierung erkannt wird, gibt die Methode Utf8 zurück.
Siehe auch QStringDecoder::decoderForHtml().
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForName(QAnyStringView name)
Konvertiert name in den entsprechenden Encoding Member, falls vorhanden.
Wenn name nicht der Name eines in der Encoding-Aufzählung aufgeführten Codecs ist, wird std::nullopt zurückgegeben. Ein solcher Name kann dennoch vom QStringConverter Konstruktor akzeptiert werden, wenn Qt mit ICU gebaut wird, wenn ICU einen Konverter mit dem angegebenen Namen bereitstellt.
Hinweis: In Qt-Versionen vor 6.8 nahm diese Funktion nur einen const char * entgegen, von dem erwartet wurde, dass er UTF-8-kodiert ist.
[noexcept] bool QStringConverter::hasError() const
Gibt true zurück, wenn ein Zeichen nicht korrekt konvertiert werden konnte. Dies kann zum Beispiel durch eine ungültige UTF-8-Sequenz ausgelöst werden oder wenn ein Zeichen aufgrund von Einschränkungen in der Zielkodierung nicht konvertiert werden kann.
[noexcept] bool QStringConverter::isValid() const
Gibt true zurück, wenn es sich um einen gültigen Stringkonverter handelt, der für die Kodierung oder Dekodierung von Text verwendet werden kann.
Standardmäßig konstruierte Stringkonverter oder Konverter, die mit einem nicht unterstützten Namen konstruiert wurden, sind nicht gültig.
[noexcept] const char *QStringConverter::name() const
Gibt den kanonischen Namen der Kodierung zurück, die QStringConverter kodieren oder dekodieren kann. Gibt eine Nullptr zurück, wenn der Konverter nicht gültig ist. Der zurückgegebene Name ist UTF-8 kodiert.
Siehe auch isValid().
[static] const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e)
Gibt den kanonischen Namen für die Kodierung e zurück.
[noexcept] void QStringConverter::resetState()
Setzt den internen Zustand des Konverters zurück und löscht mögliche Fehler oder Teilumwandlungen.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
