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 and using 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 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 place 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 the number of 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 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]=myotherarray> 
<cfset biggerarray[2][1][1][4][2]="five deep">

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]=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 a copy of the biggerarray array, and assign element [3][1][1][2][3][1].

The resulting array is 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 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 the change to myarray does not affect it.