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 anything; for example, a string, an integer, an array, or another structure. Because structures can contain both structures and arrays, they provide a very powerful and flexible mechanism for representing complex data.

You can use structures as associative arrays. When used as associative arrays, structures index repetitive data by string keys rather than by integers. For example, you might use structures to create an associative array that matches people's names with their departments. In this example, a structure named Departments includes an employee named John, listed in the Sales department. To access John's department, you would use the syntax, Departments["John"].

Structure notation

ColdFusion supports three types of notation for structures. Which notation you use depends on your needs:

Notation

Description

Object.property
Use to refer to values in a structure. 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"] or depts["John Doe"]="Sales.".

Structure functions
Use structure functions when you cannot use the simpler syntax styles.
You must use structure functions to create and remove structures and their elements, including renaming keys. You do not need structure functions to access value data in structures or to change the values in the key value pairs.

Developing ColdFusion Applications
Handling Complex Data with Structures

Notation	Description
Object.property	Use to refer to values in a structure. 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"] or depts["John Doe"]="Sales.".
Structure functions	Use structure functions when you cannot use the simpler syntax styles. You must use structure functions to create and remove structures and their elements, including renaming keys. You do not need structure functions to access value data in structures or to change the values in the key value pairs.