Structures Defined

Like arrays, structures are complex variables capable of holding multiple values simultaneously. One of the big differences between structures and arrays is that arrays are ordered, whereas structures are not. Another major difference is that while arrays are indexed, structures are accessed by a key. A key is more flexible than an array index because it can be any combination of numbers, letters, or special characters.

When to Use Structures

Almost any ColdFusion task could be accomplished without structures, but the programming logic would not be as readable or concise. Structures can improve your code by allowing you to group related data cleanly and easily.

• Data made up of multiple parts (a user record, for example) is ideally suited for storage as a structure.

• Any time that related data must be passed to a custom tag or user-defined function, it may be passed as a structure (allowing a single value to be passed even though it may contain multiple values).

• Within ColdFusion itself, many special variables are exposed as structures.

Creating and Populating Structures

Structures are created using the StructNew() function, as seen here:

 <cfset user=StructNew()> 

After you create the structure, you may specify members. Structure members are made up of a key (the name) and a value. There are two ways to refer to structure members. The first is dot notation (sometimes called object/property syntax):

 <cfset user.FirstName="Ben"> <cfset user.LastName="Forta"> <cfset user.age="21"> <cfset user.email="[e-mail]"> 

The alternative syntax places the key name in brackets (this is sometimes known as array syntax):

 <cfset user["FirstName"]="Ben"> <cfset user["LastName"]="Forta"> <cfset user["age"]="21"> <cfset user["email"]="[e-mail]"> 

As a rule, dot notation is easier, but using brackets has one important benefitit allows the use of names that contain invalid characters. For example, the following creates keys with spaces in their names, which would not be possible using dot notation:

 <cfset user=StructNew()> <cfset user["First Name"]="Ben"> <cfset user["Last Name"]="Forta"> 

NOTE

Creating a variable with a period in it actually creates a structure with a member. For example, <cfset user.FirstName="Ben"> would assign the value Ben to the structure member FirstName, and would also create the structure user if it did not already exist.

Using Structures

Structure members may be used like any other variables, simply by referring to their key names. For example, the following creates an email link that displays a user's first and last name:

 <cfoutput> <a href="mailto:#user.email#">#user.FirstName# #user.LastName#</a> </cfoutput> 

As you can see, structure members may be accessed using dot notation.

In addition, ColdFusion provides an entire set of structure-manipulation functions (the names of which all begin with Struct) for more advanced structure processing. StructFind() uses the names of a structure and key to return a value:

 E-Mail: #StructFind(user, "email")# 

Other functions can check for the existence of keys, sort keys, return a list of key names, add and delete keys, and more.

TIP

Many of the Struct functions are not that useful for simple structures (the type used here), but are invaluable for more complex nested structures.