REGEXP_REPLACE 純量函數
REGEXP_REPLACE 純量函數會傳回來源字串的修改版本,其中在來源字串中找到的正規表示式型樣的出現項目會取代為指定的取代字串。
綱目是 SYSIBM。
- source-string
- 指定要在其中進行搜尋之字串的表示式。 此表示式必須傳回內建字串、圖形字串、數值、 布林值 或日期時間值。 在評估函數之前,會將數值、布林 或日期時間值隱含地強制轉型為 VARCHAR。 字串不能指定 FOR BIT DATA 屬性 (SQLSTATE 42815)。 pattern-expression
- 指定正規表示式字串的表示式,此字串是搜尋的型樣。 此表示式必須傳回內建字串、圖形字串、數值、 布林值 或日期時間值。 在評估函數之前,會將數值、布林 或日期時間值隱含地強制轉型為 VARCHAR。 CLOB 或 DBCLOB 表示式的長度不得大於 VARCHAR 或 VARGRAPHIC 資料類型的長度上限。 字串不能指定 FOR BIT DATA 屬性 (SQLSTATE 42815)。 replacement-string
- 指定相符子字串的取代字串的表示式。 表示式必須傳回內建字串、圖形字串、數值、 布林值 或日期時間值的值。 在評估函數之前,會將數值、布林 或日期時間值隱含地強制轉型為 VARCHAR。 字串不能指定 FOR BIT DATA 屬性 (SQLSTATE 42815)。 預設取代字串是空字串。
取代字串的內容可以包括參照,以從搜尋中擷取要在取代文字中使用的群組文字。 這些參照的格式為 '$n' 或' \n ' ,其中 n 是擷取群組的號碼, 0 代表符合型樣的整個字串。 n 的值必須在 0-9 範圍內,且不大於型樣中的擷取群組數目 (SQLSTATE 2201V)。 例如,可以使用 '$2' 或 '\2' 來參照在型樣表示式中指定之第二個擷取群組的來源字串中找到的內容。 如果型樣表示式必須包含 '$' 或' \ '字元的文字參照,則該字元前面必須有' /' 字元作為跳出字元 ('\ $' 或' \\ ')。
開始 - 指定 source-string 內要開始搜尋的位置的表示式。 表示式必須傳回內建字串、圖形字串、 布林 或數值。 如果值不是 INTEGER 類型,則在評估函數之前會隱含地強制轉型為 INTEGER。 整數值必須大於或等於 1。 如果指定 OCTETS 且來源字串是圖形資料,則整數值必須是奇數 (SQLSTATE 428GC)。 預設起始值為 1。 請參閱 CODEUNITS16、 CODEUNITS32或 OCTETS 的參數說明,以取得套用至起始位置的字串單元。 出現項目
- 指定要搜尋並取代來源字串內出現的型樣表示式的表示式。 表示式必須傳回內建字串、圖形字串、 布林 或數值。 如果值不是 INTEGER 類型,則在評估函數之前會隱含地強制轉型為 INTEGER。 出現次數值必須大於或等於 0。 預設出現次數值是 0 ,表示會取代來源字串中所有出現的型樣表示式。 旗標
- 指定旗標的表示式,可控制型樣比對的各個層面。 表示式必須傳回未指定 FOR BIT DATA 屬性的內建字串 (SQLSTATE 42815)。 字串可以包含一或多個有效旗標值,且旗標值的組合必須有效 (SQLSTATE 2201T)。 空字串與值 ' c' 相同。 預設旗標值為 'c'。
表 1. 支援的旗標值 旗標值 說明 c 指定比對區分大小寫。 如果未指定 'c' 或' i ' ,則此旗標是預設值。 此值不得與值 'i' 一起指定。 i 指定比對不區分大小寫。 此值不得與值 'c' 一起指定。 m 指定輸入資料可以包含多行。 依預設,型樣中的 '^' 只符合輸入字串的開頭; 型樣中的 ' $' 只符合輸入字串的結尾。 如果設定此旗標,則 "^" 和 "$" 也會在輸入字串內每一行的開頭和結尾相符。 n 指定 '.' 型樣中的字元符合輸入字串中的行終止字元。 依預設, '.' 型樣中的字元不符合行終止字元。 輸入字串中的換行 (carriage-return) 和換行 (line-feed) 配對行為如同單行終止符,符合單一 ""。 在型樣中。 s 指定 '.' 型樣中的字元符合輸入字串中的行終止字元。 此值是 ' n' 值的同義字。 x 指定忽略型樣中的空格字元,除非跳出。 - CODEUNITS16、 CODEUNITS32或 OCTETS
- 指定起始值的字串單位:
- CODEUNITS16 指定以 16 位元 UTF-16 字碼單元來表示起始值。
- CODEUNITS32 指定以 32 位元 UTF-32 字碼單元來表示起始值。 這是預設值。
- OCTETS 指定以位元組表示開始值。
如果字串單位指定為 CODEUNITS16 或 OCTETS ,且來源字串的字串單位是 CODEUNITS32,則會傳回錯誤 (SQLSTATE 428GC)。
如需相關資訊,請參閱 字串中的「內建函數中的字串單位」。
結果
函數的結果是字串。 如果沒有出現要取代的型樣,且沒有引數是空值,則會傳回原始字串。 字串的資料類型與來源字串相同,但 CHAR (變成 VARCHAR) 及 VARGRAPHIC (變成 GRAPHIC) 除外。
使用下列計算,根據來源字串及取代字串的長度屬性來決定結果資料類型的長度屬性:
MIN(MaxTypeLen, LAS+(LAS+1)*LAR)
其中 MaxTypeLen 代表結果資料類型的長度上限屬性, LAS 代表來源字串資料類型的長度屬性, LAR 代表取代字串資料類型的長度屬性。 如果未指定取代字串,則 LAR 的值為 0。 如果結果字串的實際長度超出傳回資料類型的上限,則會傳回錯誤 (SQLSTATE 54006)。如果 REGEXP_REPLACE 函數的任何引數可以是空值,則結果可以是空值。 如果任何引數是空值,則結果是空值。
注意事項
- 正規表示式處理是使用 International Components for Unicode (ICU) 正規表示式介面來完成。
- 非 Unicode 資料庫的考量:
- 正規表示式型樣只支援半寬控制字元; 在型樣表示式引數中使用字串資料類型。 即使將圖形字串資料類型用於來源字串引數,也可以將字串資料類型用於型樣表示式引數。
- 如果型樣表示式引數是圖形字串資料類型,則來源字串引數必須是圖形字串資料類型。
- 來源字串和取代字串引數必須都是字串資料類型,或都是圖形字串資料類型。
範例
使用區分大小寫的搜尋,將型樣 'R.d' 的第二個出現項目取代為 'Orange'。
SELECT REGEXP_REPLACE(
'Red Yellow RED Blue Red Green Blue', 'R.d','Orange',1,2,'c')
FROM sysibm.sysdummy1
結果是 '紅色黃色紅色藍色橙色綠色藍色'。