IoT Platform：字串函數

STRING CHR(BIGINT ascii)

將指定ASCII碼ascii轉換成字元。

ascii：BIGINT類型的ASCII值。參數範圍是0~255，超過此範圍會引發異常。如果輸入為STRING、DOUBLE或DECIMAL類型，則會隱式轉換為BIGINT類型後參與運算，其它類型會返回異常。

返回STRING類型。如果輸入參數為NULL，則返回NULL。

STRING CONCAT(STRING a, STRING b...)

將參數中的所有字串串連在一起。

輸入參數為STRING類型。如果輸入參數為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。

返回STRING類型。如果沒有參數或者任一參數為NULL，則返回NULL。

CONCAT('ab','c') = 'abc'
CONCAT() = NULL
CONCAT('a', null, 'b') = NULL

STRING GET_JSON_OBJECT(STRING json,STRING path)

用於在一個標準JSON字串中，按照path抽取指定的字串。每次調用該函數時，都會讀一次未經處理資料，因此反覆調用可能浪費效能和費用。您可以通過GET_JSON_OBJECT，結合UDTF，輕鬆轉換JSON格式日誌資料，避免多次調用函數。

• JSON：STRING類型，標準的JSON格式字串。
• path：STRING類型，表示在JSON中的path，以$開頭。path詳情請參見LanguageManual UDF。
  • $：表示根節點。
  • .：表示子節點。
  • []：[number]表示數組下標，數組格式為key[sub1][sub2][sub3]……。
  • *：Wildcard for []，返回整個數組。*不支援轉義。

• 如果JSON為空白或非法的JSON格式，則返回NULL。
• 如果JSON合法，path也存在，則返回對應字串。
• 不支援一個Object中出現相同的Key，例如{a:1, a:0}，可能導致無法解析。
• 不支援Emoji表情字串。

• 樣本1：

  --json內容。
  {"store":
  {"fruit":[{"weight":8,"type":"apple"},{"weight":9,"type":"pear"}],
  "bicycle":{"price":19.95,"color":"red"}
  },
  "email":"amy@only_for_json_udf_test.net",
  "owner":"amy"
  }

  執行如下命令提取JSON對象中的資訊。

  --返回amy。
      GET_JSON_OBJECT(json, '$.owner');
  
  --返回{"weight":8,"type":"apple"}。
      GET_JSON_OBJECT(json, '$.store.fruit\[0]');
  
  --返回NULL。
      GET_JSON_OBJECT(json, '$.non_exist_key');

• 樣本2：

  GET_JSON_OBJECT('{"array":[["aaaa",1111],["bbbb",2222],["cccc",3333]]}','$.array[1][1]')= "2222"
  
  GET_JSON_OBJECT('{"aaa":"bbb","ccc":{"ddd":"eee","fff":"ggg","hhh":["h0","h1","h2"]},"iii":"jjj"}','$.ccc.hhh[*]') = "["h0","h1","h2"]"
  
  GET_JSON_OBJECT('{"aaa":"bbb","ccc":{"ddd":"eee","fff":"ggg","hhh":["h0","h1","h2"]},"iii":"jjj"}','$.ccc.hhh[1]') = "h1"

BIGINT INSTR(STRING str1, STRING str2[, BIGINT start_position[, BIGINT nth_appearance]])

用於計運算元串str2在字串str1中的位置。

• str1：STRING類型，要搜尋的字串。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。
• str2：STRING類型，要搜尋的子串。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。
• start_position：BIGINT類型，其它類型會返回異常。表示從str1的第幾個字元開始搜尋，預設起始位置是第一個字元位置1。
• nth_appearance：BIGINT類型，大於0。表示子串在字串中的第nth_appearance次匹配的位置。如果nth_appearance為其它類型或小於等於0，則返回異常。

• 返回BIGINT類型。
• 如果在str1中未找到str2，則返回0。
• 如果任一輸入參數為NULL，則返回NULL。
• 如果str2為空白串，則總能匹配成功，例如instr(‘abc’, ‘’)會返回1。

INSTR('Tech on the net', 'e') = 2
INSTR('Tech on the net', 'e', 1, 1) = 2
INSTR('Tech on the net', 'e', 1, 2) = 11
INSTR('Tech on the net', 'e', 1, 3) = 14

base64_decode(STRING str)

當字串為Base64加密資料時，可使用該函數進行Base64解碼處理

str：STRING類型的字串。如果輸入為BIGINT、DOUBLE、DECIMAL、TIMESTAMP或DATE類型，則會隱式轉換為STRING類型後參與運算。如果輸入為非Base64加密的字串，則返回原字串。

返回STRING類型。

BIGINT LENGTH(STRING str)

返回字串str的長度。

• str：STRING類型。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。
• 返回BIGINT類型。如果輸入參數為NULL，則返回NULL；如果輸入參數為非UTF-8編碼格式，則返回-1。

LENGTH('hi! 中國') = 6

BIGINT LENGTHB(STRING str)

