I love lists in CFML. I try to use lists whenever possible. They're efficient, clean, and powerful. I've wished for a long time that SQL Server and Oracle had built in list functions that were as easy to use as the CFML list functions. I'm not going to go over all of the list functions here, but I will cover a few examples and ways they can make your life easier.
Have you ever found yourself with a long cfif statement that's checking the same thing over and over? Something like one of these:
<cfif variables.userName is "Bob" or variables.userName is "Betty" or variables.userName is "John" or variables.userName is "Jane">...</cfif>
An easier way would be to use listFindNoCase() or listFind() to compare items. For example:
<cfif ListFindNoCase('Bob,Betty,John,Jane', variables.userName)>...</cfif>
There, isn't that better? To me that's much easier to read, and according to Adobe's Coding Best Practices for ColdFusion Performance, when it comes to using listFindNoCase() or listFind() instead of the "is" and "or" operators "They are much faster".
List functions can be used on a variety of items, not just comma delimited lists. Since you have the option to specify what your delimiter is, this really opens the door as to what you can do with lists in CFML.
For example, let's say you wanted to separate the dollars and cents from the value $14.95, just specify the dot as your list delimiter.
Would give you:
Or you wanted to find out how many words are in a sentence by specifying a blank space as your list delimiter:
#ListLen("CFML is da bomb!", " ")#
Would give you:
You could also separate words in a sentence or phrase using a blank space as your list delimiter:
#ListFirst("CFML Rocks!"," ")#<br />
#ListLast("CFML Rocks!"," ")#
Would give you:
Lists can also have multiple delimiters. To borrow an example from LiveDocs:
List length using ; and , as delimiters: #listlen(Mylist, ";,")#<br>
List length using only , as a delimiter: #listlen(Mylist)#<br>
Would displays the following output:
List length using only , as a delimiter: 3
In the multiple delimiter example above either the comma or the semicolon is interpreted as a delimiter when parsing the list, but not the combination of both. Meaning, ";" and "," are each seen as an individual delimiter, not the combined value of ";,".
ListFind() vs. ListContains()
These two functions can be confusing. It's easy to get them mixed up. They both do the same thing, sort of, but they do it just a little bit differently. Here's how I remember which function is which:
ListFind() will find an exact match to the specified value.
ListContains() will return a match that contains the specified value (though it doesn't have to be an exact match).
Here's an example that might explain it a little better:
Take the following list of numbers
If you were search for the number 1 using ListFind() like so:
you would not find a match. The number 1 is not an individual item in our list, so there is not an exact match. However, if you were to search the same list of numbers for the number 1 using ListContains():
every number in our list would be a match because each number contains the specified "1". ListContains() does not search for a specific element that exactly matches the substring (the number 1 in our case), but merely an element that contains it.
One thing to point out is that ListFind() and ListContains() are case-sensitive. So when using them with text strings, "a" and "A" are not considered matches. However, each of these has a case-insensitive counterpart of ListFindNoCase() and ListContainsNoCase().
Remove blank elements from a list
And last but not least, here's a neat little trick I've found for removing blank elements from a list in CFML. Even though empty list elements are ignored in CFML list functions, there are times when you actually need to remove the empty elements instead of just ignore them. Simply convert it to an array and then back to a list. It's quick and dirty, but it works. The ListToArray() function has an optional "includeEmptyFields" parameter which defaults to false, so it will ignore any empty elements. Here's an example:
This post is part of a continuing series of CFML 101 articles. My intent is to produce a blog series aimed at the beginning CFML developer, one which helps to explain basic techniques and concepts to those new to the CF world. The topics and examples covered in this series focus on the CFML programming language in general, not a specific application server. So whether you're using ColdFusion, Railo, or Blue Dragon (referred to as CF/R/BD) to run your CFML applications, these concepts still apply.