This section describes the following topics:
You reference array elements by enclosing the index with brackets: arrayName[x] where x is the index that you want to reference. In ColdFusion, array indexes are counted starting with position 1, which means that position 1 in the firstname array is referenced as firstname[1]. For 2D arrays, you reference an index by specifying two coordinates: myarray[1][1].
You can use ColdFusion variables and expressions inside the square brackets to reference an index, as the following example shows:
<cfset myArray=ArrayNew(1)> <cfset myArray[1]="First Array Element"> <cfset myArray[1 + 1]="Second Array" & "Element"> <cfset arrayIndex=3> <cfset arrayElement="Third Array Element"> <cfset myArray[arrayIndex]=arrayElement> <cfset myArray[arrayIndex + 1]="Fourth Array Element"> <cfdump var=#myArray#>
Note: The IsDefined function does not test the existence of array elements. Instead, put any code that might try to access an undefined array element in a try block and use a catch block to handle exceptions that arise if elements do not exist.
In ColdFusion, you declare an array by assigning a variable name to the new array and specifying its dimensions, as follows:
<cfset mynewarray=ArrayNew(x)>
where x is the number of dimensions (from 1 to 3) in the array that you want to create.
Once you declare an array, you can add array elements, which you can then reference using the elements' indexes.
For example, suppose you declare a 1D array called firstname:
<cfset firstname=ArrayNew(1)>
The array firstname holds no data and is of an unspecified length. Next you add data to the array:
<cfset firstname[1]="Coleman"> <cfset firstname[2]="Charlie"> <cfset firstname[3]="Dexter">
After you add these names to the array, it has a length of 3.
ColdFusion supports dynamic multidimensional arrays. When you declare an array with the ArrayNew function, you specify the number of dimensions. You can create an asymmetrical array or increase an existing array's dimensions by nesting arrays as array elements.
It is important to know that when you assign one array (array1) to an element of another array (array2), array1 is copied into array2. The original copy of array1 still exists, independent of array2. You can then change the contents of the two arrays independently.
The best way to understand an asymmetrical array is by looking at it. The following example creates an asymmetric, multidimensional array and the cfdump tag displays the resulting array structure. Several array elements do not yet contain data.
<cfset myarray=ArrayNew(1)> <cfset myotherarray=ArrayNew(2)> <cfset biggerarray=ArrayNew(3)> <cfset biggerarray[1][1][1]=myarray> <cfset biggerarray[1][1][1][10]=3> <cfset biggerarray[2][1][1]=myotherarray> <cfset biggerarray[2][1][1][4][2]="five deep"> <cfset biggestarray=ArrayNew(3)> <cfset biggestarray[3][1][1]=biggerarray> <cfset biggestarray[3][1][1][2][3][1]="This is complex"> <cfset myarray[3]="Can you see me"> <cfdump var=#biggestarray#><br> <cfdump var=#myarray#>
Note: The cfdump tag displays the entire contents of an array. It is an excellent tool for debugging arrays and array-handling code.
The following table describes the code:
| Code | Description |
|---|---|
<cfset myarray=ArrayNew(1)> <cfset myotherarray=ArrayNew(2)> <cfset biggerarray=ArrayNew(3)> |
Create three empty arrays, a 1D array, a 2D array, and a 3D array. |
<cfset biggerarray[1][1][1]=myarray> <cfset biggerarray[1][1][1][10]=3> |
Make element [1][1][1] of the 3D biggerarray array be a copy of the 1D array. Assign 3 to the [1][1][1][10] element of the resulting array. The biggerarray array is now asymmetric. For example, it does not have a [1][1][2][1] element. |
<cfset biggerarray[2][1][1]= |
Make element [2][1][1] of the 3D array be the 2D array, and assign the [2][1][1][4][2] element the value "five deep". The biggerarray array is now even more asymmetric. |
<cfset biggestarray=ArrayNew(3)> <cfset biggestarray[3][1][1] |
Create a second 3D array. Make the [3][1][1] element of this array be a copy of the bigerarray array, and assign element [3][1][1][2][3][1]. The resulting array is very complex and asymmetric. |
<cfset myarray[3]="Can you see me"> |
Assign a value to element [3] of myarray. |
<cfdump var=#biggestarray#><br> <cfdump var=#myarray#> |
Use Notice that the "Can you see me" entry appears in myarray, but not in biggestarray, because biggestarray has a copy of the original myarray values and is not affected by the change to myarray. |