| In this example, we will create an array and use the <CFDUMP> tag to display our array structure (see the "Using <CFDUMP>" sidebar). -
Open your text editor and type the code in Listing 10.3 or open the Array1.cfm file from the CompletedFiles\Examples\Step10 folder. Listing 10.3 Array1.cfm <!--- File: Array1.cfm Description: Demo the creation of an array and the use of <CFDUMP> Author: Created: ---> <HTML> <HEAD> <TITLE>Array 1</TITLE> </HEAD> <BODY> <!--- create the array ---> <CFSET aDepts=ArrayNew(1)> <!--- populate the array with data ---> <CFSET aDepts[1]="Marketing"> <CFSET aDepts[2]="Operations"> <CFSET aDepts[3]="Sales"> <CFSET aDepts[4]="Technology"> <!--- display element 3 ---> <P><CFOUTPUT>#aDepts[3]#</CFOUTPUT></P> <!--- dump the array ---> <CFDUMP VAR="#aDepts#"> </BODY> </HTML> -
Save the file as Array1.cfm in your Example\Step10 folder. -
Browse to the Array1.cfm file. You should see something similar to Figure 10.4. Figure 10.4. The Array1.cfm browser display. Continues
Inserting and Deleting Array Elements ColdFusion arrays are dynamic, meaning we do not have to specify the number of elements needed when we create the array. Our array will expand and contract automatically as we add and delete elements within the array. There are several ways to add data elements to an array. We have already seen how to accomplish this using <CFSET>. We can also use a number of the array functions shown in Table 10.2. These functions include ArrayAppend(), ArrayPrepend(), and ArrayInsertAt(). The ArrayAppend() function adds an element to the end of an array. The ArrayPrepend() function adds an element to the beginning of the array, and all the existing elements get reindexed. For example, if we used ArrayPrepend() to add the Legal department, the Marketing department would reshuffle to aDepts[2], the Operations department would become aDepts[3], and so on down the line. Table 10.2. Array Functions| Function | Description |
|---|
| ArrayAppend() | Adds a new element, as specified by the value argument, to the end of an array. ArrayAppend (array,value) | | ArrayAvg() | Calculates the average for all elements in an array. Must only be used with arrays that contain numeric values. Will produce an error if a non-numeric value is found. ArrayAvg (array) | | ArrayClear() | Empties all elements from an array. ArrayClear (array) | | ArrayDeleteAt() | Deletes the element specified by the position argument. All elements' indexes will be recalculated to fill the newly vacated position. ArrayDeleteAt (array, position) | | ArrayInsertAt() | Inserts a new element into the position specified. All elements whose index is greater than the new element will have their indexes incremented by one. ArrayInsertAt (array, position, value ) | | ArrayIsEmpty() | Returns true if the specified array is empty. ArrayIsEmpty (array) | | ArrayLen() | Returns the number of elements in an array ArrayLen (array) | | ArrayMax() | Displays the maximum value in an array containing numeric values. ArrayMax (array) | | ArrayMin() | Displays the minimum value in an array containing numeric values. ArrayMin (array) | | ArrayNew() | Creates a new one-, two-, or three-dimensional array. ArrayNew (dimension) | | ArrayPrepend() | Adds a new element, as specified by the value argument, to the beginning of an array. All other index values are incremented by one. ArrayPrepend (array ,value) | | ArrayResize() | Resets an array to the minimum number of elements specified by the minimum_size argument. ArrayResize (array ,minimum_size) | | ArraySet() | Used to fill array elements with a default value. ArraySet (array,start_pos,end_pos,value ) | | ArraySort() | Sorts an array. ArraySort (array ,sort_type [,sort_order ]) | | ArraySum() | Calculates the sum for all elements in an array. Must only be used with arrays that contain numeric values. Will produce an error if a non-numeric value is found. ArraySum (array) | | ArraySwap() | Swaps the values of the elements specified with the position attributes. ArraySwap (array,position1,position2) | | ArrayToList() | Converts a one-dimensional array to a list. ArrayToList (array [,delimiter ]) | | IsArray() | Returns TRUE if the value tested is an array. IsArray (value [,number ]) | | ListToArray() | Copies the elements in a list into an array. ListToArray (list [,delimiters ]) |
For more information on array functions, see the Reference section of the www.LearnColdFusionMX.com web site. The ArrayInsertAt() function inserts a new element at the position specified by the function. For example, the following code would insert the Legal department into index position 3. <CFSET temp=ArrayInsertAt(aDepts,3,"Legal")> When we use the ArrayInsertAt() function to insert a new element, all the existing elements whose index is equal to or greater than the index specified in the function get bumped up one. So, in our example, Legal becomes aDepts[3], Sales gets moved to aDepts[4], and Technology gets bumped to aDepts[5]. Let's have a closer look at the way the preceding <CFSET> statement is constructed. The ArrayInsertAt() function actually performs the insert and will return a value of TRUE if the insert was successful and FALSE if it was not. This TRUE or FALSE value is being stored in the temp variable we have created. However, we are not actually using the temp value for anything. To delete elements from an array, we can use the ArrayDeleteAt() and ArrayClear() functions. The ArrayDeleteAt() function deletes an element from the array at the index position nominated by the function. After the element has been deleted, the remaining elements will reindex to fill the empty slot. The ArrayClear() function simply deletes all elements from a given array. The array still exists in memory; it is simply devoid of any element values. You do not have to fill array indexes in order. For example, the following code creates a new array and sets the value for elements 1, 2, and 4. However, no value has been set for element 3. <!--- create the array ---> <CFSET aDepts=ArrayNew(1)> <!--- populate the array with data ---> <CFSET aDepts[1]="Marketing"> <CFSET aDepts[2]="Operations"> <CFSET aDepts[4]="Technology"> If we try to display an element that does not exist, as follows, our template will return the error shown in Figure 10.5. Figure 10.5. An undefined element error. <CFOUTPUT>#aDepts[2]#</CFOUTPUT><BR> <CFOUTPUT>#aDepts[3]#</CFOUTPUT> One way to prevent this from happening is to prefill your array elements with some temporary value using the ArraySet() function. The ArraySet() function fills specified array elements with the value of your choice. For example, the following code would create an array and fill elements 1 through 5 with an empty string. <CFSET aDepts=ArrayNew(1)> <CFSET temp=ArraySet(aDepts,1,5,"")> |