java.util.regex
クラス Matcher

java.lang.Object
  |
  +--java.util.regex.Matcher

public final class Matcher

extends Object

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

正規表現エンジンは、パターンの matcher メソッドを呼び出すことによってパターンから作成されます。一度作成すると、次の 3 種類のマッチ操作に使用できます。

• matches メソッドでは、入力シーケンス全体とパターンがマッチされます。

• lookingAt メソッドでは、入力シーケンスの先頭からパターンがマッチされます。

• find メソッドでは、入力シーケンスを走査して、パターンとマッチする次の部分シーケンスを検索します。

これらのメソッドは、マッチが成功したかどうかを示す boolean 値を返します。マッチが成功したときは、正規表現エンジンの状態を照会すれば詳細を取得できます。

このクラスには、マッチした部分シーケンスを新しい文字列に置換するメソッドも定義します。新しい文字列の内容は、必要に応じてマッチ結果から算出できます。appendReplacement および appendTail メソッドを同時に使用すれば、マッチ結果を収集して既存の文字列バッファに格納できます。また、replaceAll メソッドを使用すれば、入力シーケンス内でマッチした部分シーケンスがすべて置換された文字列を作成できます。

正規表現エンジンの明示的な状態として、最後に成功したマッチの開始インデックスと終了インデックスがあります。また、パターンの各前方参照を行う正規表現グループによって前方参照された入力部分シーケンスの開始インデックスと終了インデックスや、前方参照された部分シーケンスの総数も利用されます。前方参照された部分シーケンスを文字列形式で返すメソッドも用意されています。

正規表現エンジンの明示的な状態の初期値は定義されていません。マッチが成功する前にその一部を照会しようとすると、IllegalStateException がスローされます。正規表現エンジンの明示的な状態は、マッチ操作のたびに計算し直されます。

正規表現エンジンの暗黙的な状態には、入力文字シーケンスや「追加位置」があります。追加位置の初期値はゼロで、appendReplacement メソッドによって更新されます。

正規表現エンジンをリセットするには、正規表現エンジンの reset() メソッドまたは reset(CharSequence) メソッド (新しい入力シーケンスが必要な場合) を呼び出します。正規表現エンジンをリセットすると、その明示的な状態に関する情報が破棄され、追加位置がゼロに設定されます。

このクラスのインスタンスは、複数のスレッドで同時に使用することはできません。

導入されたバージョン:

1.4

メソッドの概要

Matcher	appendReplacement(StringBuffer sb, String replacement) 継続追加置換手順を実装します。
StringBuffer	appendTail(StringBuffer sb) 終了追加置換手順を実装します。
int	end() 最後にマッチした文字のインデックスに 1 を加えたものを返します。
int	end(int group) 前回のマッチ操作で指定されたグループによって前方参照された部分シーケンスの、最後の文字のインデックスに 1 を加えたものを返します。
boolean	find() 入力シーケンスからこのパターンとマッチする次の部分シーケンスを検索します。
boolean	find(int start) この正規表現エンジンをリセットし、指定されたインデックス以降の入力シーケンスから、このパターンとマッチする次の部分シーケンスを検索します。
String	group() 前回のマッチで一致した入力部分シーケンスを返します。
String	group(int group) 前回のマッチ操作で指定されたグループによって前方参照された入力部分シーケンスを返します。
int	groupCount() この正規表現エンジンのパターンに指定されている前方参照を行う正規表現グループの数を返します。
boolean	lookingAt() 入力シーケンスの先頭からパターンとマッチします。
boolean	matches() 入力シーケンス全体をこのパターンとマッチします。
Pattern	pattern() この正規表現エンジンによって解釈されるパターンを返します。
String	replaceAll(String replacement) パターンとマッチする入力シーケンスの部分シーケンスを、指定された置換文字列に置き換えます。
String	replaceFirst(String replacement) パターンとマッチする入力シーケンスの部分シーケンスのうち、最初の部分シーケンスを指定された置換文字列に置き換えます。
Matcher	reset() この正規表現エンジンをリセットします。
Matcher	reset(CharSequence input) 新しい入力シーケンスを使用してこの正規表現エンジンをリセットします。
int	start() 前回のマッチの開始インデックスを返します。
int	start(int group) 前回のマッチ操作で指定されたグループによって前方参照された部分シーケンスの、開始インデックスを返します。

クラス java.lang.Object から継承したメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

メソッドの詳細

pattern

public Pattern pattern()

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

戻り値:

この正規表現エンジンの作成対象となったパターン

reset

public Matcher reset()

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

正規表現エンジンをリセットすると、その明示的な状態に関する情報がすべて破棄され、その追加位置がゼロに設定されます。

戻り値:

この正規表現エンジン

reset

public Matcher reset(CharSequence input)

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

正規表現エンジンをリセットすると、その明示的な状態に関する情報がすべて破棄され、その追加位置がゼロに設定されます。

パラメータ:

input - 新しい入力文字シーケンス

戻り値:

この正規表現エンジン

start

public int start()

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

戻り値:

