QStringConverter Class
QStringConverter クラスは、テキストをエンコードおよびデコードするための基底クラスを提供します。詳細...
| ヘッダ | #include <QStringConverter> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
| によって継承される： |
注意：このクラスの関数はすべてリエントラントです。
パブリック型
| enum | Encoding { Utf8, Utf16, Utf16BE, Utf16LE, Utf32, …, System } |
| enum class | Flag { Default, ConvertInvalidToNull, WriteBom, ConvertInitialBom, Stateless } |
| flags | Flags |
パブリック関数
| bool | hasError() const |
| bool | isValid() const |
| const char * | name() const |
| void | resetState() |
静的パブリック・メンバ
| 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) |
詳しい説明
Qt は文字列の保存、描画、操作に UTF-16 を使用します。多くの場面で、異なるエンコーディングを使用するデータを扱いたいと思うかもしれません。ファイルやネットワーク接続を介して転送されるほとんどのテキストデータは、UTF-8でエンコードされています。
QStringConverter クラスは、異なるテキストエンコーディング間の変換を支援するQStringEncoder とQStringDecoder クラスの基本クラスです。QStringDecoder は、エンコードされた表現から、Qt が内部的に使用している形式である UTF-16 に文字列をデコードします。QStringEncoder は、逆の操作を行い、UTF-16 でエンコードされたデータ（通常はQString の形式）を、要求されたエンコーディングにエンコードします。
以下のエンコーディングは常にサポートされています：
- UTF-8
- UTF-16
- UTF-16BE
- UTF-16LE
- UTF-32
- UTF-32BE
- UTF-32LE
- ISO-8859-1 (Latin-1)
- システムエンコーディング
QStringConverter は、Qt のコンパイル方法によってはさらに多くのエンコーディングをサポートしている場合があります。より多くのコーデックがサポートされている場合は、availableCodecs() を使用して一覧表示できます。
QStringConverterを使用して、エンコードされた文字列をUTF-16に変換したり、UTF-16から変換したりすることができます。
UTF-8でエンコードされた文字列があり、それをQString 。これを行う簡単な方法は、次のようにQStringDecoder を使用することです：
QByteArray encodedString = "..."; auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); QString string = toUtf16(encodedString);
この後、string はデコードされた形でテキストを保持する。文字列をUnicodeからローカル・エンコーディングに変換するのも、QStringEncoder クラスを使えば簡単です：
QString string = "..."; auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8); QByteArray encodedString = fromUtf16(string);
さまざまなエンコーディングでテキスト・ファイルを読み書きするには、QTextStream とそのsetEncoding() 関数を使います。
データをネットワーク経由で受信する場合など、チャンク単位で変換しようとする場合には、若干の注意が必要です。このような場合、マルチバイト文字が2つのチャンクに分割される可能性があります。この場合、せいぜい1文字が失われる程度で、最悪の場合、変換全体が失敗する可能性があります。
QStringEncoder とQStringDecoder の両方が、内部状態でこれを追跡することによって、これを簡単にします。そのため、次のデータのチャンクでエンコーダーまたはデコーダーを再度呼び出すだけで、自動的に正しくエンコードまたはデコードが続行されます：
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); QString string; while (new_data_available()) { QByteArray chunk = get_new_data(); string += toUtf16(chunk); }
QStringDecoder オブジェクトはチャンク間の状態を保持するので、マルチバイト文字がチャンク間で分割されても正しく動作する。
QStringConverterオブジェクトはその内部状態のためにコピーすることはできないが、移動することはできる。
QTextStream 、QStringDecoder 、QStringEncoderも参照のこと 。
メンバ型ドキュメント
enum QStringConverter::Encoding
| 定数 | 値 | 説明 |
|---|---|---|
QStringConverter::Utf8 | 0 | UTF-8への、またはUTF-8からのコンバータの作成 |
QStringConverter::Utf16 | 1 | UTF-16への、またはUTF-16からのコンバータを作成します。デコード時、バイト順は先頭のバイト順マークによって自動的に検出されます。存在しない場合やエンコード時には、システムのバイト順が仮定されます。 |
QStringConverter::Utf16BE | 3 | ビッグエンディアンUTF-16への、またはビッグエンディアンUTF-16からのコンバータを作成します。 |
QStringConverter::Utf16LE | 2 | リトルエンディアンUTF-16への、またはリトルエンディアンUTF-16からのコンバータを作成する。 |
QStringConverter::Utf32 | 4 | UTF-32への、またはUTF-32からのコンバータを作成する。デコード時、バイト順は先頭のバイト順マークによって自動的に検出されます。存在しない場合やエンコード時には、システムのバイト順序が仮定されます。 |
QStringConverter::Utf32BE | 6 | ビッグエンディアンUTF-32への、またはビッグエンディアンUTF-32からのコンバータを作成します。 |
QStringConverter::Utf32LE | 5 | リトルエンディアンUTF-32への、またはリトルエンディアンUTF-32からのコンバータを作成する。 |
QStringConverter::Latin1 | 7 | ISO-8859-1（Latin1）との間でコンバータを作成する。 |
QStringConverter::System | 8 | オペレーティングシステムのロケールの基本エンコーディングとのコンバータを作成します。Unixベースのシステムでは、これは常にUTF-8と仮定される。Windows では、ロケールのコードページとの間で変換を行います。 |
enum class QStringConverter::Flag
flags QStringConverter::Flags
| 定数 | 値 | 説明 |
|---|---|---|
QStringConverter::Flag::Default | 0 | デフォルトの変換規則を適用する。 |
QStringConverter::Flag::ConvertInvalidToNull | 0x2 | このフラグが設定されている場合、無効な入力文字はそれぞれヌル文字として出力される。このフラグが設定されていない場合、無効な入力文字は、出力エンコーディングがその文字を表現できる場合はQChar::ReplacementCharacter として表現され、そうでない場合はクエスチョンマークとして表現されます。 |
QStringConverter::Flag::WriteBom | 0x4 | QString から出力エンコーディングに変換する場合、出力エンコーディングがこれをサポートしていれば、最初の文字としてQChar::ByteOrderMark を記述します。これはUTF-8、UTF-16、UTF-32エンコーディングの場合です。 |
QStringConverter::Flag::ConvertInitialBom | 0x8 | 入力エン コ ーデ ィ ン グか らQString へ変換す る 際、QStringDecoder は通常、 先頭のQChar::ByteOrderMark をスキップ し ます。こ の フ ラ グが設定 さ れてい る と 、 バ イ ト 順序マー ク は ス キ ッ プ さ れず、 utf-16 に変換 さ れて作成 さ れ るQString の先頭に挿入 さ れます。 |
QStringConverter::Flag::Stateless | 0x1 | 文字列をエンコードまたはデコードする異なる関数呼び出しの間で起こりうるコンバーターの状態を無視する。また、不完全なデータ・シーケンスに遭遇した場合、QStringConverter はエラーを発生させる。 |
Flags 型はQFlags<Flag> の typedef です。Flag値のORの組み合わせを格納する。
メンバ関数ドキュメント
[static] QStringList QStringConverter::availableCodecs()
サポートされているコーデックの名前のリストを返す。この関数が返す名前をQStringEncoder やQStringDecoder のコンストラクタに渡すと、 指定されたコーデックのエンコーダーやデコーダーを作成することができます。
この関数は、標準コーデック以外の追加コーデックの一覧を取得するために使用できます。追加コーデックをサポートするには、QtがICUライブラリをサポートしてコンパイルされている必要があります。
注意: コーデックの順番は内部的な実装の詳細であり、安定性は保証されていません。
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0)
data の内容のエンコーディングが判断できればそれを返します。expectedFirstCharacter は、エンコーディングを判断するための追加ヒントとして渡すことができます。
エンコーディングが不明な場合は、返されるオプションは空です。
[static] std::optional<QStringConverter::Encoding> QStringConverter::encodingForHtml(QByteArrayView data)
HTML metaタグの先頭のバイトオーダマークかcharset指定子を見て、data のHTMLのエンコーディングを決定しようとする。オプションが空の場合、指定されたエンコーディングはQStringConverter でサポートされていません。エンコーディングが検出されなかった場合、このメソッドは Utf8 を返します。
QStringDecoder::decoderForHtml()も参照 。
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForName(QAnyStringView name)
対応するEncoding メンバがあれば、name を変換する。
name が Encoding 列挙にリストされているコーデックの名前でない場合、std::nullopt が返されます。ICUが指定された名前のコンバータを提供する場合、QtがICUとともにビルドされたときに、QStringConverter コンストラクタがそのような名前を受け入れる可能性があります。
注意: Qt 6.8より前のバージョンでは、この関数はUTF-8エンコードされたconst char * 。
[noexcept] bool QStringConverter::hasError() const
変換が文字を正しく変換できなかった場合に真を返します。これは例えば、無効なUTF-8シーケンスや、ターゲットエンコーディングの制限のために文字が変換できない場合に発生します。
[noexcept] bool QStringConverter::isValid() const
テキストのエンコードやデコードに使える有効な文字列コンバータであれば真を返す。
デフォルトで構築された文字列コンバータや、サポートされていない名前で構築されたコンバータは無効です。
[noexcept] const char *QStringConverter::name() const
このQStringConverter がエンコードまたはデコードできるエンコードの正規名を返します。コンバータが有効でない場合は nullptr を返します。返される名前は UTF-8 エンコードされたものです。
isValid()も参照 。
[static] const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e)
e をエンコードする際の正規名を返します。
[noexcept] void QStringConverter::resetState()
コンバータの内部状態をリセットし、潜在的なエラーや部分的な変換をクリアする。
© 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.
