Java : Matcher (正規表現) - API使用例

Matcher (Java SE 18 & JDK 18) の使用例まとめです。
だいたいのメソッドを網羅済みです。
API仕様のおともにどうぞ。


概要

Patternを解釈することによって、 文字シーケンスのマッチ操作を行うエンジンです。

クラス構成

Matcherは、正規表現によるパターンマッチングを行うクラスです。

マッチ操作には、

などがあります。
マッチ結果として、文字列のどの部分がマッチしたのか?を取得できます。

次のコード例では、正規表現による部分一致を行います。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abc 012 aaabc");

// 最初に一致するのはどこか?
System.out.println(matcher.find()); // true
System.out.println(matcher.start()); // 0
System.out.println(matcher.end()); // 3
System.out.println(matcher.group()); // "abc"

// 次に一致するのはどこか?
System.out.println(matcher.find()); // true
System.out.println(matcher.start()); // 8
System.out.println(matcher.end()); // 13
System.out.println(matcher.group()); // "aaabc"

// もう一致するものがないので false を返します。
System.out.println(matcher.find()); // false

もしくは、MatchResultとして結果を取得することもできます。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abc 012 aaabc");

final var stream = matcher.results();

stream.forEach(matchResult -> {

    System.out.println("------");
    System.out.println("start : " + matchResult.start());
    System.out.println("end : " + matchResult.end());
    System.out.println("group : " + matchResult.group());
});

// 結果
// ↓
//------
//start : 0
//end : 3
//group : abc
//------
//start : 8
//end : 13
//group : aaabc

個人的には、後発APIでもある後者の手法をおすすめします。

関連記事:正規表現の基本

メソッド

Matcher appendReplacement (StringBuffer sb, String replacement)

継続追加置換ステップを実装します。

final var pattern = Pattern.compile("cat");
final var matcher = pattern.matcher("one cat two cats in the yard");

final var sb = new StringBuffer();

while (matcher.find()) {
    matcher.appendReplacement(sb, "dog");
}

System.out.println(sb); // "one dog two dog"

matcher.appendTail(sb);

System.out.println(sb); // "one dog two dogs in the yard"

Matcher appendReplacement (StringBuilder sb, String replacement)

継続追加置換ステップを実装します。

final var pattern = Pattern.compile("cat");
final var matcher = pattern.matcher("one cat two cats in the yard");

final var sb = new StringBuilder();

while (matcher.find()) {
    matcher.appendReplacement(sb, "dog");
}

System.out.println(sb); // "one dog two dog"

matcher.appendTail(sb);

System.out.println(sb); // "one dog two dogs in the yard"

StringBuffer appendTail (StringBuffer sb)

終了追加置換ステップを実装します。

このメソッドの使用例は、appendReplacement(StringBuffer sb, String replacement) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

StringBuilder appendTail (StringBuilder sb)

終了追加置換ステップを実装します。

このメソッドの使用例は、appendReplacement(StringBuilder sb, String replacement) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

int end ()

最後にマッチした文字の後のオフセットを返します。

final var pattern = Pattern.compile("a+bc");
final var input = "aaaaabc";

final var matcher = pattern.matcher(input);
System.out.println(matcher.matches()); // true

final var start = matcher.start();
System.out.println(start); // 0

final var end = matcher.end();
System.out.println(end); // 7

final var group = input.substring(start, end);
System.out.println(group); // "aaaaabc"
final var pattern = Pattern.compile("a+bc");
final var input = "012abcXYZ";

final var matcher = pattern.matcher(input);
System.out.println(matcher.find()); // true

final var start = matcher.start();
System.out.println(start); // 3

final var end = matcher.end();
System.out.println(end); // 6

final var group = input.substring(start, end);
System.out.println(group); // "abc"

int end (int group)

前回のマッチ操作で指定されたグループによって前方参照された部分シーケンスの、最終文字の後のオフセットを返します。

final var pattern = Pattern.compile("(abc|efg)_012_(x..)");
final var matcher = pattern.matcher("abc_012_xyz");

// 完全一致
System.out.println(matcher.matches()); // true

System.out.println(matcher.start()); // 0
System.out.println(matcher.end()); // 11
System.out.println(matcher.group()); // "abc_012_xyz"

final var groupCount = matcher.groupCount();
System.out.println(groupCount); // 2

for (int i = 1; i <= groupCount; i++) {

    System.out.println("------");
    System.out.println("i : " + i);
    System.out.println("start : " + matcher.start(i));
    System.out.println("end : " + matcher.end(i));
    System.out.println("group : " + matcher.group(i));
}

// 結果
// ↓
//------
//i : 1
//start : 0
//end : 3
//group : abc
//------
//i : 2
//start : 8
//end : 11
//group : xyz

