Basic array techniques

The following sections describe how to reference array elements, create arrays, add and remove array elements, and copy arrays.

Referencing array elements

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. To test whether data exists at an array index, copy the array element to a simple variable and use the IsDefined function to test the existence of the copy.

Creating arrays

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 256) 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.

Creating complex multidimensional arrays

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.

Reviewing the 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 bigerarray 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]= myotherarray> <cfset biggerarray[2][1][1][4][2]= "reality">

Make element [2][1][1] of the 3D array be the 2D array and assign the [2][1][1][4][2] element the value "reality".

The biggerarray array is now even more asymmetric.

<cfset biggestarray=ArrayNew(3)> <cfset biggestarray[3][1][1] =biggerarray> <cfset biggestarray[3][1][1][2][3][1] ="This is complex">

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.

<fdump var=#biggestarray#><br> <cfdump var=#myarray#>

Use cfdump to view the structure of biggestarray and myarray.

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.

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 bigerarray 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]= myotherarray> <cfset biggerarray[2][1][1][4][2]= "reality">	Make element [2][1][1] of the 3D array be the 2D array and assign the [2][1][1][4][2] element the value "reality". The biggerarray array is now even more asymmetric.
<cfset biggestarray=ArrayNew(3)> <cfset biggestarray[3][1][1] =biggerarray> <cfset biggestarray[3][1][1][2][3][1] ="This is complex">	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.
<fdump var=#biggestarray#><br> <cfdump var=#myarray#>	Use `cfdump` to view the structure of biggestarray and myarray. 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.

Adding elements to an array

You can add an element to an array by assigning the element a value or by using a ColdFusion function.

Adding an array element by assignment

You can add elements to an array by defining the value of an array element, as shown in the following cfset tag:

<cfset myarray[5]="Test Message">

If an element does not exist at the specified index, ColdFusion creates it. If an element already exists at the specified index, ColdFusion replaces it with the new value. To prevent existing data from being overwritten, use the ArrayInsertAt function, as described in the next section.

If elements with lower-number indexes do not exist, they remain undefined. You must assign values to undefined array elements before you can use them. For example, the following code creates an array and an element at index 4. It outputs the contents of element 4, but generates an error when it tries to output the (nonexistent) element 3.

<cfset myarray=ArrayNew(1)>

<cfset myarray[4]=4>
<cfoutput>
  myarray4: #myarray[4]#<br>
  myarray3: #myarray[3]#<br>
</cfoutput>

Adding an array element with a function

You can use the following array functions to add data to an array:

Function

Description

ArrayAppend

Creates a new array element at the end of the array.

ArrayPrepend

Creates a new array element at the beginning of the array.

ArrayInsertAt

Inserts an array element at the specified index position.

Function	Description
`ArrayAppend`	Creates a new array element at the end of the array.
`ArrayPrepend`	Creates a new array element at the beginning of the array.
`ArrayInsertAt`	Inserts an array element at the specified index position.

Because ColdFusion arrays are dynamic, if you add or delete an element from the array, any higher-numbered index values all change. For example, the following code creates a two element array and displays the array contents. It then uses ArrayPrepend to insert a new element at the beginning of the array and displays the result. The data that was originally in indexes 1 and 2 is now in indexes 2 and 3.

<!--- Create an array with three elelemts --->

<cfset myarray=ArrayNew(1)>
<cfset myarray[1]="Original First Element">
<cfset myarray[2]="Original Second Element">
<!--- Use cfdump to display the array structure --->
<cfdump var=#myarray#>
<br>
<!--- Add a new element at the beginning of the array --->
<cfscript>
  ArrayPrepend(myarray, "New First Element");
</cfscript>
<!--- Use cfdump to display the new array structure --->
<cfdump var=#myarray#>

For more information about these array functions, see CFML Reference.

Deleting elements from an array

Use the ArrayDeleteAt function to delete data from the array at a particular index, instead of setting the data value to zero or an empty string. If you remove data from an array, the array resizes dynamically, as the following example shows:

<!--- Create an array with three elements --->

<cfset firstname=ArrayNew(1)>
<cfset firstname[1]="Robert">
<cfset firstname[2]="Wanda">
<cfset firstname[3]="Jane">

<!--- Delete the second element from the array --->

<cfset temp=ArrayDeleteAt(firstname, 2)>

<!--- Display the array length (2) and its two entries,
which are now "Robert" and "Jane" --->

<cfoutput>
  The array now has #ArrayLen(firstname)# indexes<br>
  The first entry is #firstname[1]#<br>
  The second entry is #firstname[2]#<br>
</cfoutput>

The ArrayDeleteAt function removed the original second element and resized the array so that it has two entries, with the second element now being the original third element.

Copying arrays

You can copy arrays of simple variables (numbers, strings, Boolean values, and date-time values) by assigning the original array to a new variable name. You do not have to use ArrayNew to create the new array first. When you assign the existing array to a new variable, ColdFusion creates a new array and copies the old array's contents to the new array. The following example creates and populates a two-element array. It then copies the original array, changes one element of the copied array and dumps both arrays. As you can see, the original array is unchanged and the copy has a new second element.

<cfset myArray=ArrayNew(1)>

<cfset myArray[1]="First Array Element">
<cfset myArray[2]="Second Array Element">
<cfset newArray=myArray>
<cfset newArray[2]="New Array Element 2">
<cfdump var=#myArray#><br>
<cfdump var=#newArray#>

If your array contains complex variables (structures, query objects, or external objects such as COM objects) assigning the original array to a new variable does not make a complete copy of the original array. The array structure is copied; however, the new array does not get its own copy of the complex data, only references to it. To demonstrate this behavior, run the following code:

Create an array that contains a structure.<br>

<cfset myStruct=StructNew()>
<cfset myStruct.key1="Structure key 1">
<cfset myStruct.key2="Structure key 2">
<cfset myArray=ArrayNew(1)>
<cfset myArray[1]=myStruct>
<cfset myArray[2]="Second array element">
<cfdump var=#myArray#><br>
<br>
Copy the array and dump it.<br>
<cfset myNewArray=myArray>
<cfdump var=#myNewArray#><br>
<br>
Change the values in the new array.<br>
<cfset myNewArray[1].key1="New first array element">
<cfset myNewArray[2]="New second array element">
<br>
Contents of the original array after the changes:<br>
<cfdump var=#myArray#><br>
Contents of the new array after the changes:<br>
<cfdump var=#myNewArray#>

The change to the new array also changes the contents of the structure in the original array.

To make a complete copy of an array that contains complex variables, use the duplicate function.

Developing ColdFusion MX Applications with CFML
Using Arrays and Structures