モジュール 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	hasTransparentBounds()	この正規表現エンジンの領域境界の透明度を問い合わせるクエリーを出します。
boolean	hitEnd()	この正規検索エンジンが実行した最後のマッチ操作で、入力の末尾が検索エンジンによりヒットした場合に、trueを返します。
boolean	lookingAt()	入力シーケンスとパターンとのマッチを、領域の先頭から始めます。
boolean	matches()	領域全体をこのパターンとマッチします。
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)

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

パラメータ:

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)

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

パラメータ:

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

戻り値:

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

例外:

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

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

導入されたバージョン:

1.8

group

public String group()

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

入力シーケンスsのマッチャmの場合、m.group()とs.substring(m.start(), m. end())は同じ表現です。

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

定義:

group、インタフェース: MatchResult

戻り値:

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

例外:

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

戻り値:

前回のマッチ時にグループによって前方参照された部分シーケンス(空の場合もある)。グループが入力の一部へのマッチに失敗した場合はnull

例外:

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

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

group

public String group(String name)

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

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

パラメータ:

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)

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

このメソッドはまず、この正規表現エンジンをリセットします。 次に、入力シーケンスを走査して、パターンとマッチする文字列を検索します。 一致の一部ではない文字は、結果文字列に直接追加されます。それぞれの一致は、置換文字列を返す置換関数を適用することによって結果に置き換えられます。 各置換文字列には、appendReplacementメソッドのように、取得されたサブシーケンスへの参照が含まれる場合があります。

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

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

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

replacer関数は、置換の間にこの正規表現子の状態を変更すべきではありません。 このメソッドは、ベスト・エフォート・ベースで、そのような変更が検出された場合にConcurrentModificationExceptionをスローします。

replacer関数に渡されたそれぞれの一致結果の状態は、replacer関数呼び出しの間だけ、そしてreplacer関数がこのmatcher状態を変更しない場合に限り、一定であることが保証されます。

実装上のノート:

この実装は、MatchResultのインスタンスであるこのマッチャに置換関数を適用します。

パラメータ:

replacer - 置換文字列を返すこの照合元の照合結果に適用される関数。

戻り値:

一致した各サブシーケンスを、その一致したサブシーケンスに置換関数を適用した結果で置換し、必要に応じて取得したサブシーケンスを置換した文字列。

例外:

NullPointerException - replacer関数がnullの場合

ConcurrentModificationException - ベスト・エフォート・ベースで、置換機能がこのマッチャ状態を変更したことが検出された場合

導入されたバージョン:

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関数によってスローされた例外は、呼び出し元に中継されます。

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

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

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

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

replacer関数は、置換の間にこの正規表現子の状態を変更すべきではありません。 このメソッドは、ベスト・エフォート・ベースで、そのような変更が検出された場合にConcurrentModificationExceptionをスローします。

replacer関数に渡された一致結果の状態は、replacer関数呼び出しの間のみ、そしてreplacer関数がこのmatcher状態を変更しない場合に限り、一定であることが保証されます。

実装上のノート:

この実装は、MatchResultのインスタンスであるこのマッチャに置換関数を適用します。

パラメータ:

replacer - 置換文字列を返すこの照合元の照合結果に適用される関数。

戻り値:

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

例外:

NullPointerException - replacer関数がnullの場合

ConcurrentModificationException - ベスト・エフォート・ベースで、置換機能がこのマッチャ状態を変更したことが検出された場合

導入されたバージョン:

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の引数を指定して呼び出すと、透明な境界がこの正規表現エンジンで使用されます。 boolean引数がfalseの場合は、不透明な境界が使用されます。

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

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

デフォルトでは、正規表現エンジンは不透明の境界を使用します。

パラメータ:

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の引数を指定して呼び出すと、アンカー設定境界がこの正規表現エンジンで使用されます。 boolean引数がfalseの場合は、アンカー設定されない境界が使用されます。

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

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

デフォルトでは、正規表現エンジンはアンカー設定領域境界を使用します。

パラメータ:

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