モジュール java.base

パッケージ java.util.regex

クラスMatcher

java.lang.Object

java.util.regex.Matcher

すべての実装されたインタフェース:

MatchResult

public final class Matcher extends Object implements MatchResult

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

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

• matchesメソッドは、入力シーケンス全体とパターンをマッチする。

• lookingAtメソッドは、入力シーケンスの先頭から始めてパターンをマッチする。

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

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

正規検索エンジンは領域と呼ばれる入力のサブセットでマッチを検索します。 デフォルトでは、領域には正規検索エンジンの入力すべてが含まれます。 領域を変更するには、 regionメソッドを使用し、照会するには、regionStartメソッドおよびregionEndメソッドを使用します。 領域の境界による一定のパターン作成の方法は変更できます。 詳細は、useAnchoringBoundsおよびuseTransparentBoundsを参照してください。

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

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

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

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

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

このクラスのインスタンスは、複数のスレッドで並行して使用することはできません。

導入されたバージョン:

1.4

メソッドのサマリー

修飾子と型	メソッド	説明
Matcher	appendReplacement(StringBuffer sb, String replacement)	継続追加置換ステップを実装します。
Matcher	appendReplacement(StringBuilder sb, String replacement)	継続追加置換ステップを実装します。
StringBuffer	appendTail(StringBuffer sb)	終了追加置換ステップを実装します。
StringBuilder	appendTail(StringBuilder sb)	終了追加置換ステップを実装します。
int	end()	最後にマッチした文字の後のオフセットを返します。
int	end(int group)	前回のマッチ操作で指定されたグループによって前方参照された部分シーケンスの、最終文字の後のオフセットを返します。
int	end(String name)	前回のマッチ操作で、指定された名前付きの前方参照を行う正規表現グループによって前方参照された部分シーケンスの、最後の文字の後のオフセットを返します。
boolean	find()	入力シーケンスからこのパターンとマッチする次の部分シーケンスを検索します。
boolean	find(int start)	このマッチャをリセットし、指定されたインデックス以降の入力シーケンスから、このパターンとマッチする次の部分シーケンスを検索します。
String	group()	前回のマッチで一致した入力部分シーケンスを返します。
String	group(int group)	前回のマッチ操作で指定されたグループによって前方参照された入力部分シーケンスを返します。
String	group(String name)	前回のマッチ操作で指定された名前付きの前方参照を行うグループによって前方参照された入力部分シーケンスを返します。
int	groupCount()	このマッチャのパターンに指定されている前方参照を行う正規表現グループの数を返します。
boolean	hasAnchoringBounds()	このマッチャの領域境界のアンカー設定を問い合わせるクエリーを出します。
boolean	hasMatch()	thisに以前の一致または検索操作からの有効な一致が含まれているかどうかを返します。
boolean	hasTransparentBounds()	このマッチャの領域境界の透明度を問い合わせるクエリーを出します。
boolean	hitEnd()	この正規検索エンジンが実行した最後のマッチ操作で、入力の末尾が検索エンジンによりヒットした場合に、trueを返します。
boolean	lookingAt()	入力シーケンスとパターンとのマッチを、領域の先頭から始めます。
boolean	matches()	領域全体をこのパターンとマッチします。
Map<String,Integer>	namedGroups()	キャプチャリング・グループ名からグループ番号への変更不可能なマップを返します。
Pattern	pattern()	このマッチャによって解釈されるパターンを返します。
static String	quoteReplacement(String s)	指定されたStringのリテラル置換Stringを返します。
Matcher	region(int start, int end)	正規検索エンジンの領域に制限を設定します。
int	regionEnd()	この正規検索エンジンの領域の終了インデックス(その値を含まない)をレポートします。
int	regionStart()	この正規検索エンジンの領域の開始インデックスをレポートします。
String	replaceAll(String replacement)	パターンとマッチする入力シーケンスの部分シーケンスを、指定された置換文字列に置き換えます。
String	replaceAll(Function<MatchResult,String> replacer)	パターンに一致する入力シーケンスのすべてのサブシーケンスを、そのサブシーケンスに対応するこのマッチャの一致結果に、指定された置換関数を適用した結果に置き換えます。
String	replaceFirst(String replacement)	パターンとマッチする入力シーケンスの部分シーケンスのうち、最初の部分シーケンスを指定された置換文字列に置き換えます。
String	replaceFirst(Function<MatchResult,String> replacer)	パターンに一致する入力シーケンスの最初のサブシーケンスを、そのサブシーケンスに対応するこのマッチャの一致結果に、指定された置換関数を適用した結果に置き換えます。
boolean	requireEnd()	より多くの入力で正のマッチが負のマッチに変更される可能性がある場合に、trueを返します。
Matcher	reset()	このマッチャをリセットします。
Matcher	reset(CharSequence input)	新しい入力シーケンスを使用してこのマッチャをリセットします。
Stream<MatchResult>	results()	パターンに一致する入力シーケンスの各サブシーケンスの一致結果のストリームを返します。
int	start()	前回のマッチの開始インデックスを返します。
int	start(int group)	前回のマッチ操作で指定されたグループによって前方参照された部分シーケンスの、開始インデックスを返します。
int	start(String name)	前回のマッチ操作で指定された名前付き前方参照グループによって前方参照された部分シーケンスの開始インデックスを返します。
MatchResult	toMatchResult()	このマッチャのマッチ状態をMatchResultとして返します。
String	toString()	このマッチャの文字列表現を返します。
Matcher	useAnchoringBounds(boolean b)	このマッチャの領域境界のアンカーを設定します。
Matcher	usePattern(Pattern newPattern)	このMatcherが一致の検索に使用するPatternを変更します。
Matcher	useTransparentBounds(boolean b)	このマッチャの領域境界の透明度を設定します。

