$LISTFROMSTRING (ObjectScript)

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.

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.

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")