$LISTFROMSTRING
Synopsis
$LISTFROMSTRING(string,delimiter,flag) $LFS(string,delimiter,flag)
Parameters
| string | A string to be converted into an InterSystems IRIS list. This string contains one or more elements, separated by a delimiter. The delimiter does not become part of the resulting InterSystems IRIS list. |
| delimiter | Optional — The delimiter used to separate substrings (elements) in string. Specify delimiter as a quoted string. If no delimiter is specified, the default is the comma (,) character. |
| flag | Optional — A two-bit binary bit flag. Available values are 0 (00), 1 (01), 2 (10), and 3 (11). The default is 0. |
Description
$LISTFROMSTRING takes a quoted string containing delimited elements and returns a list. A list represents data in an encoded format which does not use delimiter characters. Thus a list can contain all possible characters, and is ideally suited for bitstring data. Lists are handled using the ObjectScript $LIST functions.
You can use the ZWRITE command to display a list in non-encoded format.
Parameters
string
A string literal (enclosed in quotation marks), a numeric, or a variable or expression that evaluates to a string. This string can contain one or more substrings (elements), separated by a delimiter. The string data elements must not contain the delimiter character (or string), because the delimiter character is not included in the output list.
delimiter
A character (or string of characters) used to delimit substrings within the input string. It can be a numeric or string literal (enclosed in quotation marks), the name of a variable, or an expression that evaluates to a string.
Commonly, a delimiter is a designated character which is never used within string data, but is set aside solely for use as a delimiter separating substrings. A delimiter can also be a multi-character string, the individual characters of which can be used within string data.
If you specify no delimiter, the default delimiter is the comma (,) character. You cannot specify a null string ("") as a delimiter; attempting to do so results in a <STRINGSTACK> error.
flag
A two-bit binary bit flag.
The 1 bit specifies how to handle adjacent delimiters in string, which correspond to omitted elements in the returned encoded list. 0 represents an omitted element as an empty string (""). 1 represents an omitted element as a null element. This is shown in the following example:
SET colorstr="Red,,Blue" ZWRITE $LISTFROMSTRING(colorstr,,0) // $lb("Red","","Blue") ZWRITE $LISTFROMSTRING(colorstr,,1) // $lb("Red",,"Blue")Copy code to clipboardThe 2 bit specifies how to handle quotation marks within a string. $LISTFROMSTRING returns delimited substrings in string as quoted string elements. By default, doubled quotation marks in string are preserved in the returned list elements. Setting flag to 2 or 3 causes doubled quotation marks to be removed. This is shown in the following example:
SET qstr="abc,3,""big"",004.0,""5"",""+0.600""" ZWRITE $LISTFROMSTRING(qstr,,0) // $lb("abc","3","""big""","004.0","""5""","""+0.600""") ZWRITE $LISTFROMSTRING(qstr,,2) // $lb("abc","3","big","004.0","5","+0.600")Copy code to clipboard
Example
The following example takes a string of names which are separated by a blank space, and creates a list:
SET namestring="Deborah Noah Martha Bowie" SET namelist=$LISTFROMSTRING(namestring," ") WRITE !,"1st element: ",$LIST(namelist,1) WRITE !,"2nd element: ",$LIST(namelist,2) WRITE !,"3rd element: ",$LIST(namelist,3)
See Also
$LISTTOSTRING function
$LISTBUILD function
$LIST function
$PIECE function
$LISTDATA function
$LISTFIND function
$LISTGET function
$LISTLENGTH function
$LISTNEXT function
$LISTSAME function
$LISTUPDATE function
$LISTVALID function