モジュール 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
  • メソッドのサマリー

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

    クラス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()
      領域全体をこのパターンとマッチします。

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

      戻り値:
      リージョン・シーケンス全体がこのマッチャのパターンと一致する場合のみ、true
    • find

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

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

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

      戻り値:
      入力シーケンスのサブシーケンスがこのマッチャのパターンと一致する場合のみ、true
    • find

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

      一致が成功した場合、startendおよびgroupメソッドで詳細を取得でき、後続のfind()メソッドの呼出しは、この一致で一致しない最初の文字から始まります。

      パラメータ:
      start - マッチの検索を開始するインデックス
      戻り値:
      指定された索引で始まる入力順序のサブシーケンスがこのマッチャのパターンと一致する場合のみ、true
      例外:
      IndexOutOfBoundsException - startがゼロより小さい場合、またはstartが入力シーケンスの長さより大きい場合。
    • lookingAt

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

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

      一致が成功した場合は、startendおよび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()のように生成されます。

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

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

      このマッチャの状態は、返されたストリームのパイプラインの実行中に変更しないでください。 戻されたストリームのソースSpliteratorfail-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

      public Matcher useTransparentBounds(boolean b)
      この正規表現エンジンの領域境界の透明度を設定します。

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

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

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

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

      パラメータ:
      b - 不透明または透明の領域のどちらを使用するかを示すboolean
      戻り値:
      この正規表現エンジン
      導入されたバージョン:
      1.5
      関連項目:
    • hasAnchoringBounds

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

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

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

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

      戻り値:
      このマッチャがアンカー境界を使用している場合はtrue、それ以外の場合はfalse
      導入されたバージョン:
      1.5
      関連項目:
    • useAnchoringBounds

      public Matcher useAnchoringBounds(boolean b)
      この正規表現エンジンの領域境界のアンカーを設定します。

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

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

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

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

      パラメータ:
      b - アンカー設定境界を使用するかどうかを示すboolean。
      戻り値:
      この正規表現エンジン
      導入されたバージョン:
      1.5
      関連項目:
    • 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