$LISTFROMSTRING (ObjectScript)
Synopsis
$LISTFROMSTRING(string,delimiter,flag)
$LFS(string,delimiter,flag)
Arguments
Argument | Description |
---|---|
string | A string to be converted into an InterSystems IRIS list. This string contains one or more elements, separated by a delimiter. By default, 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.
Arguments
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. By default, the delimiter character is not included in the output list and therefore the string data elements cannot contain the delimiter character (or string). As described in the following section on the use of the flag argument, string data elements of the output list can contain the delimiter string under certain conditions when the value of flag is set to 2 or 3.
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 an <ILLEGAL VALUE> 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")
-
The 2 bit specifies how to handle quotation marks within a string. $LISTFROMSTRING returns delimited substrings in string as quoted string elements. By default, quotation marks in a delimited substring will be preserved in the corresponding string data element of the list. When the flag is set to 2 or 3, quotation marks at the beginning and end of a delimited substring are removed, and delimiter characters or strings contained within that substring will not be treated as delimiters. Instead, they will be included in the corresponding string data element of the list. This is shown in the following example:
SET qstr="abc,3,""New York, New York"",004.0,""5"",""+0.600""" ZWRITE $LISTFROMSTRING(qstr,,0) // $lb("abc","3","""New York"," New York","004.0","""5""","""+0.600""") ZWRITE $LISTFROMSTRING(qstr,,2) // $lb("abc","3","New York, New York","004.0","5","+0.600")
Example
Consider a string defined like this:
SET namestring="Deborah Noah Martha Bowie"
Then suppose we convert that string to a list:
SET namelist=$LISTFROMSTRING(namestring," ")
The following table shows the resulting list elements:
Expression | Value |
---|---|
$LIST(namelist,1) | Deborah |
$LIST(namelist,2) | Noah |
$LIST(namelist,3) | Martha |
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