返回字串str的以位元組為單位的長度。

• str：STRING類型。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。
• 返回BIGINT類型。如果輸入參數為NULL，則返回NULL。

LENGTHB('hi! 中國') = 10

STRING MD5(STRING value)

計算輸入字串value的MD5值。

value：STRING類型。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型參與運算，其它類型會返回異常。

返回STRING類型。如果輸入參數為NULL，則返回NULL。

STRING REGEXP_REPLACE(STRING source, STRING pattern, STRING replace_string[, BIGINT occurrence])

將source字串中，第occurrence次匹配pattern的子串，替換成指定字串replace_STRING後，返回結果字串。

• source：STRING類型，要替換的字串。
• pattern：STRING類型常量，要匹配的模式，pattern為空白串時返回異常。
• replace_string：STRING類型，將匹配的pattern替換成的字串。
• occurrence：BIGINT類型常量，必須大於等於0，表示將第幾次匹配替換成replace_string，為0時表示替換掉所有的匹配子串。為其它類型或小於0時，返回異常。可預設，預設值為0。

• 返回STRING類型。當引用不存在的組時，不進行替換。
• 如果任一輸入參數為NULL，則返回NULL。
• 如果replace_string為NULL且pattern有匹配，則返回NULL。
• 如果replace_string為NULL但pattern不匹配，則返回原字串。

regexp_replace("123.456.7890", "([[:digit:]]{3})\\.([[:digit:]]{3})\\.([[:digit:]]{4})",
"(\\1)\\2-\\3", 0) = "(123)456-7890"
regexp_replace("abcd", "(.)", "\\1 ", 0) = "a b c d "
regexp_replace("abcd", "(.)", "\\1 ", 1) = "a bcd"
regexp_replace("abcd", "(.)", "\\2", 1) = "abcd"
-- 因為pattern中只定義了一個組，引用的第二個組不存在。
-- 請避免這樣使用，引用不存在的組的結果未定義。
regexp_replace("abcd", "(.*)(.)$", "\\2", 0) = "d"
regexp_replace("abcd", "a", "\\1", 0) = "bcd"
-- 因為在pattern中沒有組的定義，所以\1引用了不存在的組。
-- 請避免這樣使用，引用不存在的組的結果未定義。

STRING SPLIT_PART(STRING str, STRING separator, BIGINT start[, BIGINT end])

依照分隔字元separator拆分字串str，返回從第start部分到第end部分的子串（閉區間）。

• str：STRING類型，要拆分的字串。如果是BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。
• separator：STRING類型常量，拆分用的分隔字元，可以是一個字元，也可以是一個字串，其它類型返回異常。
• start：BIGINT類型常量，必須大於0。非常量或其它類型會返回異常。返回段的開始編號（從1開始），如果沒有指定end，則返回start指定的段。
• end：BIGINT類型常量，大於等於start，否則返回異常。返回段的截止編號，非常量或其它類型會返回異常。此參數可省略，預設時表示最後一部分。

• 返回STRING類型。
• 如果start的值大於切分後實際的分段數，例如字串拆分完有6個片段，start大於6，返回空串。
• 如果separator不存在於str中，且start指定為1，返回整個str。如果str為空白串，則輸出空串。
• 如果separator為空白串，則返回原字串str。
• 如果end大於片段個數，按片段個數處理。
• 如果任一輸入參數為NULL，則返回NULL。

SPLIT_PART('a,b,c,d', ',', 1) = 'a'
SPLIT_PART('a,b,c,d', ',', 1, 2) = 'a,b'
SPLIT_PART('a,b,c,d', ',', 10) = ''

STRING SUBSTR(STRING str, BIGINT start_position[, BIGINT length])

返回字串str從start_position開始，長度為length的子串。

• str：STRING類型，如果輸入為BIGINT、DECIMAL、DOUBLE或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。
• start_position：BIGINT類型，起始位置為1。當start_position為0時，返回空串。當start_position為負數時，表示開始位置是從字串的結尾往前倒數，最後一個字元是-1，往前數依次為-2、-3…，其它類型會返回異常。
• length：BIGINT類型，表示子串的長度值。值大於0，其它類型或值小於等於0返回異常。

返回STRING類型。如果任一輸入參數為NULL，則返回NULL。

SUBSTR("abc", 2) = "bc"
SUBSTR("abc", 2, 1) = "b"
SUBSTR("abc",-2,2) = "bc"
SUBSTR("abc",-3) = "abc"

STRING TOLOWER(STRING source)

輸出英文字串source對應的小寫字串。

source：STRING類型。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。

返回STRING類型。如果輸入參數為NULL，則返回NULL。

tolower("aBcd") = "abcd"
tolower("哈哈Cd") = "哈哈cd"

STRING TOUPPER(STRING source)

輸出英文字元source串對應的大寫字串。

source：STRING類型。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。

返回STRING類型。如果輸入參數為NULL，則返回NULL。

toupper("aBcd") = "ABCD"
toupper("哈哈Cd") = "哈哈CD"

