QStringConverter Class
QStringConverter クラスは、テキストをエンコードおよびデコードするための基底クラスを提供します。詳細...
| Header: | #include <QStringConverter> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Inherited By: |
注意:このクラスの関数はすべてリエントラントです。
パブリック型
| 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)
data の HTML のエンコーディングを、先頭のバイトオーダマークや HTML meta タグの charset 指定子から判断しようとします。オプションが空の場合、指定されたエンコーディングはQStringConverter でサポートされていません。エンコーディングが検出されなかった場合、このメソッドは Utf8 を返します。
QStringDecoder::decoderForHtml()も参照 。
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForName(QAnyStringView name)
name を、対応するEncoding メンバがある場合はそれに変換します。
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()
コンバータの内部状態をリセットし、潜在的なエラーや部分的な変換をクリアします。
本ドキュメントに含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。
