LOCATE_IN_STRING スカラー関数

LOCATE_IN_STRING 関数は、あるストリング (source-string、ソース・ストリングと呼ばれる) の中の、別のストリング (search-string、検索ストリングと呼ばれる) の開始位置を戻します。

構文図を読む構文図をスキップするLOCATE_IN_STRING(source-string ,search-string ,start,instance ,CODEUNITS16CODEUNITS32OCTETS )

スキーマは SYSIBM です。

search-string が見つからず、どちらの引数も NULL でない場合、結果はゼロになります。 search-string が見つかった場合、結果は 1 から source-string の実際の長さまでの数値になります。 検索には、データベースの照合が使用されます。ただし、 search-string または source-string がバイナリー・ストリングまたは FOR BIT DATA で定義されている場合は除きます。その場合は、バイナリー比較によって検索が行われます。

オプションの start が指定されている場合、それは、source-string 中での検索が開始される文字位置を示します。 start が指定されている場合は、インスタンスの出現回数も指定できます。instance 引数は、source-string 中の search-string のうち、出現回数が指定した値となるものの位置を特定するために使用されます。 オプションのストリング単位は、start と関数の結果がどの単位で表現されるかを表すために指定できます。

search-string の長さが 0 の場合、関数によって戻される結果は 1 です。source-string の長さが 0 の場合、関数によって戻される結果は 0 です。 そのどちらでもない場合で、search-string 値が、source-string 値の中に隣接して位置する同じ長さのサブストリングと等しい場合、関数によって戻される結果は、source-string 値内のその最初のサブストリングの開始位置になります。その他の場合、関数によって戻される結果は 0 です。

source-string
その中で検索が行われるストリングを指定する式。 この式は、組み込みデータ・タイプであるストリング、数値、ブール、日時のいずれかの値を返す必要があります。 値がストリング・データ・タイプでない場合、その値は関数を評価する前に 暗黙的に VARCHAR にキャストされます。この式は、以下のいずれかによって指定できます。
  • 定数
  • 特殊レジスター
  • グローバル変数
  • ホスト変数 (LOB ロケーター変数またはファイル参照変数を含む)
  • スカラー関数
  • ラージ・オブジェクトのロケーター
  • 列名
  • 上記のいずれかを (CONCAT または || を使用して) 連結する式
search-string
検索の対象となるストリングを指定する式。 この式は組み込み CHAR、VARCHAR、GRAPHIC、VARGRAPHIC、バイナリー・ストリング、数値、ブール値、または日時のいずれかのデータ・タイプの値を返す必要があります。値が CHAR、VARCHAR、GRAPHIC、VARGRAPHIC、またはバイナリー・ストリングのデータ・タイプではない場合、その値は関数を評価する前に暗黙的に VARCHAR にキャストされます。
この式は、以下のいずれかのエレメントによって指定できます。
  • 定数
  • 特殊レジスター
  • グローバル変数
  • ホスト変数
  • 上記のいずれかを引数とするスカラー関数
  • 上記のいずれかを (CONCAT または || を使用して) 連結する式
LOB ファイル参照変数でこの式を指定することはできません。
start
一致検索が開始される source-string 内の位置を指定する式。 式は組み込み数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。 値がタイプ INTEGER でない場合、 その値は関数を評価する前に暗黙的に INTEGER にキャストされます。

INTEGER の値が 0 より大きい場合、検索は start の位置から開始され、ストリングの末尾にいたるまで各位置で実行されます。INTEGER の値が 0 より小さい場合、検索は LENGTH (source-string) + start + 1 の位置から開始され、ストリングの先頭にいたるまで、各位置で実行されます。

start が指定されていない場合のデフォルトは 1 です。OCTETS が指定され、source-string がグラフィック・データである場合、整数の値は奇数でなければなりません (SQLSTATE 428GC)。 整数の値がゼロの場合、エラーが戻されます (SQLSTATE 42815)。

instance
source-string 内で検索する search-string のインスタンスを指定する式。式は組み込み数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。 値がタイプ INTEGER でない場合、 その値は関数を評価する前に暗黙的に INTEGER にキャストされます。 instance の指定がない場合のデフォルトは 1 です。この INTEGER の値は 1 以上である必要があります (SQLSTATE 42815)。
CODEUNITS16、CODEUNITS32、または OCTETS
start および結果のストリング単位を指定します。 CODEUNITS16 は、start および結果が 16 ビット UTF-16 コード単位で表現されることを指定します。 CODEUNITS32 は、start および結果が 32 ビット UTF-32 コード単位で表現されることを指定します。 OCTETS は、start および結果がバイト単位で表現されることを指定します。

ストリング単位が CODEUNITS16 または CODEUNITS32 と指定され、search-string または source-string がバイナリー・ストリングまたは FOR BIT DATA である場合は、エラーが戻されます (SQLSTATE 428GC)。ストリング単位が CODEUNITS16 または OCTETS として指定されており、source-string のストリング単位が CODEUNITS32 である場合は、エラーが戻されます (SQLSTATE 428GC)。

ストリング単位が明示的に指定されていない場合、および source-string が文字ストリングまたはグラフィック・ストリングである場合、source-string のストリング単位によって、結果と start (指定されている場合) に使用される単位が決まります。それ以外の場合、これらはバイト単位で表されます。

ロケールに依存する UCA ベースの照合がこの関数に使用される場合は、CODEUNITS16 オプションから最も適したパフォーマンスの特性を得られます。

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

1 番目と 2 番目の引数は、互換性のあるストリング・タイプを持たなければなりません。 互換性の詳細については、『ストリング変換についての規則』を参照してください。 Unicode データベースでは、一方のストリング引数が文字で (FOR BIT DATA ではない)、他方のストリング引数が GRAPHIC である場合、search-string は、処理のために source-string のデータ・タイプに変換されます。 一方の引数が文字 FOR BIT DATA である場合、他方の引数は GRAPHIC であってはなりません (SQLSTATE 42846)。

各検索位置で、その検索位置から LENGTH (search-string) - 1 の値だけ右にある位置までの source-string のサブストリングが、search-string と等しい場合に、一致が検出されます。

この関数の結果は長精度整数 (large integer) です。 結果は、source-string 中の search-string のインスタンスの開始位置です。 この値は、start 指定に関わらず、ストリングの開始位置を意味します。引数のいずれかが NULL になる可能性がある場合、結果も NULL になる可能性があります。 引数のいずれかが NULL の場合、その結果は NULL 値です。

LOCATE_IN_STRING の同義語として INSTR を使用できます。

INSTRB スカラー関数は、開始位置と結果がバイト単位で示されることを示す OCTETS を指定した (指定可能な場合) LOCATE_IN_STRING 関数の呼び出しに相当します。

例

  • 例 1: ストリング "Jürgen lives on Hegelstraße" 内の文字 "ß" の位置を、ストリング末尾から検索して特定し、そのストリング内での位置を、CODEUNITS32 単位でホスト変数 POSITION に設定する。
        SET :POSITION = LOCATE_IN_STRING('Jürgen lives on Hegelstraße',
                                    'ß',-1,CODEUNITS32);
    ホスト変数 POSITION の値は 26 に設定されます。
  • 例 2: ストリング "WINNING" 内の文字 "N" が 3 回目に出現する位置を、ストリングの開始位置から検索して特定し、その文字のストリング内での位置を、バイト単位でホスト変数 POSITION に設定する。
        SET :POSITION =
    LOCATE_IN_STRING('WINNING','N',1,3,OCTETS);
    ホスト変数 POSITION の値は 6 に設定されます。