クラスjava.lang.Objectで宣言されたメソッド

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

メソッドの詳細

pattern

public Pattern pattern()

このマッチャによって解釈されるパターンを返します。

戻り値:

このマッチャの作成対象となったパターン

toMatchResult

public MatchResult toMatchResult()

このマッチャのマッチ状態をMatchResultとして返します。 結果は、この正規検索エンジンに対する後続の操作の影響を受けません。

戻り値:

この正規検索エンジンの状態を保持するMatchResult

導入されたバージョン:

1.5

usePattern

public Matcher usePattern(Pattern newPattern)

このMatcherが一致の検索に使用するPatternを変更します。

このメソッドを使用すると、最後に発生したマッチのグループに関する情報がこのマッチャから失われます。 入力内のマッチャの位置は維持され、最後の追加位置は影響を受けません。

パラメータ:

newPattern - このマッチャが使用する新規パターン

戻り値:

このマッチャ

例外:

IllegalArgumentException - newPatternがnullの場合

導入されたバージョン:

1.5

reset

public Matcher reset()

このマッチャをリセットします。

正規検索エンジンをリセットすると、明示的な状態情報すべてが破棄され、追加位置がゼロに設定されます。 正規検索エンジンの領域は、デフォルトである文字シーケンス全体に設定されます。 このマッチャの領域境界のアンカーおよび透明度は影響を受けません。

戻り値:

このマッチャ

reset

public Matcher reset(CharSequence input)

新しい入力シーケンスを使用してこのマッチャをリセットします。

正規検索エンジンをリセットすると、明示的な状態情報すべてが破棄され、追加位置がゼロに設定されます。 正規検索エンジンの領域は、デフォルトである文字シーケンス全体に設定されます。 このマッチャの領域境界のアンカーおよび透明度は影響を受けません。

パラメータ:

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

戻り値:

このマッチャ

start

public int start()

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

定義:

start、インタフェースMatchResult

戻り値:

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

例外:

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

start

public int start(int group)

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

前方参照を行う正規表現グループは、左から右に1からインデックス付けされます。 グループ0はパターン全体を示すため、式m.start(0)はm.start()と同等です。

定義:

start、インタフェースMatchResult

パラメータ:

group - このマッチャのパターンのキャプチャリング・グループのインデックス

戻り値:

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

例外:

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

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

start

public int start(String name)

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

定義:

start、インタフェースMatchResult

パラメータ:

name - このマッチャのパターンの名前付きキャプチャリング・グループの名前

戻り値:

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

例外:

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

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

導入されたバージョン:

1.8

end

public int end()

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

定義:

end、インタフェースMatchResult

戻り値:

