Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see the InterSystems IRIS Migration Guide and Migrating to InterSystems IRIS, both available on the WRC Distributions page (login required).

$LISTTOSTRING

Creates a string from a list.

Synopsis

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

Parameters

Argument Description
list A Caché 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 boolean value that specifies how to handle an omitted list element. 0 issues a <NULL VALUE> error. 1 inserts an empty string for the element. The default is 0.

Description

$LISTTOSTRING takes a Caché 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. Caché makes no distinction between a character serving as a delimiter and the same character as a data character.

Parameters

list

A Caché 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 parameter 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
Copy code to clipboard

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 boolean flag used to specify how to handle omitted elements in list. In the following example, the $LISTBUILD creates a list with an omitted element, and the flag=1 option is specified to handle this list element:

  SET colorlist=$LISTBUILD("Red",,"Blue")
  WRITE $LISTTOSTRING(colorlist,,1)
Copy code to clipboard

If the flag option was omitted or set to 0, 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 Caché SQL, as described in the Caché SQL Reference.

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,":")
Copy code to clipboard

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*")
Copy code to clipboard

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)
Copy code to clipboard

returns "Deborah:::Bowie"

$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)
Copy code to clipboard

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

  WRITE "1",$LISTTOSTRING("",,0),!
  WRITE "4",$LISTTOSTRING($LB(""),,0)
Copy code to clipboard

The others generate a <NULL VALUE> error.

See Also

Feedback