ListToArray

Description

Copies the elements of a list to an array.

Returns

An array

Category

Array functions, Conversion functions, List functions

Function syntax

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

See also

ArrayToList; Using Arrays and Structures in the Developing ColdFusion Applications

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.