QRegularExpression Class

詳細説明

正規表現（regexps）は、文字列やテキストを扱うための非常に強力なツールである。これは多くの文脈で有用である、

このドキュメントは正規表現を使ったパターン・マッチの完全なリファレンスではありません。

正規表現に関する良い参考文献は以下の通りです：

• ジェフリー・E・F・フリードル著「Mastering Regular Expressions(Third Edition)」ISBN 0-596-52812-4；
• pcrepattern(3)のマニュアルページで、PCRE（Perl互換正規表現のリファレンス実装）がサポートするパターン構文を説明しています；
• Perlの正規表現のドキュメントと Perlの正規表現のチュートリアル。

はじめに

QRegularExpression は Perl 互換の正規表現を実装しています。Unicodeを完全にサポートしています。QRegularExpression がサポートする正規表現の構文の概要については、前述の pcrepattern(3) man ページを参照してください。正規表現は、パターン文字列と、パターン文字列の意味を変更するパターン・オプションのセットの2つで構成されます。

パターン文字列を設定するには、QRegularExpressionコンストラクタに文字列を渡します：

QRegularExpression re("a pattern");

これは、パターン文字列をa pattern に設定します。また、setPattern() 関数を使用して、既存の QRegularExpression オブジェクトにパターンを設定することもできます：

QRegularExpression re;
re.setPattern("another pattern");

C++ リテラル文字列の規則により、パターン文字列内のすべてのバックスラッシュを別のバックスラッシュでエスケープする必要があることに注意してください：

// matches two digits followed by a space and a word
QRegularExpression re("\\d\\d \\w+");

// matches a backslash
QRegularExpression re2("\\\\");

この場合、パターン内のバックスラッシュをエスケープする必要はなく、R"(...)" の間の文字はすべて生の文字とみなされます。次の例でわかるように、これでパターンを書くのが簡単になります：

// matches two digits followed by a space and a word
QRegularExpression re(R"(\d\d \w+)");

pattern() 関数は、QRegularExpression オブジェクトに現在設定されているパターンを返します：

QRegularExpression re("a third pattern");
QString pattern = re.pattern(); // pattern == "a third pattern"

パターン・オプション

パターン文字列の意味は、1 つ以上のパターン・オプションを設定することで変更できます。たとえば、QRegularExpression::CaseInsensitiveOption.

オプションを設定するには、QRegularExpression コンストラクタに次のように渡します：

// matches "Qt rocks", but also "QT rocks", "QT ROCKS", "qT rOcKs", etc.
QRegularExpression re("Qt rocks", QRegularExpression::CaseInsensitiveOption);

または、既存の QRegularExpressionObject に対してsetPatternOptions() 関数を使用することもできます：

QRegularExpression re("^\\d+$");
re.setPatternOptions(QRegularExpression::MultilineOption);
// re matches any line in the subject string that contains only digits (but at least one)

patternOptions() 関数を使用すると、QRegularExpression オブジェクトに現在設定されているパターン・オプションを取得できます：

QRegularExpression re = QRegularExpression("^two.*words$", QRegularExpression::MultilineOption
                                                           | QRegularExpression::DotMatchesEverythingOption);

QRegularExpression::PatternOptions options = re.patternOptions();
// options == QRegularExpression::MultilineOption | QRegularExpression::DotMatchesEverythingOption

各パターン・オプションの詳細については、QRegularExpression::PatternOption enum ドキュメントを参照してください。

マッチ・タイプとマッチ・オプション

match() とglobalMatch() 関数の最後の2つの引数は、マッチタイプとマッチオプションを設定します。マッチタイプはQRegularExpression::MatchType enum の値です。"伝統的な" マッチングアルゴリズムはNormalMatch マッチタイプ (デフォルト) を使って選択されます。対象文字列に対する正規表現の部分マッチを有効にすることもできます: 詳細はpartial matching セクションを参照してください。

マッチオプションは、1つ以上のQRegularExpression::MatchOption 値の集合です。これらは、主題文字列に対する正規表現の特定のマッチの方法を変更します。詳細はQRegularExpression::MatchOption enum documentationを参照してください。

通常のマッチング

マッチングを行うには、match() 関数にマッチする文字列を 渡して呼び出すだけです。この文字列を件名文字列と呼びます。match() 関数の結果はQRegularExpressionMatch オブジェクトで、これを使用してマッチの結果を調べることができます。例えば

// match two digits followed by a space and a word
QRegularExpression re("\\d\\d \\w+");
QRegularExpressionMatch match = re.match("abc123 def");
bool hasMatch = match.hasMatch(); // true