STRING TO_CHAR(BOOLEAN value)
STRING TO_CHAR(BIGINT value)
STRING TO_CHAR(DOUBLE value)
STRING TO_CHAR(DECIMAL value)

將BOOLEAN、BIGINT、DECIMAL或DOUBLE類型轉為對應的STRING類型表示。

value：BOOLEAN、BIGINT、DECIMAL型或DOUBLE類型，其它類型會返回異常。

返回STRING類型。如果輸入參數為NULL，則返回NULL。

TO_CHAR(123) = '123'
TO_CHAR(true) = 'TRUE'
TO_CHAR(1.23) = '1.23'
TO_CHAR(null) = NULL

STRING TRIM(STRING str)

去除字串str的左右空格。

str：STRING類型。如果輸入為BIGINT、DECIMAL、DOUBLE或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型返回異常。

返回STRING類型。如果輸入參數為NULL，則返回NULL。

LTRIM(' abc ')="abc"; 

STRING LTRIM(STRING str)

去除字串str的左邊空格。

str：STRING類型。如果輸入為BIGINT、DECIMAL、DOUBLE或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。

返回為STRING類型。如果輸入參數為NULL，則返回NULL。

LTRIM(' abc ')="abc "; 

STRING RTRIM(STRING str)

去除字串str的右邊空格。

str：STRING類型。如果輸入為BIGINT、DECIMAL、DOUBLE或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。

返回STRING類型。如果輸入參數為NULL，則返回NULL。

RTRIM('a abc ')="a abc"; 

STRING REVERSE(STRING str)

返回倒序字串。

str：STRING類型。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。

返回STRING類型。如果輸入參數為NULL，則返回NULL。

REVERSE('abcedfg')="gfdecba"

BIGINT ASCII(STRING str)

返回字串str第一個字元的ASCII碼。

str：STRING類型。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。

返回BIGINT類型。

--返回97。
ASCII('abcde')

STRING LPAD(STRING a, INT len, STRING b)

用b字串將a字串向左補足到len位。

• len：INT整型。
• a、b：STRING類型。

返回STRING類型。如果len小於a的位元，則返回a從左開始截取len位字元。如果len為0，則返回空。

lpad('abcdefgh',10,'12')='12abcdefgh'
lpad('abcdefgh',5,'12')='abcde'
lpad('abcdefgh',0,'12') --返回空

STRING RPAD(STRING a, INT len, STRING b)

用b字串將a字串向右補足到len位。

• len：INT整型。
• a、b：STRING類型。

返回STRING類型。如果len小於a的位元，則返回a從左開始截取len位字元；如果len為0，則返回空。

rpad('abcdefgh',10,'12')='abcdefgh12'
rpad('abcdefgh',5,'12')='abcde'
rpad('abcdefgh',0,'12') -- 返回空。

STRING REPLACE(STRING a, STRING OLD, STRING NEW)

用NEW字串替換a字串中與OLD字串完全重合的部分並返回a。

參數均為STRING類型。

返回STRING類型。如果任一輸入參數為NULL，則返回NULL。

REPLACE('ababab','abab','12')='12ab'
REPLACE('ababab','cdf','123')='ababab'
REPLACE('123abab456ab',null,'abab')=null

STRING URL_ENCODE(STRING input[, STRING encoding])

• input：要輸入的字串。
• encoding：指定的編碼格式，支援GBK或UTF-8等標準編碼格式，不輸入預設為UTF-8。

返回STRING類型。如果輸入參數為NULL，則返回NULL。

URL_ENCODE('樣本for URL_ENCODE:// (fdsf)') = "%E7%A4%BA%E4%BE%8Bfor+URL_ENCODE%3A%2F%2F+%28fdsf%29"
URL_ENCODE('Example for URL_ENCODE:// dsf(fasfs)', 'GBK') = "Example+for+URL_ENCODE+%3A%2F%2F+dsf%28fasfs%29"

STRING URL_DECODE(STRING input[, STRING encoding])

• input：要輸入的字串。
• encoding：指定的編碼格式，支援GBK或UTF-8等標準編碼格式，不輸入預設為UTF-8。

返回STRING類型。如果輸入參數為NULL，則返回NULL。

URL_DECODE('%E7%A4%BA%E4%BE%8Bfor+URL_DECODE%3A%2F%2F+%28fdsf%29')= "樣本for URL_DECODE:// (fdsf)"
URL_DECODE('Example+for+URL_DECODE+%3A%2F%2F+dsf%28fasfs%29', 'GBK') = "Example for URL_DECODE:// dsf(fasfs)"

BOOLEAN ENDSWITH(STRING input, STRING suffix)

判斷input的值是否以suffix結尾。

輸入參數為STRING類型。如果輸入參數為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，其它類型會返回異常。

返回BOOLEAN類型。

TO_BASE64(BINARY bin)

將位元據轉換成對應base64編碼的字串輸出。

輸入參數為BINARY類型。

返回base64編碼的字串。