Description

Copies the elements of a list to an array.

Returns

An array

Category

Array functionsConversion functionsList functions

Function syntax

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

See also

ArrayToListUsing 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 1

Example 2

<cfscript>
       myList="ten;twenty;thirty;fort;fifty;sixty;;seventy;;;eighty"; // list contains empty elements
       // convert myList to myArray
       myArray=listToArray(myList,";",false,true); // Using includeEmptyFields=false
       // Display array elements
       WriteDump(myArray);
</cfscript>
includeEmptyFields=true
includeEmptyFields=true

Example 3

<cfscript>
       myList="ten;twenty;thirty;fort;fifty;sixty;;seventy;;;eighty"; // list contains empty elements
       // convert myList to myArray
       myArray=listToArray(myList,";",true,true); // Using includeEmptyFields=true
       // Display array elements
       WriteDump(myArray);
</cfscript>
includeEmptyFields=false
includeEmptyFields=false

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy