Introduction to Data Structures in ColdFusion Part III - Lists

In the past two articles, we've discussed some of the more complex data structures in ColdFusion. While arrays and structs are extremely useful for very specific tasks, you'll probably find yourself using lists more often. Fortunately, lists are extremely easy to manage in ColdFusion.

For all you Java, C++, and Visual Basic developers, I'm going to let you know now that you'll be extremely jealous of ColdFusion after reading this article. ColdFusion makes it very easy to manipulate lists with its built-in functions. And with a little creativity, a good ColdFusion developer can surely find several million ways to make use of a list.

What is a List?

First, let's define what a list is in ColdFusion terms. A list is simply a string. The only difference between a string and a list is that a list is delimited by a specific character or set of characters. You can use any string as a list, and any list can be manipulated just like any string. For example, a,b,c,d,e,f,g is a comma delimited list. Or you could use a/b/c/d/e/f/g -- a forward-slash delimited list. The default delimiter for a ColdFusion list is the comma. Also, be aware that a/b/c is not the same as a / b / c. ColdFusion does not trim the white space from list elements. If a list includes spaces, you may want to use the Trim function on the elements.

Lists in Action

So, now that we know what ColdFusion defines as a list, we'll begin using lists. First of all, let's try getting the length of a list.

<cfset listLength = ListLen("a,b,c,d,e")>

ListLen will return the value 5 to the variable listLength. That's pretty simple, but here's a challenge for you: what is the value of listLength after the following code is executed?

<cfset listLength = ListLen("a,b,,c,,d,e")>

If you guessed 5, you're right. The reason is that ColdFusion ignores empty list elements. Now, let's say that we want to display every element in the list. This is extremely easy:

<cfloop list="a,b,c,d,e" index="i">
   <cfoutput> #i# <br /></cfoutput>
</cfloop>

This code displays each list element on a separate line. Now, if you have a list stored in a variable, don't forget to put pound signs (#) around the variable name when you pass it to the list attribute of the loop. Otherwise, it will not work correctly.

<cfset list = "a,b,c,d">
<!--- this works fine --->
<cfloop list="#list#" index="i">
   <cfoutput> #i# <br /></cfoutput>
</cfloop>

<!--- this outputs "list" --->
<cfloop list="list" index="i">
   <cfoutput> #i# <br /></cfoutput>
</cfloop>

Just be sure to wrap the variable name in pound signs when you loop over a list.

List Functions

There are also a few list functions that we must cover very briefly before we move on to bigger and better things. We've talked about ListLen, which returns the length of the list. ListLen takes one required parameter, which is the list you want to check the length of, and one optional parameter that specifies the delimiters you want to use. So, you can find out how many words are in a sentence by doing this:

<cfset words = ListLen("The quick brown fox jumps over the lazy dog.", " ")>

Notice that the second parameter specifies that the string passed in the first parameter is a space delimited list. After execution, the words variable contains the value 9.