int end (String name)

前回のマッチ操作で、指定された名前付きの前方参照を行う正規表現グループによって前方参照された部分シーケンスの、最後の文字の後のオフセットを返します。

final var pattern = Pattern.compile("(?<A>abc|efg)_012_(?<B>x..)");
final var matcher = pattern.matcher("abc_012_xyz");

System.out.println(matcher.matches()); // true

final var result = matcher.toMatchResult();
System.out.println(result.start()); // 0
System.out.println(result.end()); // 11
System.out.println(result.group()); // "abc_012_xyz"

{
    final var name = "A";

    System.out.println(matcher.start(name)); // 0
    System.out.println(matcher.end(name)); // 3
    System.out.println(matcher.group(name)); // "abc"
}

{
    final var name = "B";

    System.out.println(matcher.start(name)); // 8
    System.out.println(matcher.end(name)); // 11
    System.out.println(matcher.group(name)); // "xyz"
}

boolean find ()

入力シーケンスからこのパターンとマッチする次の部分シーケンスを検索します。

関連API : results

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abc 012 aaabc");

{
    System.out.println(matcher.find()); // true

    final var result = matcher.toMatchResult();
    System.out.println(result.start()); // 0
    System.out.println(result.end()); // 3
    System.out.println(result.group()); // "abc"
}

{
    System.out.println(matcher.find()); // true

    final var result = matcher.toMatchResult();
    System.out.println(result.start()); // 8
    System.out.println(result.end()); // 13
    System.out.println(result.group()); // "aaabc"
}

System.out.println(matcher.find()); // false

boolean find (int start)

この正規表現エンジンをリセットし、指定されたインデックス以降の入力シーケンスから、このパターンとマッチする次の部分シーケンスを検索します。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("012 abc xyz aaabc");

{
    System.out.println(matcher.find(8)); // true

    final var result = matcher.toMatchResult();
    System.out.println(result.start()); // 12
    System.out.println(result.end()); // 17
    System.out.println(result.group()); // "aaabc"
}

{
    System.out.println(matcher.find(1)); // true

    final var result = matcher.toMatchResult();
    System.out.println(result.start()); // 4
    System.out.println(result.end()); // 7
    System.out.println(result.group()); // "abc"
}

String group ()

前回のマッチで一致した入力部分シーケンスを返します。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abc 012 aaabc xyz");

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "abc"

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "aaabc"

System.out.println(matcher.find()); // false

String group (int group)

前回のマッチ操作で指定されたグループによって前方参照された入力部分シーケンスを返します。

このメソッドの使用例は、end(int group) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

String group (String name)

前回のマッチ操作で指定された名前付きの前方参照を行うグループによって前方参照された入力部分シーケンスを返します。

このメソッドの使用例は、end(String name) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

int groupCount ()

この正規表現エンジンのパターンに指定されている前方参照を行う正規表現グループの数を返します。

このメソッドの使用例は、end(int group) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

boolean hasAnchoringBounds ()

この正規表現エンジンの領域境界のアンカー設定を問い合わせるクエリーを出します。

final var pattern = Pattern.compile("^abc xyz$");
final var input = "012 abc xyz";

{
    final var matcher = pattern.matcher(input);

    // デフォルト
    System.out.println(matcher.hasAnchoringBounds()); // true

    // マッチ範囲を "abc xyz" にします。
    // regionで指定した範囲として ^ や $ が有効になります。
    System.out.println(input.substring(4, 11)); // "abc xyz"
    matcher.region(4, 11);

    System.out.println(matcher.find()); // true

    final var result = matcher.toMatchResult();
    System.out.println(result.start()); // 4
    System.out.println(result.end()); // 11
    System.out.println(result.group()); // "abc xyz"
}

{
    final var matcher = pattern.matcher(input);

    // 無効に変更します。
    matcher.useAnchoringBounds(false);
    System.out.println(matcher.hasAnchoringBounds()); // false

    matcher.region(4, 11);
    System.out.println(matcher.find()); // false
}

boolean hasTransparentBounds ()

この正規表現エンジンの領域境界の透明度を問い合わせるクエリーを出します。

final var pattern = Pattern.compile("\\by...");
final var input = "xyz12 yz34";

{
    final var matcher = pattern.matcher(input);

    // デフォルト
    System.out.println(matcher.hasTransparentBounds()); // false

    // マッチ範囲を "yz12 yz34" にします。
    System.out.println(input.substring(1, 10)); // "yz12 yz34"
    matcher.region(1, 10);

    System.out.println(matcher.find()); // true

    final var result = matcher.toMatchResult();
    System.out.println(result.group()); // "yz12"
}