マッチが成功した場合、（暗黙の）捕捉グループ番号0を使用して、パターン全体でマッチした部分文字列を取り出すことができます（extracting captured substrings のセクションも参照してください）：

QRegularExpression re("\\d\\d \\w+");
QRegularExpressionMatch match = re.match("abc123 def");
if (match.hasMatch()) {
    QString matched = match.captured(0); // matched == "23 def"
    // ...
}

また、match()関数の引数としてオフセットを渡すことで、対象文字列内の任意のオフセットからマッチを開始することも可能です。以下の例では、"12 abc" はオフセット 1 からマッチが開始されるため、マッチしません：

QRegularExpression re("\\d\\d \\w+");
QRegularExpressionMatch match = re.match("12 abc 45 def", 1);
if (match.hasMatch()) {
    QString matched = match.captured(0); // matched == "45 def"
    // ...
}

キャプチャされた部分文字列の抽出

QRegularExpressionMatch オブジェクトは、パターン文字列内の捕捉グループによって捕捉された部分文字列に関する情報も含んでいます。captured() 関数は、n番目の捕捉グループによって捕捉された文字列を返します：

QRegularExpression re("^(\\d\\d)/(\\d\\d)/(\\d\\d\\d\\d)$");
QRegularExpressionMatch match = re.match("08/12/1985");
if (match.hasMatch()) {
    QString day = match.captured(1); // day == "08"
    QString month = match.captured(2); // month == "12"
    QString year = match.captured(3); // year == "1985"
    // ...
}

パターン内の捕捉グループには1から番号が振られており、暗黙の捕捉グループ0は、パターン全体にマッチした部分文字列を捕捉するために使用されます。

また、capturedStart （）とcapturedEnd （）関数を使用することで、キャプチャされた部分文字列の開始オフセットと終了オフセット（対象文字列内）を取得することも可能です：

QRegularExpression re("abc(\\d+)def");
QRegularExpressionMatch match = re.match("XYZabc123defXYZ");
if (match.hasMatch()) {
    int startOffset = match.capturedStart(1); // startOffset == 6
    int endOffset = match.capturedEnd(1); // endOffset == 9
    // ...
}

これらの関数はすべて、QString をパラメータとするオーバーロードを持っており、名前付きキャプチャ部分文字列を抽出することができます。例えば

QRegularExpression re("^(?<date>\\d\\d)/(?<month>\\d\\d)/(?<year>\\d\\d\\d\\d)$");
QRegularExpressionMatch match = re.match("08/12/1985");
if (match.hasMatch()) {
    QString date = match.captured("date"); // date == "08"
    QString month = match.captured("month"); // month == "12"
    QString year = match.captured("year"); // year == 1985
}

グローバル・マッチング

グローバル・マッチングは、対象の文字列の中で指定された正規表現が出現する箇所をすべて見つけるのに便利です。与えられた文字列からすべての単語を抽出したいとします。単語はパターン\w+ にマッチする部分文字列です。

QRegularExpression::globalMatch QRegularExpressionMatchIteratorこれはJavaのような順方向イテレータで、結果を反復処理するのに使用できる。例えば

QRegularExpression re("(\\w+)");
QRegularExpressionMatchIterator i = re.globalMatch("the quick fox");

Javaライクなイテレータなので、QRegularExpressionMatchIterator は最初の結果の直前を指す。すべての結果は、QRegularExpressionMatch オブジェクトとして返されます。hasNext()関数は、少なくとももう1つ結果があれば真を返し、next()は次の結果を返してイテレーターを進めます。前の例の続きです：

QStringList words;
while (i.hasNext()) {
    QRegularExpressionMatch match = i.next();
    QString word = match.captured(1);
    words << word;
}
// words contains "the", "quick", "fox"

イテレータを進めずに次の結果を取得するには、peekNext() を使用することもできます。

また、QRegularExpression::globalMatch の結果を範囲ベースの for ループで使用することもできます：

// using a raw string literal, R"(raw_characters)", to be able to use "\w"
// without having to escape the backslash as "\\w"
QRegularExpression re(R"(\w+)");
QString subject("the quick fox");
for (const QRegularExpressionMatch &match : re.globalMatch(subject)) {
    // ...
}

match() を使った通常のマッチングとまったく同じように、開始オフセットと 1 つ以上のマッチ・オプションをglobalMatch() 関数に渡すことができます。

部分マッチング

