Developing ColdFusion Applications
Handling Complex Data with Structures

Basic Array Techniques

To use arrays in ColdFusion, as in other languages, you need to first declare the array, specifying its dimension. Once it is declared, you can add array elements, which you can then reference by index.

As an example, suppose you declare a 1D array called "firstname":

<cfset firstname=ArrayNew(1)>

At first, the array firstname holds no data and is of an unspecified length. Now you want to 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:

<cfset temp=ArrayLen(firstname)>

<!--- temp=3 --->

If you remove data from an array, the array resizes dynamically. Use the ArrayDeleteAt function to delete data from the array at a particular index, rather than set the data value to 0 or the empty string:

<cfset temp=ArrayDeleteAt(firstname, 2)>

<!--- "Charlie" has been removed from the array --->



<cfoutput>

  The firstname array is #ArrayLen(firstname)# 

  indexes in length

</cfoutput>



<!--- Now the array has a length of 2, not 3 --->

The array now contains:

firstname[1]=Coleman

firstname[2]=Dexter

Creating an array

In ColdFusion, you declare an array by assigning a variable name to the new array 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 created, you can add data to the array, in this case using a form variable:

<cfset mynewarray[4]=Form.emailaddress>

Creating multidimensional arrays

ColdFusion supports dynamic multidimensional arrays. When you declare an array with the ArrayNew function, you can specify up to three dimensions. However, you can increase an array's dimensions by nesting arrays as array elements:

<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]="reality">



<cfset biggestarray=ArrayNew(3)>

<cfset biggestarray[3][1][1]=biggerarray>

<cfset biggestarray[3][1][1][2][3][1]="This is complex">

Adding elements to an array

You can add elements to an array by defining the value of an array element:

<cfset myarray[5]=form.variable>

But you can also use a number of array functions to add data to an array. You can use the following functions:

Function	Description
ArrayAppend	Creates a new array index at the end of the array
ArrayPrepend	Creates a new array index at the beginning of the array
ArrayInsertAt	Inserts an array index and data

When you insert an array index with ArrayInsertAt, all indexes to the right of the new index are recalculated to reflect the new index count.

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

Referencing elements in dynamic arrays

In ColdFusion, array indexes are counted starting with position 1, which means that position 1 is referenced as firstname[1].

Now you can add to the current firstname array example. For 2D arrays, you reference an index by specifying two coordinates: myarray[1][1].

<!--- This example adds a 1D array to a 1D array --->

<!--- Declare two one-dimensional arrays for the first and last names --->

<cfset firstname=arraynew(1)>

<cfset lastname=arraynew(1)>



<!--- Assign first names directly to the firstname array --->

<cfset firstname[1]="Coleman">

<cfset firstname[2]="Charlie">

<cfset firstname[3]="Dexter">



<!--- Declare the full name array --->

<cfset fullname=arraynew(1)>



<!--- Add the firstname array to index 1 and the lastname array to 

      index 2 of the fullname array --->

<cfset fullname[1]=firstname>

<cfset fullname[2]=Lastname>



<!--- Add the last names using reference to the fullname array --->



<cfset fullname[2][1]="Hawkins">

<cfset fullname[2][2]="Parker">

<cfset fullname[2][3]="Gordon">



<cfoutput>

  #fullname[1][1]# #fullname[2][1]#<br>

  #fullname[1][2]# #fullname[2][2]#<br>

  #fullname[1][3]# #fullname[2][3]#<br>

  #fullname[1][1]# #fullname[2][3]#<br>

</cfoutput>

Note that because this is a full 2D array, you can easily output names that do not make sense in the real world.

Additional referencing methods

You can reference array indexes in the standard way: myarray[x] where x is the index that you want to reference. You can also use ColdFusion expressions inside the square brackets to reference an index. You can use any of the following ways of referencing an array index:

<cfset myarray[1]=expression>

<cfset myarray[1 + 1]=expression>

<cfset myarray[arrayindex]=expression>

Copyright © 2001, Macromedia Inc. All rights reserved.

---