Now that you have a firm grasp of all the functions related to a list, let’s look at a small example of how to use these capabilities in an application.
For example, say a list of comma-delimited e-mail addresses has been provided by a user (don’t concern yourself with how the list is provided because this is addressed in Chapter 15, “Forms”). Each element in this list is assumed to be an e-mail address. You want to add each address 10 a simple database table only if the address is not currently in the table.
Step by step, you need to do the following
1. Determine the number of elements in the list.
2. Display the number of addresses in the list.
3. For each element in the list, do the following:
a. Check if the address is in the database.
b. If it is not in the database, add it to the database.
c. Display a message indicating the action taken.
For the purposes of your coldFusion code you will make the following assumptions:
• The list is already stored in a variable called newusers.
• Commas are the only delimiters in the list.
• The desired database table is in a data source called ma;1; st .
• The table itself is called users.
• The table contains a single text field called ema’i 1 that is used to store the e-mail addresses.
Now, for the code, see Listing 14.2.
<!— Get ~he length of the list —>
<CFSET length – listlen(newusers»
<1— Output the length of the list —>
<STRONG>The list contains .length’ elements</STRONG><BR>
<!— loop through each element in the list —>
<CFlOOP INDEX-‘element’ FROM-l To-Ilength.>
<!— Get the specified element —>
<CFSET currentuser – listGetAt(newusers,element»
<1— Check if the element is in the database —>
<CFQUERY NAME= ‘Check” DATASOURCE-‘mai1list’>
<1— Perform the appropriate action —)
<CFIF Check. RecordCount ‘greater than 0>
<CFOUTPUT>#currentuser# is already in the
database and has not been added<BR></CFOUTPUT>
<CFQUERY NAMEa’Add’ DATASOURCE-‘maillist’>
INSERT INTO users
<CFOUTPUT>#currentuser# has been added to
This code produces results like those figure 1-1.2.
Let’s walk through this template section by section. You start by using ListLen to’ obtain the number of elements to display in the list which you then display. Knowing the number of elements in the list you can use CFLOOPto perform a series of actions on each element in the list. You do this by using 1 as the starting value for the loop index and by using the number of elements in the list as the ending value for the loop
Within the loop you use ListGetAt to extract the element at the position indicated by the index of loop element. After you have the element you have two jobs: Check whether the element is already in the database and then take the appropriate action.
You use a SQL SELECTstatement to retrieve from the database any records that match the element. Then in your CFIF statement you use the RecordCount property of your query result to see whether any records were retrieved. If RecordCount is greater than zero then you know that a record already in the database matches the current element and you don’t add it to the database again. Otherwise you use a SQL INSERTstatement to add a record to the database
Understanding and Using Arrays
Arrays are data structures common to all robust programming languages and Cold-Fusion is no exception. Conceptually arrays are quite simple.
In its most basic form, a one-dimensional array’ is very close in concept to a list: a series of elements, each with a numerical place in the list. The difference lies in how elements are referred to and manipulated.
Generally, arrays are named, ordered collections of elements. Let’s look at a simple example: a list of students in a class. Here you can use an array to keep track of the students’ names. For instance, if you have five students in a class, you can create an array called students and then the elements, numbered one to five, would be as follows:
1. Student name 1
2. Student name 2
3. Student name 3
4. Student name 4
5. Student name 5
At a practical level in ColdFusion, a numerical element within an array is referred to by placing the numerical index (or position) of the element in square brackets after the name of the array. In this case, that means the five elements are referred to as the following
These element names can be used in the same way as regular variab .names anywhere in your templates including in CFSET tags and CFOUPUT blocks. For instance you can use the following:
to assign the name of a specific student to another variable or you can output a name by using
<CFOUTPUT>Student Name: fstudents*</CFOUTPUT>
Like other variables new values can be assigned to specific elements in an array with CFSET
<CFSET students-‘New Name>
Another valuable aspect of arrays is that the numeric index, or position, of an element does not have to be explicitly specified as in the preceding examples; it can be specified with.a variable
<CFSET students[index] – ‘NewName>
This approach can be extended in that entire expressions can serve to indicate the index of an array element. For instance, continuing this example, you could access the fifth element of the students array with the following:
<CFSET students[index+l] – ‘NewName2>
Understanding Multiple Dimensions
up to this point you have looked at one-dimensional arrays. These arrays can best b thought of as a single row of multiple cells with each cell having a number-as shown in Figure 14.3.
However arrays can have more than one dimension in ColdFusion. In Coldfusion arrays can have one two or three dimensions. For instance consider a two-dimensional array: nus is really a data structure of multiple rows with each row having multiple cells. See Figure 14.4
Here you see multiple rows and multiple cells. In Coldf’usion, an jndlvidual cell C,lO be referenced by two nwperic indexes, each in square brackets following the array namein the form arrayname[row] [cell]. Therefore, to reference the third cell in the second row of the array shown in Figure 14.4, you would use something like arrayname  .
ColdFusion also provides support for three-dimensional arrays (but not higher dimensions). This simply adds another dimension to the puzzle (making it hard to show graphically). But, if you think of a cube built out of smaller cubes, then you can see the picture of multiple panes, each with a row consisting of multiple cells. To reference the individual cells, simply use three numeric indexes: arrayname [p1 ane] [row] [ce 11].
Arra.ys are created using the ArrayNew function. This function takes a single argument: The number of dimensions of the array (1, 2, or 3). It returns an empty array of the number of dimensions specified
For instance, our array of student names is a one-dimensional array. You create this array by using CFSETto assign the array returned by ArrayNew to the name students:
Similarly, to create a two-dimensional array called array 2d you would use the following:
Populating an Array
After an array is created you must populate it. That is, you need to assign whatever values you want to elements in the array. You do this with a standard CFSET tag. For instance our students array can be populated with a series of CFSETtags like these:
<CFSET students[l) – ‘Student name 1’>
<CFSET students[Z) – ‘Student name Z’>
<CFSET students[3) – ‘Student name 3’>
Our two-dimensional array could be populated with the following:
<CFSET arrayZd[l) [1) – ‘Value 1/1’>
<CFSET arrayZd[l)[Z) – ‘Value l/Z’>
<CFSET arrayZd[l) (3) – ‘Value 1/3’>
<CFSET arrayZd[Z] [1) – ‘Value Z/l’>
<CFSET arrayZd[Z) [Z).- ‘Value Z/Z’>
At times, you may want to populate a large number of cells with a default value. For one-dimensional arrays this can be done with the ArraySet function, which, given an array fills a specified range of cells with the same value. The function is used as follows:
For instance if you want the first 10 elements of our students array to be set with a default value of No Name you could use ArraySet(students 1 10 No Name·