部分マッチは、対象文字列の末尾に達したが、マッチを成功させるためにさらに文字が必要な場合に得られます。部分マッチは、マッチング・アルゴリズムの多くの最適化ができないため、 通常、通常のマッチよりもはるかに非効率的であることに注意してください。

部分一致は、QRegularExpression::match またはQRegularExpression::globalMatch を呼び出すときに、PartialPreferCompleteMatch またはPartialPreferFirstMatch のマッチタイプを指定して明示的に要求する必要がある。 部分一致が見つかった場合、match() が返すQRegularExpressionMatch オブジェクトに対してhasMatch() 関数を呼び出すと、false が返されるが、hasPartialMatch() はtrue が返される。

部分一致が見つかった場合、キャプチャされた部分文字列は返されず、全体一致に対応する （暗黙の）キャプチャグループ0が、部分一致した対象文字列の部分文字列をキャプチャする。

部分一致を要求しても、完全一致が見つかれば、完全一致になることに注意。この場合、hasMatch() はtrue を返し、hasPartialMatch() はfalse を返す。QRegularExpressionMatch が部分一致と完全一致の両方を報告することはない。

部分一致は主に、リアルタイムでのユーザー入力の検証と、インクリメンタル/マルチセグメント・マッチングの2つのシナリオで有用である。

ユーザー入力の検証

たとえば "MMM dd, yyyy "のように、特定のフォーマットで日付を入力させたいとする。入力の妥当性は、次のようなパターンでチェックできる：

^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d\d?, \d\d\d\d$