最後にマッチした文字の後のオフセット

例外:

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

end

public int end(int group)

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

前方参照を行う正規表現グループは、左から右に1からインデックス付けされます。 グループ0はパターン全体を示すため、式m.end(0)はm.end()と同等です。

定義:

end、インタフェースMatchResult

パラメータ:

group - このマッチャのパターンのキャプチャリング・グループのインデックス

戻り値:

グループによって前方参照された最後の文字の後のオフセット。マッチは成功したがグループ自体はどの部分にもマッチしなかった場合は-1

例外:

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

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

end

public int end(String name)

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

定義:

end、インタフェースMatchResult

パラメータ:

name - このマッチャのパターンの名前付きキャプチャリング・グループの名前

戻り値:

グループによって前方参照された最後の文字の後のオフセット。マッチは成功したがグループ自体はどの部分にもマッチしなかった場合は-1

例外:

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

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

導入されたバージョン:

1.8

group

public String group()

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

入力シーケンスがsのマッチャmの場合、式m.group()およびs.substring( m. start(), m. end())は同等です。

a*などの一部のパターンが空の文字列と一致することに注意してください。 これらのパターンが入力シーケンス内の空の文字列とマッチした場合、空の文字列が返されます。

定義:

group、インタフェースMatchResult

戻り値:

以前の一致したマッチャがPatternを変更したが、まだ新しい一致が試行されていない場合に、文字列形式の (おそらく空の)サブシーケンスまたはnullで一致した

例外:

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、インタフェースMatchResult

パラメータ:

group - このマッチャのパターンのキャプチャリング・グループのインデックス

戻り値:

前回の一致中にグループによって取得された(おそらく空の)部分列、またはグループが入力の一部の一致に失敗した場合、または一致が成功した後でマッチャのPatternが変更されたが、新しい一致が試行されなかった場合のnull

例外:

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

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

group

public String group(String name)

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

一致が成功したが、指定されたグループが入力順序の任意の部分に一致しなかった場合、nullが返されます。 (a*)などの一部のグループは、空の文字列と一致することに注意してください。 これらのグループが入力シーケンス内の空の文字列とマッチした場合、空の文字列が返されます。

定義:

group、インタフェースMatchResult

パラメータ:

name - このマッチャのパターンの名前付きキャプチャリング・グループの名前

戻り値:

前回の一致時に名前付きグループによって取得された(おそらく空の)部分列、またはグループが入力の一部の一致に失敗した場合はnull

例外:

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

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

導入されたバージョン:

1.7

groupCount

public int groupCount()

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

グループ0はパターン全体を表します。 これは、このカウントに含まれません。

グループ・インデックスがこのメソッドから返された値以下の正の整数である場合は、このマッチャで有効です。

定義:

groupCount、インタフェースMatchResult

戻り値:

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

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()メソッドの呼出しは、この一致で一致しない最初の文字から始まります。

パラメータ:

start - マッチの検索を開始するインデックス

戻り値:

指定された索引で始まる入力順序のサブシーケンスがこのマッチャのパターンと一致する場合のみ、true

例外:

IndexOutOfBoundsException - startがゼロより小さい場合、またはstartが入力シーケンスの長さより大きい場合。

lookingAt

public boolean lookingAt()

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

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

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

戻り値:

入力シーケンスのプレフィクスがこのマッチャのパターンと一致する場合のみ、true

quoteReplacement

public static String quoteReplacement(String s)