マッチした最初の文字のインデックス

例外:

IllegalStateException - マッチが行われていない場合、または前回のマッチ操作が失敗した場合

start

public int start(int group)

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

前方参照を行う正規表現グループには、左から右方向に 1 からインデックスが付きます。グループ 0 はパターン全体を表します。つまり、m.start(0) と m.start() は同じ表現です。

パラメータ:

group - この正規表現エンジンのパターンに指定されている前方参照を行う正規表現グループのインデックス

戻り値:

このグループによって前方参照された最初の文字のインデックス。マッチは成功したが、グループ自体はマッチしなかった場合は、-1

例外:

IllegalStateException - マッチが行われていない場合、または前回のマッチ操作が失敗した場合

IndexOutOfBoundsException - 指定されたインデックスを持つ前方参照を行う正規表現グループがそのパターンに含まれない場合

end

public int end()

最後にマッチした文字のインデックスに 1 を加えたものを返します。

戻り値:

最後にマッチした文字のインデックスに 1 を加えたもの

例外:

IllegalStateException - マッチが行われていない場合、または前回のマッチ操作が失敗した場合

end

public int end(int group)

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

前方参照を行う正規表現グループには、左から右方向に 1 からインデックスが付きます。グループ 0 はパターン全体を表します。つまり、m.end(0) と m.end() は同じ表現です。

パラメータ:

group - この正規表現エンジンのパターンに指定されている前方参照を行う正規表現グループのインデックス

戻り値:

このグループによって前方参照された最後の文字のインデックスに 1 を加えたもの。マッチは成功したが、グループ自体はマッチしなかった場合は -1

例外:

IllegalStateException - マッチが行われていない場合、または前回のマッチ操作が失敗した場合

IndexOutOfBoundsException - 指定されたインデックスを持つ前方参照を行う正規表現グループがそのパターンに含まれない場合

group

public String group()

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

正規表現エンジン m に入力シーケンス s が指定されている場合、m.group() と s.substring(m.start(), m.end()) は同じ表現になります。

パターン (a* など) によっては、空の文字列とマッチすることがあります。これらのパターンが入力シーケンス内の空の文字列とマッチした場合、空の文字列が返されます。

戻り値:

前回のマッチで一致した部分シーケンス (空の場合もある)。文字列形式

例外:

IllegalStateException - マッチが行われていない場合、または前回のマッチ操作が失敗した場合

group

public String group(int group)

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

正規表現エンジン m、入力シーケンス s、およびグループインデックス g が指定されている場合、m.group(g) と s.substring(m.start(g), m.end(g)) は同じ表現になります。

前方参照を行う正規表現グループには、左から右方向に 1 からインデックスが付きます。グループ 0 はパターン全体を表します。つまり、m.group(0) と m.group() は同じ表現です。

マッチは正常終了したが、指定されたグループが入力シーケンスに検出されなかった場合、null が返されます。パターン ((a*) など) によっては、空の文字列とマッチすることがあります。これらのグループが入力シーケンス内の空の文字列とマッチした場合、空の文字列が返されます。

パラメータ:

group - この正規表現エンジンのパターンに指定されている前方参照を行う正規表現グループのインデックス

戻り値:

前回のマッチでグループによって前方参照された部分シーケンス (空の場合もある)。このグループが入力シーケンスに検出されなかった場合は null

例外:

IllegalStateException - マッチが行われていない場合、または前回のマッチ操作が失敗した場合

IndexOutOfBoundsException - 指定されたインデックスを持つ前方参照を行う正規表現グループがそのパターンに含まれない場合

groupCount

public int groupCount()

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

グループインデックスがこのメソッドから返された値より小さな正の整数の場合は、この正規表現エンジンで有効です。

戻り値:

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

matches

public boolean matches()

入力シーケンス全体をこのパターンとマッチします。

マッチが成功した場合は、start、end、および group メソッドを使用して詳細情報を取得できます。

戻り値:

入力シーケンス全体がこの正規表現エンジンのパターンとマッチした場合にかぎり、true

find

public boolean find()

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

このメソッドは、入力シーケンスの先頭から開始されます。ただし、前回の呼び出しが正常に終了してから正規表現エンジンがリセットされていない場合は、前回のマッチで一致しなかった最初の文字から開始されます。

マッチが成功した場合は、start、end、および group メソッドを使用して詳細情報を取得できます。

戻り値:

入力シーケンスの部分シーケンスがこの正規表現エンジンのパターンとマッチした場合にかぎり、true

find

public boolean find(int start)

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

マッチが成功した場合は、start、end、および group メソッドを使用して詳細情報を取得できます。後続の find() メソッド呼び出しでは、このマッチで一致しなかった最初の文字から開始されます。

戻り値:

指定されたインデックス以降の入力シーケンスから、この正規表現エンジンのパターンとマッチする部分シーケンスが検出された場合にかぎり、true

例外:

IndexOutOfBoundsException - 開始インデックスが、0 より小さい場合か、入力シーケンスの長さより大きい場合

lookingAt

