Complex data types



Arrays, structures, and queries are ColdFusion built-in complex data types. Structures and queries are sometimes referred to as objects, because they are containers for data, not individual data values.

For details on using arrays and structures, see Using Arrays and Structures.

Arrays

Arrays are a way of storing multiple values in a table-like format that can have one or more dimensions. You create arrays using a function or an assignment statement:

  • The ColdFusion ArrayNew function creates an array and specifies its initial dimensions. For example, the following line creates an empty two-dimensional array:

    <cfset myarray=ArrayNew(2)>

  • A direct assignment creates an array and populates an array element. For example, the following line creates a two-dimensional array and sets the value of row 1 column 2 to the current date.

    <cfset myarray[1][2]=Now()>

You reference elements using numeric indexes, with one index for each dimension, as shown in the preceding example.

You can create arrays with up to three dimensions directly. However, there is no limit on array size or maximum dimension. To create arrays with more than three dimensions, create arrays of arrays.

After you create an array, you can use functions or direct references to manipulate its contents.

When you assign an 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 a copy of the original array:

<cfset newArray=myArray>

For more information on using arrays, see Using Arrays and Structures.

Structures

ColdFusion structures consist of key-value pairs, where the keys are text strings and the values can be any ColdFusion data type, including other structures. Structures let you build a collection of related variables that are grouped under a single name. To create a structure, use the ColdFusion StructNew function. For example, the following line creates a new, empty, structure called depts:

<cfset depts=StructNew()>

You can also create a structure by assigning a value in the structure. For example, the following line creates a new structure called MyStruct with a key named MyValue, equal to 2:

<cfset MyStruct.MyValue=2>
Note: In ColdFusion versions through ColdFusion 7, this line created a Variables scope variable named "MyStruct.MyValue" with the value 2.

After you create a structure, you can use functions or direct references to manipulate its contents, including adding key-value pairs.

You can use either of the following methods to reference elements stored in a structure:

  • StructureName.KeyName

  • StructureName["KeyName"]

The following examples show these methods:

depts.John="Sales" 
depts["John"]="Sales"

When you assign an existing structure to a new variable, ColdFusion does not create a new structure. Instead, the new variable accesses the same data (location) in memory as the original structure variable. In other words, both variables are references to the same object.

For example, the following line creates a new variable, myStructure2, that is a reference to the same structure as the myStructure variable:

<cfset myStructure2=myStructure>

When you change the contents of myStructure2, you also change the contents of myStructure. To copy the contents of a structure, use the ColdFusion Duplicate function, which copies the contents of structures and other complex data types.

Structure key names can be the names of complex data objects, including structures or arrays. This lets you create arbitrarily complex structures.

For more information on using structures, see Using Arrays and Structures.

Queries

A query object, sometimes referred to as a query, query result, or recordset, is a complex ColdFusion data type that represents data in a set of named columns, like the columns of a database table. Many tags can return data as a query object, including the following:

In these tags, the name attribute specifies the query object’s variable name. The QueryNew function also creates query objects.

When you assign a query to a new variable, ColdFusion does not copy the query object. Instead, both names point to the same recordset data. For example, the following line creates a new variable, myQuery2, that references the same recordset as the myQuery variable:

<cfset myQuery2 = myQuery>

If you make changes to data in myQuery, myQuery2 also shows those changes.

You reference query columns by specifying the query name, a period, and the column name; for example:

myQuery.Dept_ID

When you reference query columns inside tags, such as cfoutput and cfloop, in which you specify the query name in a tag attribute, you do not have to specify the query name.

You can access query columns as if they are one-dimensional arrays. For example, the following line assigns the contents of the Employee column in the second row of the myQuery query to the variable myVar: 

<cfset myVar = myQuery.Employee[2]>
Note: You cannot use array notation to reference a row (of all columns) of a query. For example, myQuery[2] does not reference the second row of the myQuery query object.

Working with structures and queries

Because structure variables and query variables are references to objects, the rules in the following sections apply to both types of data.

Multiple references to an object

When multiple variables reference a structure or query object, the object continues to exist as long as at least one reference to the object exists. The following example shows how this works: 

<cfscript> depts = structnew();</cfscript> 
<cfset newStructure=depts> 
<cfset depts.John="Sales"> 
<cfset depts=0> 
<cfoutput> 
    #newStructure.John#<br> 
    #depts# 
</cfoutput>

This example displays the following output:

Sales

0

After the <cfset depts=0> tag executes, the depts variable does not reference a structure; it is a simple variable with the value 0. However, the variable newStructure still refers to the original structure object.

Assigning objects to scopes

You can give a query or structure a different scope by assigning it to a new variable in the other scope. For example, the following line creates a server variable, Server.SScopeQuery, using the local myquery variable:

<cfset Server.SScopeQuery = myquery>

To clear the server scope query variable, reassign the query object, as follows:

<cfset Server.SScopeQuery = 0>

This line deletes the reference to the object from the server scope, but does not remove any other references that can exist.

Copying and duplicating objects

You can use the Duplicate function to make a true copy of a structure or query object. Changes to the copy do not affect the original.

Using a query column

When you are not inside a tag such as cfloop, cfoutput, or cfmail that has a query attribute, you can treat a query column as an array. However, query column references do not always behave as you might expect. This section explains the behavior of references to query columns using the results of the following cfquery tag in its examples:

<cfquery dataSource="cfdocexamples" name="myQuery"> 
    SELECT FirstName, LastName 
    FROM Employee 
</cfquery>

To reference elements in a query column, use the row number as an array index. For example, both of the following lines display the word "ben":

<cfoutput> #myQuery.Firstname[1]# </cfoutput><br> 
<cfoutput> #myQuery["Firstname"][1]# </cfoutput><br>

ColdFusion behavior is less straightforward, however, when you use the query column references myQuery.Firstname and myQuery["Firstname"] without using an array index. The two reference formats produce different results.

If you reference myQuery.Firstname, ColdFusion automatically converts it to the first row in the column. For example, the following lines print the word "ben":

<cfset myCol = myQuery.Firstname > 
<cfoutput>#mycol#</cfoutput>

But the following lines display an error message:

<cfset myCol = myQuery.Firstname > 
<cfoutput>#mycol[1]#</cfoutput><br>

If you reference Query["Firstname"], ColdFusion does not automatically convert it to the first row of the column. For example, the following line results in an error message indicating that ColdFusion cannot convert a complex type to a simple value:

<cfoutput> #myQuery['Firstname']# </cfoutput><br>

Similarly, the following lines print the name "marjorie", the value of the second row in the column:

<cfset myCol = myQuery["Firstname"]> 
<cfoutput>#mycol[2]#</cfoutput><br>

However, when you make an assignment that requires a simple value, ColdFusion automatically converts the query column to the value of the first row. For example, the following lines display the name "ben" twice:

<cfoutput> #myQuery.Firstname# </cfoutput><br> 
<cfset myVar= myQuery['Firstname']> 
<cfoutput> #myVar# </cfoutput><br>