QRegularExpression Class

詳細説明

正規表現（regexp）は、文字列やテキストを扱うための非常に強力なツールです。これは、例えば次のような多くの場面で役立ちます。

この文書は、正規表現を用いたパターンマッチングに関する完全なリファレンスというわけではありません。また、以下の部分を読むには、Perl風の正規表現とそのパターン構文に関する基本的な知識が必要です。

正規表現に関する優れた参考資料としては、以下が挙げられます：

• 『Mastering Regular Expressions』（第3版）Jeffrey E. F. Friedl 著、ISBN 0-596-52812-4;
• PCRE（Perl互換正規表現のリファレンス実装）がサポートするパターン構文を解説したpcrepattern(3)のマニュアルページ；
• Perlの正規表現に関するドキュメントおよびPerlの正規表現チュートリアル。

はじめに

QRegularExpression は、Perl 互換の正規表現を実装しています。Unicode を完全にサポートしています。QRegularExpression がサポートする正規表現の構文の概要については、前述の pcrepattern(3) マニュアルページを参照してください。 正規表現は、パターン文字列と、そのパターン文字列の意味を変更する一連のパターンオプションという 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 列挙型のドキュメントを参照してください。

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

match() およびglobalMatch() 関数の最後の 2 つの引数により、マッチタイプとマッチオプションが設定されます。 マッチタイプは、QRegularExpression::MatchType 列挙型の値です。「従来の」マッチングアルゴリズムは、NormalMatch マッチタイプ（デフォルト）を使用することで選択されます。また、対象文字列に対する正規表現の部分一致を有効にすることも可能です。詳細については、「partial matching 」のセクションを参照してください。

マッチオプションは、1つ以上のQRegularExpression::MatchOption 値のセットです。これらは、対象文字列に対する正規表現の特定の一致処理の方法を変更します。詳細については、QRegularExpression::MatchOption 列挙型のドキュメントを参照してください。

通常のマッチング

マッチングを実行するには、マッチング対象の文字列を引数として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() 関数の引数としてオフセットを指定することで、対象文字列内の任意のオフセット位置からマッチを開始することも可能です。次の例では、マッチがオフセット 1 から開始されるため、"12 abc" は一致しません：

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つ結果が残っている場合にtrueを返し、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)) {
    // ...
}

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

部分一致

部分一致とは、対象文字列の末尾に到達したものの、一致を完了させるためにさらに文字が必要な状態を指します。なお、部分一致では一致アルゴリズムの多くの最適化を適用できないため、通常の一致に比べてはるかに非効率的であることに注意してください。

部分一致を行うには、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 列挙型を参照してください）。

特に、最後のケースでは、正規表現エンジンに部分一致を報告させたいと考えています。つまり、対象文字列に対してパターンの一致は成功しているものの、対象文字列の末尾に到達したため、それ以上の一致処理を続けることができない状態です。 ただし、マッチングアルゴリズムは継続してすべての可能性を試すべきであり、完全な（部分的なものではない）一致が見つかった場合は、それを報告し、入力文字列を完全に有効なものとして受け入れるべきであることに注意してください。

この挙動は、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

別のパターンを用いたもう1つの例で、部分一致よりも完全一致を優先する動作を示します：

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

これは、選択演算子の最初の分岐をマッチングする際に部分一致が見つかり、そのため 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

この挙動は、エンジンが対象文字列を、一致を検索対象とするテキスト全体の単なる部分文字列であると想定していることを思い出せば、容易に理解できます（つまり、前述したように、エンジンは対象文字列の末尾の先に他の文字が存在すると想定しているのです）。

* という量指定子は貪欲（greedy）であるため、完全一致として報告することはエラーとなる可能性があります。なぜなら、現在の対象文字列"abc" の後に、"abc" という他の出現箇所が存在する可能性があるからです。 例えば、完全なテキストが「abcabcX」であった場合、（完全なテキストにおいて）報告すべき正しい一致は「"abcabc" 」となります。しかし、先頭の「"abc" 」のみに一致させた結果、部分一致として報告されてしまいます。

エラー処理

パターン文字列の構文エラーにより、QRegularExpressionオブジェクトが無効になる可能性があります。isValid()関数は、正規表現が有効な場合はtrueを、そうでない場合はfalseを返します:

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 ` をそれぞれ 0 以外の値または 0 に設定することで、デフォルト設定を上書きし、JIT の使用を有効または無効にすることができます（デバッグモードおよびリリースモードの両方で可能です）。