(このパターンでは無効な日は検出されませんが、この例のために残しておきましょう）。

ユーザーが入力をタイプしている間に、この正規表現で入力を検証して、入力がコミットされるとすぐにエラーを報告できるようにしたいと思います（たとえば、ユーザーが間違ったキーをタイプした場合など）。そのためには、3つのケースを区別しなければならない：

• 入力が正規表現にマッチしない；
• 入力が正規表現にマッチする；
• 入力は今は正規表現にマッチしないが、文字が追加されればマッチする。

これらの3つのケースは、まさにQValidator （QValidator::State enumを参照）の可能な状態を表していることに注意してください。

特に、最後のケースでは、正規表現エンジンに部分一致を報告させたい: subject文字列に対するパターンのマッチングには成功しているが、 subjectの最後に遭遇したため、マッチングを続けることができない。しかし、マッチングアルゴリズムはすべての可能性を試し続け、完全な(部分的でない)マッチが見つかった場合、このマッチを報告し、入力文字列を完全に有効なものとして受け入れるべきであることに注意してください。

この動作は、PartialPreferCompleteMatch マッチ・タイプによって実装されている。例えば

QString pattern("^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \\d\\d?, \\d\\d\\d\\d$");
QRegularExpression re(pattern);

QString input("Jan 21,");
QRegularExpressionMatch match = re.match(input, 0, QRegularExpression::PartialPreferCompleteMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

同じ正規表現をサブジェクト文字列にマッチさせると完全一致になる場合は、通常通り報告されます：

QString input("Dec 8, 1985");
QRegularExpressionMatch match = re.match(input, 0, QRegularExpression::PartialPreferCompleteMatch);
bool hasMatch = match.hasMatch(); // true
bool hasPartialMatch = match.hasPartialMatch(); // false

別のパターンによる別の例では、部分一致よりも完全一致を優先する挙動を示している：

QRegularExpression re("abc\\w+X|def");
QRegularExpressionMatch match = re.match("abcdef", 0, QRegularExpression::PartialPreferCompleteMatch);
bool hasMatch = match.hasMatch(); // true
bool hasPartialMatch = match.hasPartialMatch(); // false
QString captured = match.captured(0); // captured == "def"

この場合、サブパターンabc\\w+X はサブジェクト文字列と部分的にマッチします。しかし、サブパターンdef はサブジェクト文字列と完全にマッチするため、完全なマッチが報告されます。

マッチング時に複数の部分一致が見つかった場合 (完全一致は見つからなかった場合)、QRegularExpressionMatch オブジェクトは最初に見つかったものを報告します。例えば

QRegularExpression re("abc\\w+X|defY");
QRegularExpressionMatch match = re.match("abcdef", 0, QRegularExpression::PartialPreferCompleteMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true
QString captured = match.captured(0); // captured == "abcdef"

インクリメンタル/マルチセグメントマッチング

インクリメンタル・マッチングも部分マッチングの使用例である。大きなテキストの中にある正規表現の出現箇所（つまり、正規表現にマッチする部分文字列）を見つけたいとする。そのためには、大きなテキストを小さな塊にして正規表現エンジンに「供給」したい。明らかな問題は、正規表現にマッチする部分文字列が2つ以上のチャンクにまたがる場合にどうなるかです。

この場合、正規表現エンジンは部分一致を報告し、新しいデータを追加して再度マッチさせ、（最終的に）完全一致を得ることができるはずです。このことは、正規表現エンジンが、対象文字列の末尾以外にも文字があると仮定する可能性があることを意味する。これは文字通りの意味ではなく、エンジンはサブジェクトの最後の文字以降の文字にアクセスしようとすることはありません。

QRegularExpression は、PartialPreferFirstMatch マッチ・タイプを使用するときにこの動作を実装します。このマッチタイプは、部分一致が見つかるとすぐにそれを報告し、他のマッチの選択肢は（完全一致につながる可能性があっても）試されません。たとえば

QRegularExpression re("abc|ab");
QRegularExpressionMatch match = re.match("ab", 0, QRegularExpression::PartialPreferFirstMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

これは、alternation operatorの最初のブランチにマッチしたときに部分一致が見つかり、マッチングが停止して、2番目のブランチが試されないために起こります。もうひとつの例：

QRegularExpression re("abc(def)?");
QRegularExpressionMatch match = re.match("abc", 0, QRegularExpression::PartialPreferFirstMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

? は貪欲なので、エンジンはまず、"abc" にマッチした後、マッチを継続しようとします。しかし、その後、マッチは対象文字列の最後に到達するので、部分一致が報告されます。これは次の例ではさらに驚くべきことです：

QRegularExpression re("(abc)*");
QRegularExpressionMatch match = re.match("abc", 0, QRegularExpression::PartialPreferFirstMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

エンジンは主語文字列が、マッチを探そうとしているテキスト全体の部分文字列だけであることを想定していることを思い出せば、この動作を理解するのは簡単です（つまり、前に述べたように、エンジンは主語文字列の末尾の先にも他の文字があることを想定しているのです）。

* "abc" "abc"たとえば、完全なテキストは "abcabcX "であったかもしれず、したがって（完全なテキストで）報告すべき正しいマッチは"abcabc" であったでしょう；先頭の"abc" に対してのみマッチすることで、代わりに部分的なマッチが得られます。

エラー処理

パターン文字列の構文エラーにより、QRegularExpression オブジェクトが無効になることがあります。isValid() 関数は正規表現が有効であれば真を、そうでなければ偽を返します：

QRegularExpression invalidRe("(unmatched|parenthesis");
bool isValid = invalidRe.isValid(); // false

errorStringさらに、patternErrorOffset() 関数は、パターン文字列内のオフセットを返します。

QRegularExpression invalidRe("(unmatched|parenthesis");
if (!invalidRe.isValid()) {
    QString errorString = invalidRe.errorString(); // errorString == "missing )"
    int errorOffset = invalidRe.patternErrorOffset(); // errorOffset == 22
    // ...
}

無効な QRegularExpression とのマッチが試みられた場合、返されるQRegularExpressionMatch オブジェクトも同様に無効です (つまり、isValid() 関数は false を返します)。グローバル一致を試みる場合も同様です。

サポートされていない Perl 互換の正規表現機能

QRegularExpression は Perl 互換の正規表現で利用可能なすべての機能をサポートしているわけではありません。最も顕著なものは、グループをキャプチャするための重複した名前がサポートされておらず、それらを使用すると未定義の動作につながる可能性があるという事実です。

これは Qt の将来のバージョンで変更される可能性があります。

QRegularExpression を使用するコードのデバッグ

QRegularExpression は、マッチング・アルゴリズムの実行を最適化するために、内部的にジャスト・イン・タイム・コンパイラ（JIT）を使用します。JIT は自己修正コードを広範囲に使用するため、Valgrind などのデバッグ・ツールがクラッシュする可能性があります。QRegularExpression（例えば、Valgrindの--smc-check コマンドラインオプション）を使用してプログラムをデバッグしたい場合は、自己修正コードのチェックをすべて有効にする必要があります。このようなチェックを有効にすることの欠点は、プログラムの実行速度がかなり遅くなることです。

それを避けるために、デバッグモードでQtをコンパイルする場合、JITはデフォルトで無効になります。QT_ENABLE_REGEXP_JIT デバッグモードでもリリースモードでも）デフォルトをオーバーライドして、JITの使用を有効または無効にすることができます。