Inside Coldfusion MX
| A list is a series of values arranged one after the other and separated by a delimiter. These values do not have to be in any particular order. The delimiter that separates the items in a list can be any character. Most commonly, the delimiter is a comma. Having said that, you should know that a list is not really a complex data type. However, manipulation of lists more closely resembles the manipulation of a complex data type than that of a simple data type. ColdFusion sees the list as a string. As long as ColdFusion understands which character in the string is the delimiter, it can process each value in the list separately. Table 7.2 gives samples of lists.
Creating a List
In ColdFusion, you can create a list just as you would any other variable. Look at the example shown in Listing 7.3. Listing 7.3 Creating a List Is As Easy As 1, 2, 3
<html> <head> <title>Inside ColdFusion MX - Lists</title> </head> <body> <!--- We first create our lists ---> <cfset newlist="1,2,3"> <cfset othernewlist="1|2|3"> <cfset yetothernewlist="1|2;3"> </body> </html> This is quite straightforward. Notice that in the second list, we used the | (pipe) character as the delimiter and in the third list, we used multiple delimiters. We don't have to explain to ColdFusion at this point the character or set of characters that we're going to use as the delimiter. When we create the list , we just define it. With a list, you create a variable and the list of items is viewed as the value of that single variable. This variable can be in different scopes: local, session, application, request, cookie, or client. Outputting a List
To output the value of the variable, you simply call the variable within the CFOUTPUT tag, as shown in Listing 7.4. Listing 7.4 Outputting the List Variable to the Screen
<html> <head> <title>Inside ColdFusion MX - Lists</title> </head> <body> <!--- We first create our lists ---> <cfset newlist="1,2,3"> <cfset othernewlist="1|2|3"> <cfset yetothernewlist="1|2;3"> <!--- Now we do the output ---> My lists are:<br><br> <cfoutput> newlist = #newlist#<br> othernewlist = #othernewlist#<br> yetothernewlist = #yetothernewlist# </cfoutput> </body> </html> A list is a variable and a string variable at that so we can output the variable to the page. By combining the code from Listing 7.2 and Listing 7.3, we can produce the result in Figure 7.3. Figure 7.3. The result of the combined code from Listings 7.2 and 7.3.
Obviously, it is pretty easy to create a list and to output it manually. However, what if you want to create a list and set its values on-the-fly? Fortunately, ColdFusion can take care of that for us as well. List Functions
ColdFusion gives developers a number of functions to use to manipulate lists. These functions enable you to do things, such as determine the length of a list, add values to the beginning or end of the list, and even sort your list. The list functions available in ColdFusion include the following:
In this section, we take a look at some of the most commonly used ColdFusion list functions. Creating a List Dynamically
Lists can be created easily and dynamically in ColdFusion. Using the results of a query, you can create a list using the ValueList() function. You saw an example of this functionality in the last section of this chapter; let's review. The ValueList() function enables you to create a list from a specific column in a query object. You can specify a delimiter for the list, but it will default to a comma. You use the following code to create the list: <cfset EmailList=ValueList(GetUsers.Email)> Assume that you want to know how many values are in the list. ColdFusion enables you to find this helpful little piece of information by using the ListLen() function, as shown in the following code snippet: The length of the list is: #ListLen(EmailList)# So, now you have a list of values. Let's look at outputting those values. It won't be as a single value, so let's loop through the output. You might need to perform this kind of task when you need to perform a specific job on each value in the list. ColdFusion gives you the CFLOOP tag for just such a task, as shown in Listing 7.5. Listing 7.5 Creating the Loop to Access Each Value in the List
<html> <head> <title>Inside ColdFusion MX - Lists</title> </head> <body> <!--- We first create our query object ---> <cfset GetUsers = QueryNew("FirstName,LastName,Email")> <!--- Now we set our values ---> <cfset rows=QueryAddRow(GetUsers, 3)> <!--- Now we set our values ---> <cfset var=QuerySetCell(GetUsers, "FirstName", "Neil", 1)> <cfset var=QuerySetCell(GetUsers, "LastName", "Ross", 1)> <cfset var=QuerySetCell(GetUsers, "Email", "neil@codesweeper.com", 1)> <cfset var=QuerySetCell(GetUsers, "FirstName", "John", 2)> <cfset var=QuerySetCell(GetUsers, "LastName", "Cummings", 2)> <cfset var=QuerySetCell(GetUsers, "Email", "john@mauzy-broadway.com", 2)> <cfset var=QuerySetCell(GetUsers, "FirstName", "Robi", 3)> <cfset var=QuerySetCell(GetUsers, "LastName", "Sen", 3)> <cfset var=QuerySetCell(GetUsers, "Email", "r@granularity.com", 3)> <table> <tr> <td> <!--- We first create our lists ---> <cfset EmailList=ValueList(GetUsers.Email)> <cfset EmailListLen=ListLen(EmailList, ",")> <cfset EmailList=ListSort(EmailList, "text", "asc")> <cfset foundit=ListContains(EmailList, "neil")> <cfoutput>We found it at position number #foundit#.</cfoutput><br><br> <cfset EmailList=ListPrepend(EmailList, "info@insidecoldfusionmx.com")> <!--- Now we do the output ---> There are <cfoutput>#EmailListLen#</cfoutput> values in EmailList.<br><br><br> The values of EmailList are:<br> <br> <cfset ListLoopCount=1> <cfloop list="#EmailList#" index="individualemail"> <cfoutput> Position #ListLoopCount# = #individualemail#<br> </cfoutput> <cfset ListLoopCount=ListLoopCount+1> </cfloop> <cfset EmailListArray=ListToArray(EmailList)> <br><br> <cfdump var="#EmailListArray#"> </td> </tr> </table> </body> </html> When the code in Listing 7.5 is executed, you can look for the output shown in Figure 7.4. Figure 7.4. Displaying the contents of the list.
ColdFusion functions enable you to manipulate lists in a number of ways. Let's take a look at some of the commonly used list functions:
The list could, of course, go on and on, but these are the most commonly used list functions. At this point, let's move on to our next complex data type the array. |