{
    final var matcher = pattern.matcher(input);

    // 有効に変更します。
    matcher.useTransparentBounds(true);
    System.out.println(matcher.hasTransparentBounds()); // true

    // マッチ範囲を "yz12 yz34" にします。
    matcher.region(1, 10);

    // \b の単語境界として、regionの範囲外も考慮されます。
    // つまり、"xyz12" が単語として認識されるため、
    // 最初の "yz12" はヒットせず、"yz34" がヒットします。
    System.out.println(matcher.find()); // true

    final var result = matcher.toMatchResult();
    System.out.println(result.group()); // "yz34"
}

boolean hitEnd ()

この正規検索エンジンが実行した最後のマッチ操作で、入力の末尾が検索エンジンによりヒットした場合に、trueを返します。

final var pattern = Pattern.compile("cat");
final var matcher = pattern.matcher("one cat two cats in the yard");

while (matcher.find()) {

    System.out.println("-------");
    System.out.println("hitEnd : " + matcher.hitEnd());

    final var result = matcher.toMatchResult();
    System.out.println("start : " + result.start());
    System.out.println("end : " + result.end());
}

// 結果
// ↓
//-------
//hitEnd : false
//start : 4
//end : 7
//-------
//hitEnd : false
//start : 12
//end : 15

System.out.println(matcher.hitEnd()); // true

boolean lookingAt ()

入力シーケンスとパターンとのマッチを、領域の先頭から始めます。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("aaabc");

System.out.println(matcher.lookingAt()); // true

final var result = matcher.toMatchResult();
System.out.println(result.start()); // 0
System.out.println(result.end()); // 5
System.out.println(result.group()); // "aaabc"
final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abcXYZ");

System.out.println(matcher.lookingAt()); // true

final var result = matcher.toMatchResult();
System.out.println(result.start()); // 0
System.out.println(result.end()); // 3
System.out.println(result.group()); // "abc"
final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("012abc");

System.out.println(matcher.lookingAt()); // false

boolean matches ()

領域全体をこのパターンとマッチします。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abc");

System.out.println(matcher.matches()); // true

final var result = matcher.toMatchResult();
System.out.println(result.start()); // 0
System.out.println(result.end()); // 3
System.out.println(result.group()); // "abc"
final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("aaaaabc");

System.out.println(matcher.matches()); // true

final var result = matcher.toMatchResult();
System.out.println(result.start()); // 0
System.out.println(result.end()); // 7
System.out.println(result.group()); // "aaaaabc"
final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("012abc");

System.out.println(matcher.matches()); // false
final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abcZ");

System.out.println(matcher.matches()); // false

Pattern pattern ()

この正規表現エンジンによって解釈されるパターンを返します。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("aaabc");

System.out.println(matcher.pattern()); // "a+bc"

static String quoteReplacement (String s)

指定されたStringのリテラル置換Stringを返します。

final var pattern = Pattern.compile(" "); // 半角スペース
final var matcher = pattern.matcher("abc 012 xyz");

final var replacement = Matcher.quoteReplacement("$");
System.out.println(replacement); // "\$"

final var ret = matcher.replaceAll(replacement);
System.out.println(ret); // "abc$012$xyz"

Matcher region (int start, int end)

正規検索エンジンの領域に制限を設定します。

final var pattern = Pattern.compile("a+bc+");

final var input = "aaabccc";
final var matcher = pattern.matcher(input);

// 範囲を "abcc" に指定します。
System.out.println(input.substring(2, 6)); // "abcc"
matcher.region(2, 6);

System.out.println(matcher.regionStart()); // 2
System.out.println(matcher.regionEnd()); // 6

System.out.println(matcher.matches()); // true

final var result = matcher.toMatchResult();
System.out.println(result.group()); // "abcc"
// regionを指定しない例です。
final var pattern = Pattern.compile("a+bc+");
final var matcher = pattern.matcher("aaabccc");

System.out.println(matcher.matches()); // true

final var result = matcher.toMatchResult();
System.out.println(result.group()); // "aaabccc"

int regionEnd ()

この正規検索エンジンの領域の終了インデックス(その値を含まない)をレポートします。

このメソッドの使用例は、region(int start, int end) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

int regionStart ()

この正規検索エンジンの領域の開始インデックスをレポートします。

このメソッドの使用例は、region(int start, int end) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

String replaceAll (String replacement)

パターンとマッチする入力シーケンスの部分シーケンスを、指定された置換文字列に置き換えます。

final var pattern = Pattern.compile("a*b");
final var matcher = pattern.matcher("aabfooaabfooabfoob");

final var result = matcher.replaceAll("-");
System.out.println(result); // "-foo-foo-foo-"

String replaceAll (Function<MatchResult,String> replacer)

