| ColdFusion lists give us the capability to store several values as a single variable. For example, the following code shows how we can use a list to store all of our departments in one variable called lDepts. Note we are using an "l" as a variable prefix to denote the Depts variable is a list (see the "Whats in a Name?" sidebar in Step 2, "Using Variables"). <CFSET lDepts="Marketing,Operations,Sales,Technology"> A list is a simple variable type; it is really nothing more than a normal string variable with a special delimiter character. The default delimiter is a comma, but you can use other values. Values in the list are referred to as elements. For example, Operations is the second element in the list. As you can see, it is a very simple process to create a list. The real power of lists comes in the vast range of list-related functions that are built into ColdFusion MX. Table 10.1 outlines the list-related functions that we have at our disposal. Table 10.1. List Functions| Function | Description |
|---|
| ArrayToList() | This function converts an array to a list. ArrayToList(ArrayName[,delimiter]) | | ListAppend() | This appends the nominated value to the end of the list. ListAppend (list ,value [,delimiters ]) For example: ListAppend(lDepts, Legal) This would append the new Legal department to the end of our lDepts list using the default delimiter. | | ListChangeDelims() | This replaces the current list delimiters with a new value. ListChangeDelims (list ,new_delimiter [,delimiters ]) | | ListContains() | This returns the numerical position of the first element to contain the nominated string. The search is case sensitive. It returns 0 if the string is not found. ListContains (list ,substring [,delimiters ]) For example: ListContains(lDepts, "al") This returns the number 3 because "al" first occurs in the Sales element, which is third in the list. | | ListContainsNoCase() | This is a case-insensitive version of ListContains(). ListContainsNoCase (list ,substring [,delimiters ]) | | ListDeleteAt() | This deletes the element specified by the position argument. ListDeleteAt (list ,position [,delimiters ]) | | ListFind() | This finds the position of the first complete match for the value argument. The search is case sensitive and does not search for substrings. ListFind (list ,value [,delimiters ]) For example: ListFind(lDepts, "Sales") This returns a value of 3. However, searching for "al" will return 0 because it is not a complete match of any element. | | ListFindNoCase() | This is a case-insensitive version of ListFind(). ListFindNoCase (list ,value [,delimiters ]) | | ListFirst() | This returns the first element in a list. ListFirst (list [,delimiters ]) | | ListGetAt() | This returns the element specified by the position argument. ListGetAt (list ,position [,delimiters ]) For example: ListGetAt(lDepts, 3) This would return Sales. | | ListInsertAt() | This inserts a new element at the specified position. ListInsertAt (list ,position ,value [,delimiters ]) For example: ListInsertAt(lDepts, 3, "Legal") This inserts Legal between Operations and Sales. | | ListLast() | This returns the last element in the list. ListLast (list [,delimiters ]) | | ListLen() | This returns the number of elements in a list. ListLen (list [ ,delimiters ]) | | ListPrepend() | This adds the nominated value to the beginning of the list. It is the opposite of ListAppend(). ListPrepend (list ,value [,delimiters ]) | | ListQualify() | This is used to add qualifiers around list elements. ListQualify (list ,qualifier [,delimiters ] [,elements ]) For example: ListQualify(lDepts,"'") This returns a list of all elements surrounded with single quotes. 'Marketing','Operations','Sales','Technology' | | ListRest() | This returns all elements in the list except the first one. It is the opposite of ListFirst(). ListRest (list [,delimiters ]) | | ListSetAt() | This replaces the element nominated by the position argument with the new value specified. ListSetAt (list ,position ,value [,delimiters ]) | | ListSort() | This sorts the list. ListSort (list,sort_type [,sort_order ][,delimiters ]) | | ListToArray() | This converts the nominated list to an array. ListToArray (list [,delimiters ]) | | ListValueCount() | This returns the number of times the element occurs in the list. The search is case sensitive. ListValueCount (list,value [,delimiters ]) | | ListValueCountNoCase() | This is a case-insensitive version of ListValueCount(). ListValueCountNoCase (list,value [,delimiters ]) |
For more information on list functions, see the Reference section of the www.LearnColdFusionMX.com web site. There is also a special type of loop used especially with lists. In Step 4, "Controlling Program Flow," we had a look at Index and While loops. There also is a loop designed specifically to loop through list elements. Instead of a FROM and TO value, the <CFLOOP> tag simply takes an INDEX attribute and a LIST attribute, which nominates the list to be used in the loop. You can also use an optional DELEMITERS attribute if the list delimiter is something other than a comma. The following code <CFSET lDepts="Marketing,Operations,Sales,Technology"> <CFLOOP INDEX="x" LIST="#lDepts#"> <CFOUTPUT>Department: #x# <BR></CFOUTPUT> </CFLOOP> would display each individual element in the lDepts list, as follows. Department: Marketing Department: Operations Department: Sales Department: Technology Displaying list values is quite easy. To display the entire list, simply use <CFOUTPUT> tags and the list name to output the list, as follows: <CFOUTPUT>#lDepts#</CFOUTPUT> The preceding code would output the entire list, delimiters and all, as follows: Marketing,Operations,Sales,Technology To output a particular element, simply use a List loop or one of the list functions in Table 10.1. The following code illustrates how we could display just the Sales element. <CFOUTPUT>#ListGetAt(lDepts, 3)#</CFOUTPUT> |