Basic array techniques

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 firstname1. For 2D arrays, you reference an index by specifying two coordinates: myarray11.
You can use ColdFusion variables and expressions inside the brackets to reference an index, as the following example shows:

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:

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:

The array firstname holds no data and is of an unspecified length. Next you add data to the array:

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:

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:

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

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:

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

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

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.

Reviewing the code

The following table describes the code:

Using implicitly created arrays

You can use implicitly created arrays directly in functions (including user-defined functions) and tags. For example, the following code uses two implicit arrays, one in a ColdFusion function, the other in a user-defined function:

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:

If an element does not exist at the specified index, ColdFusion creates it. If an element 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. 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.

Adding an array element with a function

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

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.

For more information about these array functions, see the 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:

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 array first. When you assign the existing array to a new variable, ColdFusion creates an array and copies the contents of the old array 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.

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:

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.