Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

$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

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)

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

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"

$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

$LISTUPDATENext section
Previous section$LISTSAME
FeedbackOpens in a new tab