This section explains how to create and use structures in ColdFusion. The sample code in this section uses a structure called employee, which is used to add new employees to a corporate information system.

Creating structures

In ColdFusion, you can create structures explicitly by using a function, and then populate the structure using assignment statements or functions, or you can create the structure implicitly by using an assignment statement.

Creating structures using functions

You can create structures by assigning a variable name to the structure with the StructNew function as follows:

<cfset structName = StructNew()>

For example, to create a structure named departments, use the following syntax:

<cfset departments = StructNew()>

This creates an empty structure to which you can add data.

Creating structures implicitly

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

<cfset myStruct = {}>

You can also create a structure by assigning data to a variable. For example, each of the following lines creates a structure named myStruct with one element, name, that has the value Adobe Systems Incorporated.

<cfset coInfo.name = "Adobe Systems Incorporated">
<cfset coInfo["name"] = "Adobe Systems Incorporated">
<cfset coInfo = {name = "Adobe Systems Incorporated"}>

When you use structure notation to create a structure, as shown in the third example, you can populate multiple structure fields. The following example shows this use:

<cfset coInfo={name="Adobe Systems Incorporated", industry="software"}

ColdFusion does not allow nested implicit creation of structures, arrays, or structures and arrays. The following line, for example, generates an error:

<cfset myStruct = {structKey1 = {innerStructKey1 = "innerStructValue1"}}>

Similarly, you cannot use object.property notation on the left side of assignments inside structure notation. The following statement, for example, causes an error:

<cfset myStruct={structKey1.innerStructKey1 = "innerStructValue1"}>

Instead of using these formats, you must use multiple statements, such as the following:

<cfset innerStruct1 = {innerStructKey1 = "innerStructValue1"}
<cfset myStruct1={structKey1 = innerStruct1}>

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

<cfset i="coInfo">
<cfset "#i#"={name = ""Adobe Systems Incorporated"}>

Adding and updating structure elements

You add or update a structure element to a structure by assigning the element a value or by using a ColdFusion function. It is simpler and more efficient to use direct assignment.

You can add structure key-value pairs by defining the value of the structure key, as the following example shows:

<cfset myNewStructure.key1="A new structure with a new key">
<cfdump var=#myNewStructure#>
<cfset myNewStructure.key2="Now I've added a second key">
<cfdump var=#myNewStructure#>

The following code uses cfset and object.property notation to create a structure element called departments.John, and changes John's department from Sales to Marketing. It then uses associative array notation to change his department to Facilities. Each time the department changes, it displays the results:

<cfset departments=structnew()>
<cfset departments.John = "Sales">
<cfoutput>
    Before the first change, John was in the #departments.John# Department<br>
</cfoutput>
<cfset Departments.John = "Marketing">
<cfoutput>
    After the first change, John is in the #departments.John# Department<br>
</cfoutput>
<cfset Departments["John"] = "Facilities">
<cfoutput>
    After the second change, John is in the #departments.John# Department<br>
</cfoutput>

Getting information about structures and keys

You use ColdFusion functions to find information about structures and their keys.

Getting information about structures

To find out if a given value represents a structure, use the IsStruct function, as follows:

IsStruct(variable)

This function returns True if variable is a ColdFusion structure. (It also returns True if variable is a Java object that implements the java.util.Map interface.)

Structures are not indexed numerically, so to find out how many name-value pairs exist in a structure, use the StructCount function, as in the following example:

StructCount(employee)

To discover whether a specific Structure contains data, use the StructIsEmpty function, as follows:

StructIsEmpty(structure_name)

This function returns True if the structure is empty, and False if it contains data.

Finding a specific key and its value

To determine whether a specific key exists in a structure, use the StructKeyExists function, as follows:

StructKeyExists(structure_name, "key_name")

Do not put the name of the structure in quotation marks, but you do put the key name in quotation marks. For example, the following code displays the value of the MyStruct.MyKey only if it exists:

<cfif StructKeyExists(myStruct, "myKey")>
    <cfoutput> #mystruct.myKey#</cfoutput><br>
</cfif>

You can use the StructKeyExists function to dynamically test for keys by using a variable to represent the key name. In this case, you do not put the variable in quotation marks. For example, the following code loops through the records of the GetEmployees query and tests the myStruct structure for a key that matches the query's LastName field. If ColdFusion finds a matching key, it displays the Last Name from the query and the corresponding entry in the structure.

<cfloop query="GetEmployees">
<cfif StructKeyExists(myStruct, LastName)>
    <cfoutput>#LastName#: #mystruct[LastName]#</cfoutput><br>
</cfif>
</cfloop>

If the name of the key is known in advance, you can also use the ColdFusion IsDefined function, as follows:

IsDefined("structure_name.key")>

However, if the key is dynamic, or contains special characters, you must use the StructKeyExists function.

Getting a list of keys in a structure

To get a list of the keys in a CFML structure, you use the StructKeyList function, as follows:

<cfset temp=StructKeyList(structure_name, [delimiter])>

You can specify any character as the delimiter; the default is a comma.

Use the StructKeyArray function to returns an array of keys in a structure, as follows:

<cfset temp=StructKeyArray(structure_name)>