REPLACE スカラー関数

source-string 内に存在する search-string のすべての出現箇所を replace-string に置き換えます。

スキーマは SYSIBM です。 REPLACE 関数の SYSFUN バージョンは引き続き使用可能です。ただし、データベースの照合に依存しているわけではありません。

検索ストリングがソース・ストリングで見つからない場合、検索ストリングは未変更のまま返されます。ロケールに依存する UCA ベースの照合で Unicode データベースが定義され、かつ source-string、search-string、replace-string の引数がいずれも FOR BIT DATA またはバイナリー・ストリングとして定義されていない場合、言語的に正しい検索が実行されます。それ以外の場合、マルチバイト文字に対して特別な考慮をしないで、バイナリー比較を使用して検索が実行されます。

ソース・ストリング

ソース・ストリングを指定する式。この式は、組み込みの文字ストリング、数値、DBCLOB 値、ブール値、または日時値の値を戻す必要があります。値に応じて以下のようになります。

数値、日時、または CLOB 値の場合、関数の評価の前に VARCHAR に暗黙的にキャストされます。
DBCLOB 値の場合は、関数の評価の前に VARGRAPHIC に暗黙的にキャストされます。

バイナリー・ストリングの実際の長さは、1,048,576 バイト以下でなければなりません (SQLSTATE 42815)。

検索ストリング

ソース・ストリングから除去するストリングを指定する式。この式は、組み込みの文字ストリング、数値、DBCLOB 値、ブール値、または日時値の値を戻す必要があります。値に応じて以下のようになります。

数値、日時、または CLOB 値の場合、関数の評価の前に VARCHAR に暗黙的にキャストされます。
DBCLOB 値の場合は、関数の評価の前に VARGRAPHIC に暗黙的にキャストされます。

バイナリー・ストリングの実際の長さは、1,048,576 バイト以下でなければなりません (SQLSTATE 42815)。

置換ストリング

置き換えストリングを指定する式。この式は、組み込みの文字ストリング、数値、DBCLOB 値、ブール値、または日時値の値を戻す必要があります。値に応じて以下のようになります。

数値、日時、または CLOB 値の場合、関数の評価の前に VARCHAR に暗黙的にキャストされます。
DBCLOB 値の場合は、関数の評価の前に VARGRAPHIC に暗黙的にキャストされます。

バイナリー・ストリングの実際の長さは、1,048,576 バイト以下でなければなりません (SQLSTATE 42815)。式が空ストリングであるか指定されない場合、ソース・ストリングから削除されるストリングは置き換えられません。

この 3 つの引数のデータ・タイプには互換性がなければなりません。

結果

結果のデータ・タイプは引数のデータ・タイプに応じて変わります。

いずれかの引数が BLOB の場合、結果は BLOB です。
引数がバイナリー・ストリングであるが BLOB ではない場合、結果は VARBINARY です。
引数が文字ストリングの場合、結果は VARCHAR です。いずれかの引数が FOR BIT DATA として定義されている場合、結果は FOR BIT DATA として定義されます。
引数がグラフィック・ストリングの場合、結果は VARGRAPHIC です。

Unicode データベースの場合は、引数として文字ストリングとグラフィック・ストリングの両方を使用すると、source-string 引数のストリングのタイプに基づいて結果のデータ・タイプが決まります。 source-string 引数のタイプが文字ストリングであれば、結果のデータ・タイプは VARCHAR になります。 source-string 引数のタイプがグラフィック・ストリングであれば、結果のデータ・タイプは VARGRAPHIC になります。

結果のストリング単位は、source-string のストリング単位です。いずれかの引数を FOR BIT DATA として定義する場合は、その他の引数を CODEUNITS32 のストリング単位で定義することはできません。

結果のストリング単位は、source-string のストリング単位と同じになります。結果の長さ属性は、引数によって異なります。

結果の長さ属性は、以下の場合には (同じストリング単位の) source-string の長さ属性になります。
- replace-string 引数が指定されていないか、空ストリング定数として指定されている場合。
- search-string が定数であり、search-string 定数に含まれるバイト数が以下の値より大きいか等しい場合。
  - 定数 replace-string のバイト数
  - OCTETS 単位の非定数文字ストリング・タイプ replace-string の長さ属性
  - 非定数グラフィック・ストリング・タイプ replace-string の長さ属性の 2 倍 (2 バイト単位)、または CODEUNITS16。
  - CODEUNITS32の非定数 replace-string の長さ属性の 4 倍。
  - 非定数バイナリー・ストリング・タイプ replace-string の長さ属性
それ以外の場合、結果の長さ属性は、結果のデータ・タイプに応じて以下のように計算されます (これにより、最小限の search-string を最大限の replace-string で置き換えることができます)。
- ストリング単位が OCTETS の VARCHAR の場合:
  - L1 < = 4000 であれば、結果の長さ属性は、MIN(4000, (L3*(L1/L2)) + MOD(L1,L2)) になります。
  - そうでなければ、結果の長さ属性は、MIN(32672, (L3*(L1/L2)) + MOD(L1,L2))になります。
