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 How to Migrate to InterSystems IRIS, available on the WRC Distributions page (login required).

ListToString

Creates a string from a list.

Synopsis

ListToString(list[,delimiter])

Parameters

list An expression that evaluates to a valid list. A Caché list must be created using ListBuild or ListFromString, or extracted from another list using List. The null string ("") is also treated as a valid 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.

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 ListFromString, or extracted from another list using List.

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

Examples

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

namelist=ListBuild("Deborah","Noah","Martha","Bowie")
PrintLn 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:

namelist=ListBuild("Deborah","Noah","Martha","Bowie")
PrintLn ListToString(namelist,"*sp*")

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

See Also

Feedback