About structures

ColdFusion structures consist of key-value pairs. Structures let you build a collection of related variables that are grouped under a single name. You can define ColdFusion structures dynamically.

You can use structures to refer to related values as a unit, rather than individually. To maintain employee lists, for example, you can create a structure that holds personnel information such as name, address, phone number, ID numbers, and so on. Then you can refer to this collection of information as a structure called employee rather than as a collection of individual variables.

A structure's key must be a string. The values associated with the key can be any valid ColdFusion value or object. It can be a string or integer, or a complex object such as an array or another structure. Because structures can contain any kind of data they provide a very powerful and flexible mechanism for representing complex data.

Structure notation

ColdFusion supports two types of notation for referencing structure contents. Which notation you use depends on your requirements:
Notation
Description
Object.property
You can refer to a property, prop, of an object, obj, as obj.prop. This notation is useful for simple assignments, as in this example:
depts.John="Sales"
Use this notation only when you know the property names (keys) in advance and they are strings, with no special characters, numbers, or spaces. You cannot use the dot notation when the property, or key, is dynamic.
Associative arrays
If you do not know the key name is in advance, or it contains spaces, numbers or special characters, you can use associative array notation. This notation uses structures as arrays with string indexes, for example,
depts["John"]="Sales"
depts[employeeName]="Sales"
You can use a variable (such as employeeName) as an associative array index. Therefore, you must enclose any literal key names in quotes.
For information on using associative array references containing variables, see "Dynamically constructing structure references," in Chapter 4.

Referencing complex structures

When a structure contains another structure, you reference the data in the nested structure by extending either object.property or associative array notation. You can even use a mixture of both notations.

For example, if structure1 has a key key1 whose value is a structure that has keys struct2key1, struct2key2, and so on, you can use any of the following references to access the data in the first key of the embedded structure:

Structure1.key1.Struct2key1
Structure1["key1"].Struct2key1
Structure1.key1["Struct2key1"]
Structure1["key1"]["Struct2key1"]

The following example shows various ways you can reference the contents of a complex structure:

<cfset myArray=ArrayNew(1)>
<cfset myArray[1]="2">
<cfset myArray[2]="3">
<cfset myStruct2=StructNew()>
<cfset myStruct2.struct2key1="4">
<cfset myStruct2.struct2key2="5">
<cfset myStruct=StructNew()>
<cfset myStruct.key1="1">
<cfset myStruct.key2=myArray>
<cfset myStruct.key3=myStruct2>
<cfdump var=#myStruct#><br>

<cfset key1Var="key1">
<cfset key2Var="key2">
<cfset key3Var="key3">
<cfset var2="2">

<cfoutput>
Value of the first key<br>
#mystruct.key1#<br>
#mystruct["key1"]#<br>
#mystruct[key1Var]#<br>
<br>
Value of the second entry in the key2 array<br>
#myStruct.key2[2]#<br>
#myStruct["key2"][2]#<br>
#myStruct[key2Var][2]#<br>
#myStruct[key2Var][var2]#<br>
<br>
Value of the struct2key2 entry in the key3 structure<br>
#myStruct.key3.struct2key2#<br>
#myStruct["key3"]["struct2key2"]#<br>
#myStruct[key3Var]["struct2key2"]#<br>
#myStruct.key3["struct2key2"]#<br>
#myStruct["key3"].struct2key2#<br>
<br>
</cfoutput>

Reviewing the code

The following table describes the code:
Code
Description
<cfset myArray=ArrayNew(1)>
<cfset myArray[1]="2">
<cfset myArray[2]="3">
<cfset myStruct2=StructNew()>
<cfset myStruct2.struct2key1="4">
<cfset myStruct2.struct2key2="5">
<cfset myStruct=StructNew()>
<cfset myStruct.key1="1">
<cfset myStruct.key2=myArray>
<cfset myStruct.key3=myStruct2>
Create a structure with three entries: a string, an array, and an embedded structure.
<cfdump var=#myStruct#><br>
Display the complete structure.
<cfset key1Var="key1">
<cfset key2Var="key2">
<cfset key3Var="key3">
<cfset var2="2">
Create variables containing the names of the myStruct keys and the number 2.
<cfoutput>
Value of the first key<br>
#mystruct.key1#<br>
#mystruct["key1"]#<br>
#mystruct[key1Var]#<br>
<br>
Output the value of the structure's key1 (string) entry using the following notation:
  • object.property notation
  • associative array notation with a constant
  • associative array notation with a variable
Value of the second entry in the
key2 array<br>
#myStruct.key2[2]#<br>
#myStruct["key2"][2]#<br>
#myStruct[key2Var][2]#<br>
#myStruct[key2Var][var2]#<br>
<br>
Output the value of the second entry in the structure's key2 array using the following notation:
  • object.property notation
  • associative array notation with a constant
  • associative array notation with a variable
  • associative array notation with variables for both the array and the array index
Value of the struct2key2 entry in
the key3 structure<br>
#myStruct.key3.struct2key2#<br>
#myStruct["key3"]["struct2key2"]#<br>
#myStruct[key3Var]["struct2key2"]#<br>
#myStruct.key3["struct2key2"]#<br>
#myStruct["key3"].struct2key2#<br>
<br>
</cfoutput>
Output the value of second entry in the structure's key3 embedded structure using the following notation:
  • object.property notation
  • associative array notation with two constants
  • associative array notation with a variable and a constant
  • object.property notation followed by associative array notation
  • associative array notation followed by object.property notation

Comments