- ストリング単位が CODEUNITS32の VARCHAR の場合、結果の長さ属性は MIN(8168, (L3*(L1/L2)) + MOD(L1,L2))になります。
- ストリング単位が 2 バイトまたは CODEUNITS16 の VARGRAPHIC の場合:
  - L1 < = 2000 であれば、結果の長さ属性は、MIN(2000, (L3*(L1/L2)) + MOD(L1,L2)) になります。
  - そうでなければ、結果の長さ属性は、MIN(16336, (L3*(L1/L2)) + MOD(L1,L2))になります。
- ストリング単位が CODEUNITS32の VARGRAPHIC の場合、結果の長さ属性は MIN(8168, (L3*(L1/L2)) + MOD(L1,L2))になります。
- VARBINARY の場合、結果の長さ属性は MIN(32672, (L3*(L1/L2)) + MOD(L1,L2)) になります。
- BLOB の場合、結果の長さ属性は MIN(2G, (L3*(L1/L2)) + MOD(L1,L2)) になります。

これらの L1、L2、および L3 の長さ値については、結果のストリング単位に基づいて以下の表に示しています。

表 1. L1、L2、および L3 の長さ値
結果のストリング単位	L1	L2	L3
OCTETS (文字ストリング)	`source-string` の長さ属性	定数でない場合は 1、それ以外の場合は、文字ストリング・タイプとして表現された定数内の実際のバイト数	`replace-string` が定数の場合、文字ストリング・タイプとして表現された定数内の実際のバイト数 `replace-string` が OCTETS 単位の文字ストリングの場合、`replace-string` の長さ属性 `replace-string` が CODEUNITS32内の文字ストリングまたはグラフィック・ストリングの場合、 `replace-string`の長さ属性の 4 倍。 `replace-string` が 2 バイトまたは CODEUNITS16の GRAPHIC ストリングである場合、 `replace-string`の長さ属性の 3 倍。
CODEUNITS16 または 2 バイト (グラフィック・ストリング)	`source-string` の長さ属性	定数でない場合は 1、それ以外の場合は、グラフィック・ストリング・タイプとして表現された定数内の実際の 2 バイト数または CODEUNITS16 ストリング単位の数	`replace-string` が定数の場合、GRAPHIC ストリング・タイプとして表される、定数内の実際の 2 バイト数または CODEUNITS16 ストリング単位。 `replace-string` が OCTETS の文字ストリング、2 バイトのグラフィック・ストリング、または CODEUNITS16 の場合は、 `replace-string`の長さ属性。 `replace-string` が CODEUNITS32 の文字ストリングまたはグラフィック・ストリングの場合、 `replace-string`の長さ属性の 2 倍。
CODEUNITS32 (文字ストリングまたはグラフィック・ストリング)	`source-string` の長さ属性	定数でない場合は 1、それ以外の場合は、`search-string` の長さ属性	`replace-string` の長さ属性
該当しない (バイナリー・ストリング)	source-string の長さ属性	定数でない場合は 1、それ以外の場合は、バイナリー・ストリング・タイプとして表現された定数内の実際のバイト数	replace-string が定数の場合、バイナリー・ストリング・タイプとして表現された定数内の実際のバイト数 replace-string が FOR BIT DATA のバイナリー・ストリングまたは文字ストリングの場合は、replace-string の長さ属性。

結果が文字ストリングの場合、結果の長さ属性は、結果のストリング単位での VARCHAR データ・タイプの最大長を超えてはなりません。結果がグラフィック・ストリングの場合、結果の長さ属性は、結果のストリング単位での VARGRAPHIC データ・タイプの最大長を超えてはなりません。

結果の実際の長さは、source-string の実際の長さに、 replace-string の実際の長さを source-string に存在する search-string のオカレンス数で乗算した値を加算し、search-string の長さを減算した値になります。結果の実際の長さが結果の長さ属性または 1,048,576 バイトを超えると、エラーが戻されます (SQLSTATE 22001)。

replace-string の実際の長さが戻りデータ・タイプの最大値を超えている場合は、エラーが戻されます。引数のいずれかが NULL になる可能性がある場合、結果も NULL になる可能性があります。引数のいずれかが NULL の場合、その結果は NULL 値です。

例

例 1: 'DINING' という語の文字 'N' のすべてのオカレンスを 'VID' で置き換えます。
```
   VALUES CHAR (REPLACE ('DINING', 'N', 'VID'), 10)
```
結果は 'DIVIDIVIDG' というストリングになります。
例 2: 大/小文字を区別しない照合 CLDR181_LEN_S1 を使用する Unicode データベースで、'QUICK' という語を 'LARGE' という語で置き換えます。
```
VALUES REPLACE ('The quick brown fox', 'QUICK', 'LARGE')
```
結果はストリング 'The LARGE brown fox' になります。