Project: YugabyteDB (App Definition and Development / Database)
File: string-to-array.md

title: stringtoarray() linkTitle: stringtoarray() headerTitle: stringtoarray() description: stringtoarray() menu: v2.18: identifier: string-to-array parent: array-functions-operators type: docs Purpose: Return a one-dimensional `text[]` array by splitting the input `text` value into subvalues using the specified `text` value as the "delimiter". Optionally, allows a specified `text` value to be interpreted as `NULL`. Signature: ``` input value: text, text [, text] return value: text[] ``` Example: ```plpgsql select stringtoarray( 'a|b|?|c', -- the to-be-split string '|', -- the character(s) to be taken as the delimiter '?' -- the character(s) to be taken to the null indicator ) as "stringtoarray result"; ``` It produces thus result: ``` stringtoarray result {a,b,NULL,c} ``` Semantics: The interpretation of the "delimiter" `text` value and the "null indicator" `text` uses this priority rule: First, the "delimiter" `text` value is consumed and only then is the "null indicator" `text` value consumed. However, this rule matters only when these two critical values are defined by more than one character and when one starts with a sequence that the other ends with. Yugabyte recommends, therefore, that when you can choose the `text` values for the "delimiter" and for the "null indicator", you choose two different single characters. This is what the example, above, does. Of course, you must be sure that neither occurs in any of the `text` values that you want to convert into `text[]` arrays. (There is no escaping mechanism.) Predicting the outcome, when unfortunate choices for these two values were made, will require some mental effort. The `DO` block below demonstrates an example of this: The "delimiter" is `' !'::text`. The "null indicator" is `'~ '::text`. And the input contains this sequence: &#160;&#160;&#160; &#60;tilda&#62;&#60;space&#62;&#60;exclamationPoint&#62; The troublesome sequence is shown in typewriter font here: &#160;&#160;&#160; dog house !~ !x! `~ !` cat flap ! ! These considerations, together with the fact that it can produce only a `text[]` output, mean that the `stringtoarray()` function has limited usefulness. ```plpgsql do $body$ declare delim_text constant text := ' !'; null_text constant text := '~ '; input_text constant text := 'dog house !~ !x! ~ ! cat flap ! !'; result constant text[] := stringtoarray(inputtext, delimtext, null_text); gooddelimtext constant text := '|'; goodnulltext constant text := '?'; delimfirsttext constant text := replace(replace( input_text, delimtext, gooddelim_text), nulltext, goodnull_text); nullfirsttext constant text := replace(replace( input_text, nulltext, goodnull_text), delimtext, gooddelim_text); delimfirstresult constant text[] := stringtoarray(delimfirsttext, gooddelimtext, goodnulltext); nullfirstresult constant text[] := stringtoarray(nullfirsttext, gooddelimtext, goodnulltext); -- Notice that one of the special characters, "!", remains in -- both expectedresult and unexpectedresult. -- If expected_result constant text[] := '{"dog house",NULL,"x! ~"," cat flap"," ",""}'; unexpected_result constant text[] := '{"dog house",NULL,"x! ?! cat flap"," ",""}'; begin assert (result = expected_result) and (delimfirstresult = expected_result) and (nullfirstresult <> delimfirstresult) and (nullfirstresult = unexpected_result) and true, 'unexpected'; end; $body$; ```