Feature

Way back when ColdFusion 4.5 was released, the concept of structures (associative arrays to some of you) was introduced. Never one to be receptive to change - not to mention having no background in other programming languages - I shunned structures for the most part and kept on my merry way working with arrays and lists. Over the years, however, I have come to appreciate the simplicity and functionality of structures and embrace them as my favorite ColdFusion data type.

If you haven't worked with other languages such as the various flavors of C or Java, the concept of what structures are may be hard to grasp - so I hope to make it easier for you.

Like arrays and query results, structures are considered to be complex data types - as opposed to numbers or strings. Structures are made up of key/value pairs logically grouped together. For instance, the following structure contains information related to a contact:

Contact.FirstName = "Selene"
Contact.LastName = "Bainum"
Contact.EmailAddress = "selene@webtricks.com"

ColdFusion has many built-in structures that you have worked with, but may not realize: Server, Application, Session, Request, Form, URL, and Variables. So the Session structure is a logical grouping of all session information, the Application structure is a logical grouping of all application information and so on.

Structure Notations
There are two ways to access the values of structure keys: dot notation and indexed notation. You're already familiar with dot notation: Form.FieldName, Session.SessionID, Application.DSN, etc. These are all examples of structures and keys. FieldName is a key of the Form structure, SessionID is a key of the Session structure, and DSN is a key of the Application structure.

Dot notation is easy and familiar, but it has several limitations. First, the key name must be a syntactically correct ColdFusion variable name - you probably already know your form field names can't start with a number or contain spaces. Second, the name of the key must be a static value. If it's not a static value, you must use the Evaluate() function, which can be resource expensive.

Indexed notation is much more flexible: key names can start with a number and/or contain spaces and variables can be used to represent all or part of the key name without needing to use Evaluate(). With indexed notation, the key name is placed between brackets, with the left bracket being immediately to the right of the structure name. If the key is a numeric value, quotes are optional around the key name, but quotes are required for a string key name. If there are no quotes around a string key, ColdFusion will assume the value is the name of a variable and will attempt to retrieve the value of that variable to use as the key name.

For example:

Form[1] // = Form["1"]
Session["SessionID"]
varA = "DSN"
varB = 1
Request[varA] // = Request["DSN"]
Request["DSN" & varB] or Request["DSN#varB#"] // = Request["DSN1"]

Looking at indexed notations, you may notice some similarities between structures and arrays. They are, with the following notable differences:

• Structure values can be referenced by a string name or a numeric value
• Structures can only be one dimension in depth
• The keys are stored in no particular order
• Structures are passed by reference, not value

Creating/Modifying Structures
It isn't always necessary to create a new empty structure before adding keys to it, but it's a good idea because there are times when it's required. To create an empty structure without any keys, you can use the StructNew() function or the cfparam tag in conjunction with StructNew():

<cfset Cart = StructNew() />
<cfparam name="Cart.BillingStruct" default="#StructNew()#" />

In the example above, a new empty structure called Cart will be created. Notice that StructNew() uses no arguments. If the structure already existed, it will be overwritten with the empty structure. Using cfparam, however, the new empty structure of Cart.BillingStruct will only be created if it doesn't already exist. Both methods are very useful, depending on your desired results.

If you've worked with any of the built-in ColdFusion data types, you have already set and modified the key/value pairs of structures. Using dot or indexed notation, you can easily set and update values of structure keys:

<cfset Application.DSN = "mydb" />
<cfset Cart["CCNum"] = "xxxx" />
<cfparam name="Cart.ExpDate" default="12/06" />

In the examples above, the structure will be created if it doesn't already exist, the key will be added if it isn't there already and the value of the key will be set. If the key already existed, its value will be overwritten with the new value.

Working with Structures
There are many structure functions that are quite useful when working with structures.

As you already know, ColdFusion has many decision functions, and several work with just structures. The IsStruct() function can be used to determine if an object is a structure or not:

<cfscript>
    Cart = StructNew();
    BillingFirstName = "Selene";
    Test1 = IsStruct(Cart); // returns "yes"
    Test2 = IsStruct(BillingFirstName); // returns "no"
</cfscript>

The StructIsEmpty() function can be used to determine whether or not a structure contains any keys:

<cfscript>
    Cart = StructNew();
    BillingStruct.FirstName = "Selene";
    ShippingFirstName = "Dave";
    Test1 = StructIsEmpty(Cart); // returns "yes"
    Test2 = StructIsEmpty(BillingStruct); // returns "no"
    Test3 = StructIsEmpty(ShippingFirstName); // error
</cfscript>

The values of Test1 and Test2 aren't surprising. However, setting the value of Test3 will return an error because the object being passed to the function isn't a structure.

You're probably very familiar with the IsDefined() function to test for the existence of an object in ColdFusion. The variable passed in can be of any data type, so the function is extremely useful. There's also a function called StructKeyExists() that's used only to test the existence of a key in a particular structure:

<cfscript>
    Cart = StructNew();
    BillingStruct.FirstName = "Selene";
    ShippingFirstName = "Dave";
    Test1 = StructKeyExists(Cart, "CCNum"); // returns "no"
    Test2 = StructKeyExists(BillingStruct, "FirstName"); // returns "yes"
    Test3 = StructIsEmpty(ShippingFirstName); // error
</cfscript>

Again, the setting of Test3 will return an error because ShippingFirstName isn't a structure.