public boolean lookingAt()

入力シーケンスの先頭からパターンとマッチします。

matches メソッドと同様に、入力シーケンスの先頭から開始されます。ただし、入力シーケンス全体がマッチする必要はありません。

マッチが成功した場合は、start、end、および group メソッドを使用して詳細情報を取得できます。

戻り値:

入力シーケンスの接頭辞がこの正規表現エンジンのパターンとマッチした場合にかぎり、true

appendReplacement

public Matcher appendReplacement(StringBuffer sb,
                                 String replacement)

継続追加置換手順を実装します。

このメソッドは、次の処理を実行します。

1. 追加位置以降の入力シーケンスから文字列を読み込み、指定された文字列バッファに追加します。前回マッチした文字の直前の文字、つまりインデックス start() - 1 の文字を読み込んだときに終了します。

2. 指定された置換文字列を文字列バッファに追加します。

3. この正規表現エンジンの追加位置を、最後にマッチした文字のインデックスに 1 を加えた値、つまり end() に設定します。

置換文字列には、前回のマッチ時に前方参照された部分シーケンスへの参照が含まれる場合があります。$g が検出されると、group(g) を評価した結果にすべて置換されます。たとえば、2 番目のグループが文字列 "foo" とマッチした場合は、置換文字列 "$2bar" を渡すと、"foobar" が文字列バッファに追加されます。ドル記号 ($) をリテラルとして置換文字列に含める場合は、その前にバックスラッシュを付けます (¥$)。

このメソッドは、ループ内で appendTail メソッドおよび find メソッドと組み合わせて使用します。たとえば、次のコードでは、one dog two dogs in the yard を標準出力ストリームに書き出します。

 Pattern p = Pattern.compile("cat");
 Matcher m = p.matcher("one cat two cats in the yard");
 StringBuffer sb = new StringBuffer();
 boolean result = m.find();
 while (m.appendReplacement(sb, "dog")) {
     result = m.find();
 }
 m.appendTail(sb);
 System.out.println(sb.toString());

パラメータ:

sb - ターゲット文字列バッファ

replacement - 置換文字列

戻り値:

この正規表現エンジン

例外:

IllegalStateException - マッチが行われていない場合、または前回のマッチ操作が失敗した場合

IndexOutOfBoundsException - パターンに存在しない前方参照を行う正規表現グループを置換文字列が参照している場合

appendTail

public StringBuffer appendTail(StringBuffer sb)

終了追加置換手順を実装します。

このメソッドは、追加位置以降の入力シーケンスから文字列を読み込み、指定された文字列バッファに追加します。入力シーケンスの残りの部分をコピーするために、appendReplacement メソッドを 1 回以上呼び出してからこのメソッドを呼び出します。

パラメータ:

sb - ターゲット文字列バッファ

戻り値:

ターゲット文字列バッファ

replaceAll

public String replaceAll(String replacement)

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

このメソッドはまず、この正規表現エンジンをリセットします。次に、入力シーケンスを走査して、パターンとマッチする文字列を検索します。パターンとマッチしない文字列は、結果文字列に直接追加されます。パターンとマッチした文字列は、置換文字列に置換されて結果に追加されます。appendReplacement メソッドと同様に、前方参照された部分シーケンスへの参照が置換文字列に含まれる場合があります。

正規表現 a*b、入力 "aabfooaabfooabfoob"、および置換文字列 "-" を指定した場合、その表現の正規表現エンジン上でこのメソッドを呼び出すと、文字列 "-foo-foo-foo-" が生成されます。

このメソッドを呼び出すと、この正規表現エンジンの状態が変わります。この正規表現エンジンを後続のマッチ操作で使用する場合は、最初に正規表現エンジンをリセットする必要があります。

パラメータ:

replacement - 置換文字列

戻り値:

マッチした部分シーケンスがすべて置換文字列に置換されて作成された文字列。必要に応じて、前方参照された部分シーケンスも置換される

replaceFirst

public String replaceFirst(String replacement)

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

このメソッドはまず、この正規表現エンジンをリセットします。次に、入力シーケンスを走査して、パターンとマッチする最初の文字列を検索します。パターンとマッチしない文字列は、結果文字列に直接追加されます。パターンとマッチした文字列は、置換文字列に置換されて結果に追加されます。appendReplacement メソッドと同様に、前方参照された部分シーケンスへの参照が置換文字列に含まれる場合があります。

正規表現 dog、入力 "zzzdogzzzdogzzz"、および置換文字列 "cat" を指定した場合、その表現の正規表現エンジン上でこのメソッドを呼び出すと、文字列 "zzzcatzzzdogzzz" が生成されます。

このメソッドを呼び出すと、この正規表現エンジンの状態が変わります。この正規表現エンジンを後続のマッチ操作で使用する場合は、最初に正規表現エンジンをリセットする必要があります。

パラメータ:

replacement - 置換文字列

戻り値:

マッチした最初の部分シーケンスが置換文字列に置換されて作成された文字列。必要に応じて、前方参照された部分シーケンスも置換される