Working with Lists

Lists are extremely easy to use and even easier to create. For this reason, many of ColdFusion's internal data sets are stored as lists, and several CFML functions (and variables) return data in this format too.

Lists are accessed via a set of special CFML functions, all of which begin with the word List and take a list as the first attribute.

Creating Lists

CFML functions are generally not used to create a list (in contrast to arrays and structures, both of which require the use of special functions). The following <cfset> statement creates the list of states shown at the beginning of the chapter:

 <!--- States list ---> <cfset states="CA,FL,MA,MI,NY,WA"> 

TIP

You can also use <cfparam> to create lists, and you can use the assignment operator in a <cfscript> block as well.

You can create lists using any of the functions that update lists (for example, ListAppend()) by passing an empty string to the function as the existing list.

Accessing List Elements

You access and manipulate lists by using the list functions. For example, to determine the number of elements in a list, you can use the ListLen() function as follows:

 <!--- Display number of states in list ---> <cfoutput>#ListLen(states)#</cfoutput> 

NOTE

Empty elements are ignored by the list functions, so list a,,b contains just two elements (not three). However, white space is not ignored, so list a, ,b contains three elements.

To access a specific list element, use the ListGetAt() function as follows:

 <!--- Display the third state ---> <cfoutput>#ListGetAt(states, 3)#</cfoutput> 

ColdFusion provides special functions to quickly access the first and last elements in a list (the ListFirst() and ListLast() functions, respectively), as well as to return all elements after the first element (the ListRest() function).

CAUTION

Be careful never to refer to an element that does not exist (for example, trying to retrieve the sixth element in a five-element list) because doing so throws an error. It's a good practice to always check the length of a list (using ListLen()) before accessing specific elements.

NOTE

List elements are numbered starting from 1 (not 0, as in other development languages and platforms).

You also can search lists to find the first element that matches or contains specific text. Use ListFind() to perform an element match (the element matches if it equals the exact search text and nothing more) and ListContains() to perform a contains match (the element matches if it contains the search text). Both functions return the position of the first matching element (not the element itself) and 0 if no match is found. The following code snippet checks to see whether a state is in a list (using the ListFind() function) and displays one of two messages based on the result:

 <!--- Is user's state in the taxable state list? ---> <cfset match=ListFind(states, user.state)> <!--- "match" will be greater than 0 (TRUE) if in "states" list ---> <cfif match>  <!--- Yes, tell user that it is taxable --->  <cfoutput>Sales to #user.state# residents are taxable</cfoutput> <cfelse>  <!--- No, tell user that tax will not be added --->  <cfoutput>No tax is added for #user.state# residents</cfoutput> </cfif> 

TIP

List searches (exact or partial matches) are case sensitive. To perform searches that are not case sensitive, use the ListFindNoCase() and ListContainsNoCase() functions.

Modifying Lists

You can modify lists as you create themdirectly using standard CFML assignment tags and operators. A more efficient way to modify them is to use functions designed for just that purpose. To update an element in a list, for example, use the ListSetAt() function, and to delete an element from a list, use ListDeleteAt().

You can add new elements to a list at any time. The ListPrepend() function inserts an element at the beginning of a list; ListAppend() adds an element at the end of a list; and ListInsertAt() inserts an element at a specific location.

NOTE

The list functions do not modify lists; rather, they return modified lists. If you want to modify a list, you must use the same list as the list parameter and the variable being assigned, as follows:

 <cfset states=ListAppend(states, "WY")> 

Here, an element is added to the states list, so the value returned by ListAppend() (the new list) is assigned to states.

Specifying Delimiters

By default, lists use commas as delimiters, which you saw in the previous examples. But as we explained at the beginning of this chapter, ColdFusion allows you to use any characters as list delimiters. You therefore can use list functionality in interesting ways. For example, to determine the number of words in a string, you could treat that string as a list delimited by spaces, as follows:

 <!--- How many words in "text"? ---> <cfoutput>#text# contains #ListLen(text, " ")# words</cfoutput> 

Because the default delimiter is a comma, alternative delimiters must be explicitly specified. Every list function takes an optional final attributethe delimiter to be used. If you specify " " (a string containing only a space) as the delimiter, the elements in the preceding list are the words in the variable text (words separated by a space).

You can specify multiple delimiters, in which case any of the specified characters acts as a delimiter (rather than all of them). In other words, to count the number of words in a string separated by spaces, periods, commas, or hyphens, you could do the following:

 <!--- How many words in "text"? ---> <cfoutput>#text# contains #ListLen(text, " .,-")# words</cfoutput> 

NOTE

To change the delimiter used in a list (returning a copy of the list using the new delimiter), use the ListChangeDelims() function.