REGEXP_REPLACE スカラー関数

REGEXP_REPLACE スカラー関数は、ソース・ストリング内の正規表現パターンの出現箇所を、指定された置換ストリングに置き換えた変更バージョンのソース・ストリングを戻します。

Read syntax diagramSkip visual syntax diagramREGEXP_REPLACE(source-string ,pattern-expression,replacement-string,start,occurrence,flags ,CODEUNITS32,CODEUNITS16OCTETS )

スキーマは SYSIBM です。

ソース・ストリング
その中で検索が行われるストリングを指定する式。 この式は、組み込みの文字ストリング、グラフィック・ストリング、数値、 ブール値、 または日時値を返す必要があります。 数値、ブール値、 または日時値は、関数が評価される前に暗黙的に VARCHAR にキャストされます。 文字ストリングは、FOR BIT DATA 属性を指定できません (SQLSTATE 42815)。
パターン式
検索するパターンである正規表現ストリングを指定する式。 この式は、組み込みの文字ストリング、グラフィック・ストリング、数値、 ブール値、 または日時値を返す必要があります。 数値、ブール値、 または日時値は、関数が評価される前に暗黙的に VARCHAR にキャストされます。 CLOB または DBCLOB 式の長さは、VARCHAR または VARGRAPHIC データ・タイプの最大長を超えてはなりません。 文字ストリングは、FOR BIT DATA 属性を指定できません (SQLSTATE 42815)。
置換ストリング
一致したサブストリングに対する置き換えストリングを指定する式。 この式は、組み込みの文字ストリング、グラフィック・ストリング、数値、 ブール値、 または日時値の値を戻す必要があります。 数値、ブール値、 または日時値は、関数が評価される前に暗黙的に VARCHAR にキャストされます。 文字ストリングは、FOR BIT DATA 属性を指定できません (SQLSTATE 42815)。 デフォルトの置き換えストリングは、空ストリングです。

置き換えストリングの内容として、検索から得られたキャプチャー・グループ・テキストの参照を含めて置換テキストで使用することができます。 これらの参照は '$n' または '¥n' の形式です。ここで、n はキャプチャー・グループの番号で、0 はパターンと一致するストリング全体を表します。 n の値は、0 から 9 まででなければならず、パターン内のキャプチャー・グループの数を超えてはなりません (SQLSTATE 2201V)。 例えば、'$2' または '¥2' を使用すると、パターン式に指定された 2 番目のキャプチャー・グループがソース・ストリングで検出された箇所の内容を参照できます。 パターン式に '$' または '¥' 文字のリテラル参照を含める必要がある場合は、その文字の前に '/' 文字をエスケープ文字として付ける必要があります ('¥$' または '¥¥')。

