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]="Fourth Array Element">
<cfdump var=#myArray#>

Creating arrays

In ColdFusion, you can create arrays explicitly, by using a function to declare the array and then assigning it data, or implicitly by using an assignment statement. You can create simple or complex, multidimensional arrays.

Creating arrays using functions

To create an array explicitly, you use the arrayNew function and specify the array dimensions, as in the following example:

<cfset myNewArray=ArrayNew(2)>

This line creates a two-dimensional array named myNewArray. You use this method to create an array with up to three dimensions.

After you create an array, you add array elements, which you can then reference by using the element indexes.

For example, suppose you create a one-dimensional 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 arrays implicitly

To create an array implicitly, you do not use the ArrayNew function. Instead, you use a new variable name on the left side of an assignment statement, and array notation on the right side of the statement, as in the following example:

<cfset firstnameImplicit=["Coleman","Charlie","Dexter"]>

This single statement is equivalent to the four statements used to create the firstname array in Creating arrays using functions.

When you create an array implicitly, the right side of the assignment statement has square brackets ([]) surrounding the array contents and commas separating the individual array elements. The elements can be literal values, such as the strings in the example, variables, or expressions. If you specify variables, do not put the variable names in quotation marks.

You can create an empty array implicitly, as in the following example:

<cfset myArray = []>

You can also create an array implicitly by assigning a single entry, as the following example shows:

<cfset chPar[1] = "Charlie">
<cfset chPar[2] = "Parker">

ColdFusion does not allow nested implicit creation of arrays, structures, or arrays and structures. Therefore, you cannot create a multidimensional array in a single implicit statement. For example, neither of the following statements is valid:

<cfset myArray = [[],[]]>
<cfset jazzmen = [["Coleman","Charlie"],["Hawkins", "Parker"]

To create a two-dimensional array, for example, use a format such as the following:

<cfset ch = ["Coleman", "Hawkins"]>
<cfset cp = ["Charlie", "Parker"]>
<cfset dg = ["Dexter", "Gordon"]>
<cfset players = [ch, cp, dg]>

You cannot use a dynamic variable when you create an array implicitly. For example, the following expression generates an error:

<cfset i="CP">
<cfset "#i#"=["Charlie","Parker"]>

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#>

Reviewing the code

The following table describes the code: