$LISTTOSTRING ($LTS)
Synopsis
$LISTTOSTRING(list,delimiter) $LTS(list,delimiter)
Parameters
| list | An expression that resolves to a Caché list. A Caché list is created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST. |
| delimiter | Optional — A delimiter used to separate substrings. An expression that resolves to a string containing one or more characters. If no delimiter is specified, the default is the comma (,) character. The delimiter cannot contain the character used to delimit the quoted string. |
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.
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.
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, either use another delimiter for the string (for example, \"\) or use the CHAR() function (34=", 39=', 92=\).
Example
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")
PRINT $LISTTOSTRING(namelist,":")
returns "Deborah:Noah:Martha:Bowie"
See Also
-
$LIST function
-
$LISTBUILD function
-
$LISTDATA function
-
$LISTFIND function
-
$LISTFROMSTRING function
-
$LISTGET function
-
$LISTLENGTH function
-
$LISTNEXT function
-
$LISTSAME function
-
$LISTVALID function