start
検索が開始される source-string 内の位置を指定する式。 この式は、組み込みの文字ストリング、グラフィック・ストリング、 ブール値、 または数値を戻す必要があります。 INTEGER タイプでない値は、関数の評価の前に INTEGER に暗黙的にキャストされます。 整数の値は、1 以上でなければなりません。 OCTETS が指定され、ソース・ストリングがグラフィック・データである場合、整数の値は奇数でなければなりません (SQLSTATE 428GC)。 デフォルトの開始値は 1 です。 開始位置に適用されるストリング単位については、CODEUNITS16、CODEUNITS32、または OCTETS のパラメーターの説明を参照してください。
オカレンス (occurrence)
検索して置換する対象となる、ソース・ストリング内のパターン式の出現個所を指定する式。 この式は、組み込みの文字ストリング、グラフィック・ストリング、 ブール値、 または数値を戻す必要があります。 INTEGER タイプでない値は、関数の評価の前に INTEGER に暗黙的にキャストされます。 オカレンス値は 0 以上でなければなりません。 デフォルトのオカレンス値は 0 です。これは、ソース・ストリング内のパターン式のすべてのオカレンスが置換されることを示します。
・フラグ
パターン・マッチングのさまざまな面を制御するフラグを指定する式。 この式は、FOR BIT DATA 属性を指定しない組み込み文字ストリングを返す必要があります (SQLSTATE 42815)。 1 つ以上の有効なフラグ値をストリングとして指定できますが、フラグ値の組み合わせが有効でなければなりません (SQLSTATE 2201T)。 空ストリングは、値 'c' と同じです。 デフォルトのフラグ値は 'c' です。
表 1. サポートされるフラグ値
フラグ値 説明
c マッチングで大/小文字を区別することを指定します。 このフラグは、'c' または 'i' が指定されていない場合のデフォルト値です。 この値は、値 'i' と一緒には指定できません。
i マッチングで大/小文字を区別しないことを指定します。 この値は、値 'c' と一緒には指定できません。
m 入力データに複数行含まれている可能性があることを指定します。 デフォルトでは、パターン内の「^」は入力ストリングの先頭のみと一致し、パターン内の「$」は入力ストリングの末尾のみと一致します。 このフラグを設定すると、「^」と「$」は、入力ストリング内の各行の先頭と末尾とも一致します。
n パターン内の「.」 文字が、入力ストリング内の行終了文字と一致することを指定します。 デフォルトでは、パターン内の「.」 文字は行終了文字と一致しません。 入力ストリング内の復帰と改行のペアが、単一行の終了文字として機能し、パターン内の単一の「.」 と一致します。
s パターン内の「.」 文字が、入力ストリング内の行終了文字と一致することを指定します。 この値は、値 'n' の同義語です。
x パターン内の空白文字を、エスケープされていない限り無視することを指定します。
CODEUNITS16、CODEUNITS32、または OCTETS
start 値のストリング単位を指定します。
  • CODEUNITS16 は、start 値を 16 ビットの UTF-16 コード単位で表すよう指定します。
  • CODEUNITS32 は、start 値を 32 ビットの UTF-32 コード単位で表すよう指定します。 これがデフォルトです。
  • OCTETS は、開始値がバイト単位で表現されることを指定します。

ストリング単位が CODEUNITS16 または OCTETS として指定されており、ソース・ストリングのストリング単位が CODEUNITS32 である場合は、エラーが返されます (SQLSTATE 428GC)。

詳しくは、「 文字ストリング」の「組み込み関数のストリング単位」を参照してください。

結果

関数の結果はストリングです。 置換するパターンが出現せず、どの引数も NULL でない場合、元のストリングが戻されます。 ストリングのデータ・タイプは、ソース・ストリングと同じデータ・タイプになります。ただし例外として、CHAR は VARCHAR に、GRAPHIC は VARGRAPHIC になります。

結果のデータ・タイプの長さ属性は、以下の計算を使用してソース・ストリングと置き換えストリングの長さ属性に基づいて決まります。
   MIN(MaxTypeLen, LAS+(LAS+1)*LAR)
ここで、MaxTypeLen は結果のデータ・タイプの最大長属性を表し、LAS はソース・ストリングのデータ・タイプの長さ属性を表し、LAR は置き換えストリングのデータ・タイプの長さ属性を表します。 置換ストリングが指定されていない場合、LAR の値は 0 です。 結果のストリングの実際の長さが戻りデータ・タイプの最大値を超える場合、エラーが戻されます (SQLSTATE 54006)。

REGEXP_REPLACE 関数の引数のいずれかが NULL になる可能性がある場合、結果も NULL になる可能性があります。 引数のいずれかが NULL の場合、その結果は NULL 値です。

注

  • 正規表現の処理は、International Components for Unicode (ICU) 正規表現インターフェースを使用して実行されます。
  • 非 Unicode データベースに関する考慮事項:
    • 正規表現パターンでは、半角の制御文字のみがサポートされます。パターン式引数には、文字ストリング・データ・タイプを使用してください。 ソース・ストリング引数でグラフィック・ストリング・データ・タイプを使用している場合でも、パターン式引数で文字ストリング・データ・タイプを使用できます。
    • パターン式引数がグラフィック・ストリング・データ・タイプの場合、ソース・ストリング引数はグラフィック・ストリング・データ・タイプでなければなりません。
    • ソース・ストリング引数と置き換えストリング引数は、両方とも文字ストリング・データ・タイプであるか、または両方とも GRAPHIC ストリング・データ・タイプでなければなりません。

例

大/小文字を区別する検索を使用して、パターン 'R.d' の 2 番目の出現個所を 'Orange' に置換します。
SELECT REGEXP_REPLACE(
   'Red Yellow RED Blue Red Green Blue', 'R.d','Orange',1,2,'c') 
      FROM sysibm.sysdummy1
結果は 'Red Yellow RED Blue Orange Green Blue' となります。