パターンに一致する入力シーケンスのすべてのサブシーケンスを、そのサブシーケンスに対応するこのマッチャの一致結果に与えられた置換関数を適用した結果に置き換えます。

final var pattern = Pattern.compile("dog");
final var matcher = pattern.matcher("zzzdogzzzdogzzz");

final var result = matcher.replaceAll(mr -> mr.group().toUpperCase());
System.out.println(result); // "zzzDOGzzzDOGzzz"

String replaceFirst (String replacement)

パターンとマッチする入力シーケンスの部分シーケンスのうち、最初の部分シーケンスを指定された置換文字列に置き換えます。

final var pattern = Pattern.compile("dog");
final var matcher = pattern.matcher("zzzdogzzzdogzzz");

final var result = matcher.replaceFirst("cat");
System.out.println(result); // "zzzcatzzzdogzzz"

String replaceFirst (Function<MatchResult,String> replacer)

パターンに一致する入力シーケンスの最初のサブシーケンスを、そのサブシーケンスに対応するこのマッチャの一致結果に与えられた置換関数を適用した結果に置き換えます。

final var pattern = Pattern.compile("dog");
final var matcher = pattern.matcher("zzzdogzzzdogzzz");

final var result = matcher.replaceFirst(mr -> mr.group().toUpperCase());
System.out.println(result); // "zzzDOGzzzdogzzz"

boolean requireEnd ()

より多くの入力で正のマッチが負のマッチに変更される可能性がある場合に、trueを返します。

final var pattern = Pattern.compile("abc$");
final var matcher = pattern.matcher("abc");

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "abc"
System.out.println(matcher.requireEnd()); // true
final var pattern = Pattern.compile("abc");
final var matcher = pattern.matcher("abcd");

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "abc"
System.out.println(matcher.requireEnd()); // false

Matcher reset ()

この正規表現エンジンをリセットします。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abc aabc");

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "abc"

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "aabc"

System.out.println(matcher.find()); // false

matcher.reset();

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "abc"

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "aabc"

System.out.println(matcher.find()); // false

Matcher reset (CharSequence input)

新しい入力シーケンスを使用してこの正規表現エンジンをリセットします。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abc aabc");

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "abc"

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "aabc"

System.out.println(matcher.find()); // false

matcher.reset("aaaabc");

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "aaaabc"

System.out.println(matcher.find()); // false

Stream<MatchResult> results ()

パターンに一致する入力シーケンスの各サブシーケンスに対する一致結果のストリームを返します。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abc 012 aabc");

final var stream = matcher.results();

stream.forEach(matchResult -> {
    System.out.println(matchResult.group());
});

// 結果
// ↓
// "abc"
// "aabc"

int start ()

前回のマッチの開始インデックスを返します。

このメソッドの使用例は、end() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

int start (int group)

前回のマッチ操作で指定されたグループによって前方参照された部分シーケンスの、開始インデックスを返します。

このメソッドの使用例は、end(int group) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

int start (String name)

前回のマッチ操作で指定された名前付き前方参照グループによって前方参照された部分シーケンスの開始インデックスを返します。

このメソッドの使用例は、end(String name) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

MatchResult toMatchResult ()

このマッチャのマッチ状態をMatchResultとして返します。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abc aabc");

{
    System.out.println(matcher.find()); // true

    final var result = matcher.toMatchResult();
    System.out.println(result.start()); // 0
    System.out.println(result.end()); // 3
    System.out.println(result.group()); // "abc"
}

{
    System.out.println(matcher.find()); // true

    final var result = matcher.toMatchResult();
    System.out.println(result.start()); // 4
    System.out.println(result.end()); // 8
    System.out.println(result.group()); // "aabc"
}

String toString ()

この正規表現エンジンの文字列表現を返します。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("abc aabc");

System.out.println(matcher.find()); // true

final var str = matcher.toString();

// java.util.regex.Matcher[pattern=a+bc region=0,8 lastmatch=abc]
System.out.println(str);

Matcher useAnchoringBounds (boolean b)

この正規表現エンジンの領域境界のアンカーを設定します。

このメソッドの使用例は、hasAnchoringBounds() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

Matcher usePattern (Pattern newPattern)

このMatcherがマッチ検索に使用するPatternを変更します。

final var pattern = Pattern.compile("a+bc");
final var matcher = pattern.matcher("aabc xyz");

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "aabc"

System.out.println(matcher.find()); // false

matcher.usePattern(Pattern.compile("x.."));

System.out.println(matcher.find()); // true
System.out.println(matcher.group()); // "xyz"

Matcher useTransparentBounds (boolean b)

この正規表現エンジンの領域境界の透明度を設定します。

このメソッドの使用例は、hasTransparentBounds() にまとめて記載しました。
そちらのAPI使用例をご参照ください。


関連記事

ページの先頭へ