指定されたStringのリテラル置換Stringを返します。 このメソッドは、MatcherクラスのappendReplacementメソッド内のリテラル置換sとして機能するStringを生成します。 生成されるStringは、リテラル・シーケンスとして処理されるs内の文字シーケンスにマッチします。 スラッシュ('\')およびドル記号('$')には特別な意味はありません。

パラメータ:

s - リテラル化する文字列

戻り値:

リテラル文字列置換

導入されたバージョン:

1.5

appendReplacement

public Matcher appendReplacement(StringBuffer sb, String replacement)

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

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

1. 追加位置以降の入力シーケンスから文字列を読み込み、指定された文字列バッファに追加する。 これは、前回の一致の前の最後の文字、つまり、索引start() - 1の文字を読み取ると停止します。

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

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

置換文字列には、前回の一致時に取得されたサブシーケンスへの参照が含まれる場合があります: ${name}または$gの各出現箇所は、対応するgroup(name)またはgroup(g)をそれぞれ評価した結果に置き換えられます。 $ gの場合、$の後の最初の数値は常にグループ参照の一部として処理されます。 後続の数値が正当なグループ参照を構成する場合、これらは g に組み込まれます。 数 0 - 9 だけが、グループ参照の潜在的なコンポーネントと見なされます。 たとえば、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();
 while (m.find()) {
     m.appendReplacement(sb, "dog");
 }
 m.appendTail(sb);
 System.out.println(sb.toString());

パラメータ:

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

replacement - 置換文字列

戻り値:

このマッチャ

例外:

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

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

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

appendReplacement

public Matcher appendReplacement(StringBuilder sb, String replacement)

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

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

1. 入力シーケンスから文字を読み取り、追加位置から開始して、指定された文字列ビルダーに追加します。 これは、前回の一致の前の最後の文字、つまり、索引start() - 1の文字を読み取ると停止します。

2. 指定された置換文字列を文字列ビルダーに追加します。

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

置換文字列には、前回の一致時に取得されたサブシーケンスへの参照が含まれる場合があります: $ gが出現するたびに、group( g )が評価された結果に置き換えられます。 $の後の最初の数値は、常にグループ参照の一部として処理されます。 後続の数値が正当なグループ参照を構成する場合、これらは g に組み込まれます。 数 0 - 9 だけが、グループ参照の潜在的なコンポーネントと見なされます。 たとえば、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");
 StringBuilder sb = new StringBuilder();
 while (m.find()) {
     m.appendReplacement(sb, "dog");
 }
 m.appendTail(sb);
 System.out.println(sb.toString());

パラメータ:

sb - ターゲット文字列ビルダー

replacement - 置換文字列

戻り値:

このマッチャ

例外:

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

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

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

導入されたバージョン:

9

appendTail

public StringBuffer appendTail(StringBuffer sb)

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

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

パラメータ:

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

戻り値:

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

appendTail

public StringBuilder appendTail(StringBuilder sb)

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

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

パラメータ:

sb - ターゲット文字列ビルダー

戻り値:

ターゲット文字列ビルダー

導入されたバージョン:

9

replaceAll

public String replaceAll(String replacement)

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

このメソッドはまず、このマッチャをリセットします。 次に、入力シーケンスを走査して、パターンとマッチする文字列を検索します。 パターンとマッチしない文字列は、結果文字列に直接追加されます。パターンとマッチした文字列は、置換文字列に置換されて結果に追加されます。 置換文字列には、appendReplacementメソッドのように、前方参照された部分シーケンスへの参照を含めることができます。

置換文字列のバックスラッシュ(\)およびドル記号($)によって、結果がリテラル置換文字列として扱われていた場合と異なる場合があります。 ドル記号は、先に説明したとおり、前方参照された部分シーケンスへの参照として処理される場合があり、バックスラッシュは置換文字列内のリテラル文字をエスケープするのに使用されます。

正規表現a*b、入力"aabfooaabfooabfoob"および置換文字列"-"を指定すると、その式のマッチャでこのメソッドを呼び出すと、文字列"-foo-foo-foo-"が生成されます。

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

パラメータ:

replacement - 置換文字列

戻り値:

マッチしたすべての部分シーケンスを置換文字列で置き換え、前方参照された部分シーケンスを必要に応じて置換することによって構築された文字列

replaceAll

public String replaceAll(Function<MatchResult,String> replacer)

パターンに一致する入力シーケンスのすべてのサブシーケンスを、そのサブシーケンスに対応するこのマッチャの一致結果に、指定された置換関数を適用した結果に置き換えます。 関数によってスローされた例外は、呼出し側に中継されます。

このメソッドはまず、このマッチャをリセットします。 次に、入力シーケンスを走査して、パターンとマッチする文字列を検索します。 一致の一部ではない文字は、結果文字列に直接追加されます。結果の各一致は、置換文字列を返すreplacer関数を適用することで置換されます。 各置換文字列には、appendReplacementメソッドのように取得された部分列への参照を含めることができます。

置換文字列に(\)およびドル記号($)をバックスラッシュすると、結果がリテラル置換文字列として扱われる場合と異なる場合があります。 ドル記号は、先に説明したとおり、前方参照された部分シーケンスへの参照として処理される場合があり、バックスラッシュは置換文字列内のリテラル文字をエスケープするのに使用されます。

正規表現dog、入力"zzzdogzzzdogzzz"、および関数mr -> mr.group().toUpperCase()が与えられている場合、その式のマッチャでこのメソッドを呼び出すと、文字列"zzzDOGzzzDOGzzz"が生成されます。

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

交換機能では、交換時にこのマッチャの状態を変更しないでください。 このメソッドは、ベスト・エフォート・ベースで、このような変更が検出された場合にConcurrentModificationExceptionをスローします。

リ・プレース・ファンクションに渡される各一致結果の状態は、リ・プレース・ファンクション・コールの期間中、およびリ・プレース・ファンクションがこのマッチャの状態を変更しない場合にのみ、一定であることが保証されます。

実装上のノート:

この実装では、このマッチャ(MatchResultのインスタンス)にリ・プレース・ファンクションが適用されます。

パラメータ:

replacer - 置換文字列を返すこのマッチャの一致結果に適用される関数。

戻り値:

一致した各サブシーケンスを、一致したサブシーケンスに置換関数を適用した結果に置換して構築された文字列。必要に応じて、取得されたサブシーケンスを置換します。

例外:

NullPointerException - replacer関数がnullの場合

ConcurrentModificationException - ベスト・エフォート・ベースで、replacer関数がこのマッチャの状態を変更したことを検出した場合

導入されたバージョン:

9

results

public Stream<MatchResult> results()

パターンに一致する入力シーケンスの各サブシーケンスの一致結果のストリームを返します。 一致結果は、入力シーケンス内の一致するサブシーケンスと同じ順序で発生します。

それぞれの一致結果はtoMatchResult()のように生成されます。

このメソッドは、このマッチャをリセットしません。 マッチングは、このマッチャのリージョンの先頭にある端末ストリーム操作の開始時に開始されます。または、マッチャがリセットされていない場合は、前の一致によって一致しない最初の文字で開始されます。

ターミナル・ストリーム操作の完了後に、マッチャをさらに照合する操作に使用する場合は、最初にリセットする必要があります。

このマッチャの状態は、返されたストリームのパイプラインの実行中に変更しないでください。 戻されたストリームのソースSpliteratorはfail-fastであり、ベスト・エフォート・ベースで、このような変更が検出された場合はConcurrentModificationExceptionをスローします。

戻り値:

一致結果の順次ストリーム。

導入されたバージョン:

9

replaceFirst

public String replaceFirst(String replacement)

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

このメソッドはまず、このマッチャをリセットします。 次に、入力シーケンスを走査して、パターンとマッチする最初の文字列を検索します。 パターンとマッチしない文字列は、結果文字列に直接追加されます。パターンとマッチした文字列は、置換文字列に置換されて結果に追加されます。 置換文字列には、appendReplacementメソッドのように、前方参照された部分シーケンスへの参照を含めることができます。

置換文字列のバックスラッシュ(\)およびドル記号($)によって、結果がリテラル置換文字列として扱われていた場合と異なる場合があります。 ドル記号は、先に説明したとおり、前方参照された部分シーケンスへの参照として処理される場合があり、バックスラッシュは置換文字列内のリテラル文字をエスケープするのに使用されます。

正規表現dog、入力"zzzdogzzzdogzzz"および置換文字列"cat"を指定すると、その式のマッチャでこのメソッドを呼び出すと、文字列"zzzcatzzzdogzzz"が生成されます。

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

パラメータ:

replacement - 置換文字列

戻り値:

最初にマッチした部分シーケンスを置換文字列で置き換え、前方参照された部分シーケンスを必要に応じて置換することによって構築された文字列

replaceFirst

public String replaceFirst(Function<MatchResult,String> replacer)

パターンに一致する入力シーケンスの最初のサブシーケンスを、そのサブシーケンスに対応するこのマッチャの一致結果に、指定された置換関数を適用した結果に置き換えます。 replace関数によってスローされた例外は、コール元にリレーされます。

このメソッドはまず、このマッチャをリセットします。 次に、入力シーケンスを走査して、パターンとマッチする最初の文字列を検索します。 一致の一部ではない文字は、結果文字列に直接追加されます。その結果、一致は置換文字列を返すreplacer関数を適用することで置き換えられます。 置換文字列には、appendReplacementメソッドのように、前方参照された部分シーケンスへの参照を含めることができます。

置換文字列のバックスラッシュ(\)およびドル記号($)によって、結果がリテラル置換文字列として扱われていた場合と異なる場合があります。 ドル記号は、先に説明したとおり、前方参照された部分シーケンスへの参照として処理される場合があり、バックスラッシュは置換文字列内のリテラル文字をエスケープするのに使用されます。

正規表現dog、入力"zzzdogzzzdogzzz"、および関数mr -> mr.group().toUpperCase()が与えられている場合、その式のマッチャでこのメソッドを呼び出すと、文字列"zzzDOGzzzdogzzz"が生成されます。

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

交換機能では、交換時にこのマッチャの状態を変更しないでください。 このメソッドは、ベスト・エフォート・ベースで、このような変更が検出された場合にConcurrentModificationExceptionをスローします。

リ・プレース・ファンクションに渡される一致結果の状態は、リ・プレース・ファンクション・コールの間、およびリ・プレース・ファンクションがこのマッチャの状態を変更しない場合にのみ、一定であることが保証されます。

実装上のノート:

この実装では、このマッチャ(MatchResultのインスタンス)にリ・プレース・ファンクションが適用されます。

パラメータ:

replacer - 置換文字列を返すこのマッチャの一致結果に適用される関数。

戻り値:

最初の一致するサブシーケンスを、一致したサブシーケンスに置換関数を適用した結果に置き換えることによって構築された文字列。必要に応じて、取得されたサブシーケンスを置換します。

例外:

NullPointerException - replacer関数がnullの場合

ConcurrentModificationException - ベスト・エフォート・ベースで、replacer関数がこのマッチャの状態を変更したことを検出した場合

導入されたバージョン:

9

region

public Matcher region(int start, int end)

正規検索エンジンの領域に制限を設定します。 領域は、マッチの検索対象となる入力シーケンスの一部です。 このメソッドを呼び出すと、正規検索エンジンがリセットされ、領域の先頭がstartパラメータにより指定されたインデックスに、領域の末尾がendパラメータにより指定されたインデックスにそれぞれ設定されます。

使用される透明度とアンカー設定によっては(useTransparentBoundsおよびuseAnchoringBoundsを参照)、アンカーなどの特定の作成上の振る舞いが領域の境界またはその付近で異なる場合があります。

パラメータ:

start - 検索を開始する位置のインデックス(その値も含む)

end - 検索を終了する位置のインデックス(その値を含まない)

戻り値:

このマッチャ

例外:

IndexOutOfBoundsException - startまたはendがゼロより小さい場合、startが入力シーケンスの長さより大きい場合、endが入力シーケンスの長さより大きい場合、またはstartがendより大きい場合。

導入されたバージョン:

1.5

regionStart

public int regionStart()

この正規検索エンジンの領域の開始インデックスをレポートします。 このマッチャが行う検索は、regionStart (その値も含む)とregionEnd (その値を含まない)の内部でのマッチ検索に制限されます。

戻り値:

この正規検索エンジンの領域の始点

導入されたバージョン:

1.5

regionEnd

public int regionEnd()

この正規検索エンジンの領域の終了インデックス(その値を含まない)をレポートします。 このマッチャが行う検索は、regionStart (その値も含む)とregionEnd (その値を含まない)の内部でのマッチ検索に制限されます。

戻り値:

このマッチャの領域の終点

導入されたバージョン:

1.5

hasTransparentBounds

public boolean hasTransparentBounds()

このマッチャの領域境界の透明度を問い合わせるクエリーを出します。

このメソッドは、このマッチャがtransparent境界を使用する場合はtrueを返し、opaque境界を使用する場合はfalseを返します。

透明または不透明の境界の詳細については、useTransparentBoundsを参照してください。

デフォルトでは、マッチャは不透明の領域境界を使用します。

戻り値:

このマッチャが透明境界を使用している場合はtrue、それ以外の場合はfalse。

導入されたバージョン:

1.5

関連項目:

• useTransparentBounds(boolean)

useTransparentBounds

public Matcher useTransparentBounds(boolean b)

このマッチャの領域境界の透明度を設定します。

引数trueを指定してこのメソッドを呼び出すと、このマッチャはtransparent境界を使用するように設定されます。 ブール引数がfalseの場合、opaque境界が使用されます。

透明な境界を使用する場合、このマッチャの領域は、前方、後方、および境界のマッチング作成で透明になります。 これらの作成は、マッチが適切かどうかを領域の境界を超えて見ることができます。

不透明な境界を使用すると、このマッチャの境界は、前方、後方、および境界を超えて検索を試みるマッチング作成で不透明となります。 これらの作成では境界を以前にさかのぼって検索できないため、領域外ではどのようなマッチングも失敗します。

デフォルトでは、マッチャは不透明の境界を使用します。

パラメータ:

b - 不透明または透明の領域のどちらを使用するかを示すboolean

戻り値:

このマッチャ

導入されたバージョン:

1.5

関連項目:

• hasTransparentBounds()

hasAnchoringBounds

public boolean hasAnchoringBounds()

このマッチャの領域境界のアンカー設定を問い合わせるクエリーを出します。

このメソッドは、このマッチャが「アンカー」境界を使用する場合はtrueを返し、それ以外の場合はfalseを返します。

アンカー設定境界の詳細については、useAnchoringBoundsを参照してください。

デフォルトでは、マッチャはアンカー設定領域境界を使用します。

戻り値:

このマッチャがアンカー境界を使用している場合はtrue、それ以外の場合はfalse。

導入されたバージョン:

1.5

関連項目:

• useAnchoringBounds(boolean)

useAnchoringBounds

public Matcher useAnchoringBounds(boolean b)

このマッチャの領域境界のアンカーを設定します。

引数trueを指定してこのメソッドを呼び出すと、このマッチャは「アンカー」境界を使用するように設定されます。 ブール引数がfalseの場合、non-anchoring境界が使用されます。

アンカー設定境界が使用されると、このマッチャの領域の境界は、^および$などのアンカーにマッチします。

アンカー設定境界が使用されない場合は、このマッチャの領域の境界は、^および$などのアンカーにマッチしません。

デフォルトでは、マッチャはアンカー設定領域境界を使用します。

パラメータ:

b - アンカー設定境界を使用するかどうかを示すboolean。

戻り値:

このマッチャ

導入されたバージョン:

1.5

関連項目:

• hasAnchoringBounds()

toString

public String toString()

このマッチャの文字列表現を返します。 Matcherの文字列表現には、デバッグに有用な情報が含まれます。 厳密な書式は指定されません。

オーバーライド:

toString、クラスObject

戻り値:

この正規検索エンジンの文字列表現

導入されたバージョン:

1.5

hitEnd

public boolean hitEnd()

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

このメソッドがtrueを返す場合、入力がさらに多ければ、最後の検索の結果が変更された可能性があります。

戻り値:

入力の末尾が最後のマッチでヒットした場合はtrue、そうでない場合はfalse

導入されたバージョン:

1.5

requireEnd

public boolean requireEnd()

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

このメソッドがtrueを返し、かつマッチが検出された場合、より多くの入力があればマッチが失われた可能性があります。 このメソッドがfalseを返し、かつマッチが検出された場合、より多くの入力があればマッチは変更されるが、失われることはなかった可能性があります。 マッチが検出されなかった場合、requireEndに意味はありません。

戻り値:

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

導入されたバージョン:

1.5

namedGroups

public Map<String,Integer> namedGroups()

キャプチャリング・グループ名からグループ番号への変更不可能なマップを返します。 名前付きグループがない場合は、空のマップを返します。

定義:

インタフェースMatchResult内のnamedGroups

戻り値:

キャプチャリング・グループ名からグループ番号への変更不可能なマップ

導入されたバージョン:

20

hasMatch

public boolean hasMatch()

thisに以前の一致または検索操作からの有効な一致が含まれているかどうかを返します。

定義:

インタフェースMatchResult内のhasMatch

戻り値:

thisに有効な一致が含まれているかどうか

導入されたバージョン:

20