Skip to main content

$LISTTOSTRING (ObjectScript)

Creates a string from a list.

Synopsis

$LISTTOSTRING(list,delimiter,flag)
$LTS(list,delimiter,flag)

Arguments

Argument Description
list An InterSystems IRIS list, created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.
delimiter Optional — A delimiter used to separate substrings. Specify delimiter as a quoted string. If no delimiter is specified, the default is the comma (,) character.
flag Optional — A three-bit binary bit flag. Available values are 0 (000), 1 (001), 2 (010), 3 (011), 4 (100), 5 (101), 6 (110), and 7 (111). The default is 0.

Description

$LISTTOSTRING takes an InterSystems IRIS list and converts it to a string. In the resulting string, the elements of the list are separated by the delimiter.

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. $LISTTOSTRING converts this list to a string with delimited elements. It sets aside a specified character (or character string) to serve as a delimiter. These delimited elements can be handled using the $PIECE function.

Note:

The delimiter specified here must not occur in the source data. InterSystems IRIS makes no distinction between a character serving as a delimiter and the same character as a data character.

You can use the ZWRITE command to display a list in non-encoded format.

Arguments

list

An InterSystems IRIS list, which contains one or more elements. A list is created using $LISTBUILD or extracted from another list using $LIST.

If the expression in the list argument does not evaluate to a valid list, a <LIST> error occurs.

   SET x=$CHAR(0,0,0,1,16,27,134,240)
   SET a=$LISTTOSTRING(x,",")   // generates a <LIST> error

delimiter

A character (or string of characters) used to delimit substrings within the output 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 can specify a null string ("") as a delimiter; in this case, substrings are concatenated with no delimiter. To specify a quote character as a delimiter, specify the quote character twice ("""") or use $CHAR(34).

flag

A three-bit binary bit flag:

  • The 1 bit specifies how to handle omitted elements in list. 0 issues a <NULL VALUE> error. 1 inserts an empty string for each omitted element.

    In the following example, the list has an omitted element. The flag=1 option is specified to handle this list element:

      SET colorlist=$LISTBUILD("Red",,"Blue")
  WRITE $LISTTOSTRING(colorlist,,1)

    If the flag 1 bit was omitted or set to 0 (flag=0, 2, 4, or 6), the $LISTTOSTRING would generate a <NULL VALUE> error.

    Note that if flag=1, an element with an empty string value is indistinguishable from an omitted element. Thus $LISTBUILD("Red","","Blue") and $LISTBUILD("Red",,"Blue") would return the same $LISTTOSTRING value. This flag=1 behavior is compatible with the implementation of $LISTTOSTRING in InterSystems SQL.

  • The 2 bit specifies quoting of strings that contain certain characters. These characters are the delimiter character (which defaults to a comma), the double-quote character ("), the line feed (LF = $CHAR(10)) and the carriage return (CR = $CHAR(13)) characters. This bit is set by flag=2, or 3. (When flag=6, or 7, this option is set, but overridden by the 4 bit option).

  • The 4 bit specifies quoting of all strings. This bit is set by flag=4, 5, 6, or 7.

Examples

The following example creates a list of four elements, then converts it to a string with the elements delimited by the colon (:) character:

   SET namelist=$LISTBUILD("Deborah","Noah","Martha","Bowie")
   WRITE $LISTTOSTRING(namelist,":")

returns "Deborah:Noah:Martha:Bowie"

The following example creates a list of four elements, then converts it to a string with the elements delimited by the *sp* string:

   SET namelist=$LISTBUILD("Deborah","Noah","Martha","Bowie")
   WRITE $LISTTOSTRING(namelist,"*sp*")

returns "Deborah*sp*Noah*sp*Martha*sp*Bowie"

The following example creates a list with one omitted element and one element with an empty string value. $LISTTOSTRING converts it to a string with the elements delimited by the colon (:) character. Because of the omitted element, flag=1 is required to avoid a <NULL VALUE> error. However, when flag=1, the omitted element and the empty string value are indistinguishable:

   SET namelist=$LISTBUILD("Deborah",,"","Bowie")
   WRITE $LISTTOSTRING(namelist,":",1)

returns "Deborah:::Bowie"

The following example creates a list with an element that contains a comma. By default, $LISTTOSTRING uses the comma as the delimiter. In the first example, the element containing the comma is indistinguishable from two comma-separated elements. In the second example, flag=3 quotes this element. In the third example, flag=7 quotes all string elements.

   SET pairlist=$LISTBUILD("A,B","C^D","E|F")
   WRITE $LISTTOSTRING(pairlist,,1)
     // returns A,B,C^D,E|F
   WRITE $LISTTOSTRING(pairlist,,3)
     // returns "A,B",C^D,E|F
   WRITE $LISTTOSTRING(pairlist,,7)
    // returns "A,B","C^D","E|F"

$LISTVALID considers all of the following valid lists. With flag=1, $LISTTOSTRING returns the null string ("") for all of them:

  WRITE "1",$LISTTOSTRING("",,1),!
  WRITE "2",$LISTTOSTRING($LB(),,1),!
  WRITE "3",$LISTTOSTRING($LB(UndefinedVar),,1),!
  WRITE "4",$LISTTOSTRING($LB(""),,1)

With flag=0, $LISTTOSTRING returns the null string ("") for only the following:

  WRITE "1",$LISTTOSTRING("",,0),!
  WRITE "4",$LISTTOSTRING($LB(""),,0)

The others generate a <NULL VALUE> error.

See Also

$LISTUPDATE (ObjectScript)Next section
Previous section$LISTSAME (ObjectScript)
FeedbackOpens in a new tab