REGEXP_INSTR スカラー関数

REGEXP_INSTR スカラー関数は、return_option 引数の値に応じて、一致したサブストリングの開始位置または終了位置を戻します。

スキーマは SYSIBM です。

source-string

その中で検索が行われるストリングを指定する式。この式は、組み込みの文字ストリング、グラフィック・ストリング、数値、ブール値、日時値のいずれかを戻す必要があります。数値、ブール値、または日時値は、関数の評価の前に VARCHAR に暗黙的にキャストされます。文字ストリングは、FOR BIT DATA 属性を指定できません (SQLSTATE 42815)。

pattern-expression

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

start

検索が開始される source-string 内の位置を指定する式。この式は、組み込みの文字ストリング、グラフィック・ストリング、ブール値、数値のいずれかを戻す必要があります。INTEGER タイプでない値は、関数の評価の前に INTEGER に暗黙的にキャストされます。整数の値は 1 以上でなければなりません。OCTETS が指定され、ソース・ストリングがグラフィック・データである場合、整数の値は奇数でなければなりません (SQLSTATE 428GC)。start のデフォルト値は 1 です。開始位置に適用されるストリング単位については、CODEUNITS16、CODEUNITS32、または OCTETS のパラメーターに関する説明を参照してください。

occurrence

検索するソース・ストリング内のパターン式の出現個所を指定する式。この式は、組み込みの文字ストリング、グラフィック・ストリング、ブール値、数値のいずれかを戻す必要があります。INTEGER タイプでない値は、関数の評価の前に INTEGER に暗黙的にキャストされます。この値は 1 以上でなければなりません。occurrence のデフォルト値は 1 です。これは、パターン式の 1 番目の出現個所のみが対象になることを表します。

return-option

出現個所の何を戻すかを指定する式。この式は、組み込みの文字ストリング、グラフィック・ストリング、ブール値、数値のいずれかを戻す必要があります。INTEGER タイプでない値は、関数の評価の前に INTEGER に暗黙的にキャストされます。この値は 0 または 1 でなければなりません (SQLSTATE 22546)。

値 0 の場合、出現個所の最初のストリング単位の位置を戻します。
値 1 の場合、出現個所の次のストリング単位の位置を戻します。

return-option のデフォルト値は 0 です。

flags

パターン・マッチングのさまざまな面を制御するフラグを指定する式。この式は、FOR BIT DATA 属性を指定しない組み込み文字ストリングを返す必要があります (SQLSTATE 42815)。 1 つ以上の有効なフラグ値をストリングとして指定できますが、フラグ値の組み合わせが有効でなければなりません (SQLSTATE 2201T)。空ストリングは、値 'c' と同じです。デフォルトのフラグ値は 'c' です。

表 1. サポートされるフラグ値
フラグ値	説明
c	マッチングで大/小文字を区別することを指定します。このフラグは、'c' または 'i' が指定されていない場合のデフォルト値です。この値は、値 'i' と一緒には指定できません。
i	マッチングで大/小文字を区別しないことを指定します。この値は、値 'c' と一緒には指定できません。
m	入力データに複数行含まれている可能性があることを指定します。デフォルトでは、パターン内の「^」は入力ストリングの先頭のみと一致し、パターン内の「$」は入力ストリングの末尾のみと一致します。このフラグを設定すると、「^」と「$」は、入力ストリング内の各行の先頭と末尾とも一致します。
n	パターン内の「.」文字が、入力ストリング内の行終了文字と一致することを指定します。デフォルトでは、パターン内の「.」文字は行終了文字と一致しません。入力ストリング内の復帰と改行のペアが、単一行の終了文字として機能し、パターン内の単一の「.」と一致します。
s	パターン内の「.」文字が、入力ストリング内の行終了文字と一致することを指定します。この値は、値 'n' の同義語です。
x	パターン内の空白文字を、エスケープされていない限り無視することを指定します。

group

返すソース・ストリング内の位置を決定するために使用する、パターン式のキャプチャー・グループを指定する式。この式は、組み込みの文字ストリング、グラフィック・ストリング、ブール値、数値のいずれかを戻す必要があります。INTEGER タイプでない値は、関数の評価の前に INTEGER に暗黙的にキャストされます。この値は、0 以上でなければならず、パターン式のキャプチャー・グループの数を超えてはなりません (SQLSTATE 22546)。 group のデフォルト値は 0 です。これは、パターン全体と一致するストリングに基づいた位置であることを表します。

CODEUNITS16、CODEUNITS32、または OCTETS

start 値と結果の両方のストリング単位を指定します。

CODEUNITS16 は、start 値と結果を 16 ビットの UTF-16 コード単位で表すよう指定します。
CODEUNITS32 は、start 値と結果を 32 ビットの UTF-32 コード単位で表すよう指定します。これはデフォルトです。
OCTETS は、start 値と結果をバイト単位で表すよう指定します。

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

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

結果

この関数の結果は長精度整数 (large integer) です。パターン式が検出された場合、結果は 1 から n までの数値となります。ここで、n はソース・ストリングの実際の長さに 1 を加えた数値です。結果値は、関数の処理に使用されたストリング単位で表記された位置を表します。パターン式が検出されず、いずれの引数も NULL でない場合、結果は 0 です。

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

注

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

例

前に文字が 1 つ付いた 'o' の最初の出現個所を検出します。
```
SELECT REGEXP_INSTR('hello to you', '.o',1,1)
   FROM sysibm.sysdummy1
```
結果は 4 です。これは 2 番目の 'l' 文字の位置です。
前に文字が 1 つ付いた 'o' の 2 番目の出現個所を検出します。
```
SELECT REGEXP_INSTR('hello to you', '.o',1,2) 
   FROM sysibm.sysdummy1
```
結果は 7 です。これは文字 't' の位置です。
大/小文字を区別しないマッチングを使用して、正規表現 '(.o).' の最初のキャプチャー・グループの 3 番目の出現個所の後ろの位置を検出します。
```
SELECT REGEXP_INSTR('hello TO you', '(.o).', 1,3,1,'i',1) 
   FROM sysibm.sysdummy1
```
結果は 12 です。これは、ストリングの末尾にある文字 'u' の位置です。