ColdFusion 9.0 Resources

ListToArray

Description

Copies the elements of a list to an array.

Returns

An array

Function syntax

ListToArray(list [, delimiters[, includeEmptyFields[, multiCharacterDelimiter]]])

History

ColdFusion 9: Added the multiCharacterDelimiter parameter.

Parameters

Parameter	Description
`list`	A list or a variable that contains one. You define a list variable with a `cfset` statement.
`delimiters`	A string or a variable that contains one. ColdFusion treats each character in the string as a delimiter. The default value is comma.
`includeEmptyFields`	A Boolean value specifying whether to create empty array entries if there are two delimiters in a row. `false` (Default) ignore empty elements in a list; for example, convert `a,,c` into an array with only two elements. `true` Convert empty elements in a list to empty array entries; for example, convert `a,,c` into an array with three elements, the second of which is empty.
`multiCharacterDelimiter`	A Boolean value specifying whether the `delimiters` parameter specifies a multi-character delimiter. The default is `false`. If this parameter is `true`, the `delimiters` parameter must specify a single delimiter consisting of multiple characters. This parameter enables the ListToArray function to convert a list such as the following to an array of color names: red:\|orange:\|yellow:\|green:\|blue:\|indigo:\|violet.

Usage

ColdFusion, by default, ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.

ColdFusion treats each character in the delimiters parameter as a separate delimiter. Therefore, if the parameter is ",+" ColdFusion will break the list at either a comma or a plus sign.

If you specify a multiCharacterDelimiter parameter, all list elements must be separated by exactly the specified characters. For example, the following code creates an array with three entries, “red, orange”, “yellow, green” and “blue, violet”.

<cfset list = "red,orange,&yellow,green,&blue,violet"> 
<cfset arr = listToArray (list, ",&",false,true)>

Example

<h3>ListToArray Example</h3> 
<!--- Find a list of users who wrote messages ---> 
<cfquery name = "GetMessageUser" datasource = "cfdocexamples"> 
SELECT Username, Subject, Posted 
FROMMessages 
</cfquery> 
<cfset myList = ValueList(GetMessageUser.UserName)> 
<p>My list is a list with <cfoutput>#ListLen(myList)#</cfoutput> 
    elements. 
<cfset myArrayList = ListToArray(myList)> 
<p>My array list is an array with <cfoutput>#ArrayLen(myArrayList)# 
    </cfoutput> elements.