Structures: The Basics of CF-Based Structures
by Dan G. Switzer, II | 10/12/1999

Structures are a new class of variables just introduced in ColdFusion v4. Much like associative arrays, they allow you to build an array that's based upon a string, called a "key". Normal arrays are based upon an integer value. Using a string based value has several advantages, including ease of reading.

Creating a structure is easy. To create a new structure use the structNew() function. Let's create a structure where we'll store information about an object.

Source Code

<cfset stObject = structNew()>

There are several methods to insert new keys into the structure. Listed below are the different possible methods in which we can declare a new key and it's value.

Method 1:
<cfset tmp = structInsert(structure, "key", "value", [allowoveride])>
Method 2:
<cfset structure["key"] = "value"> <-- Prefered method
Method 3:
<cfset structure.key = "value">

Each method has it's own advantages/disadvantages, but the method I prefer is "Method 2". There are several reasons I prefer using this method. First, this operation will either insert or update an existing key. Second, you can dynamically calculate the keys name. Last, but not least, it's much easier to read then using the structInsert() method.

Now that we know how to create a new key in the structure, let's add some keys to our object:

Source Code

<cfset stObject["Name"] = "ball"> <cfset stObject["Shape"] = "round"> <cfset stObject["Color"] = "red"> <cfset stObject["Size"] = "large">

Now that we've declared some keys for are structure, we might need to check to see what keys are available. To do that we use the structKeyList() or structKeyArray() functions. For our purposes, we'll use the structKeyList() function.

Source Code

<cfoutput>#structKeyList(stObject)#</cfoutput>

Output

SIZE,NAME,SHAPE,COLOR

Just as there are several ways to declare a new key, there are also several ways to display an existing key. Any of the following methods will display the value contained within the key specified:

Method 1:
#structFind(structure, "key")#
Method 2:
#structure["key"]# <-- Prefered method
Method 3:
#structure.key#

Once again, there are advantages/disadvantages to all methods, but my favorite is the second method. Method 2 will almost always met your needs.

Now that we now how to list our keys and display the values for the keys, let's create a loop that goes through all the keys in a structure and outputs the results to the screen.

Source Code

<cfloop index="key" list="#structKeyList(stObject)#"> <cfoutput>#stObject[key]#</cfoutput><br /> </cfloop>

Output

large ball round red

One of the nice things about structures, is if you declare a new variable equal to an existing structure, the new structure will contain a pointer to the existing structure. This opens up all sorts of possibilities when creating an application that may have several different settings based upon the current action the user is taking.

Let's create a pointer to our existing object:

Source Code

<cfset stBall = stObject>

Now that we have created the pointer, we can reference the properties of the new pointer, by doing the following:

Source Code

<cfoutput>#stBall["Color"]#</cfoutput>

Output

red

Now it's important to note that "pointers" are exactly that, a reference to the original variable, they are not copies of the variable. This means by changing the content an existing key in the "stObject" structure (or adding a new key,) I also change the value of the "stBall" structure. Let's see how this works if I change the color from "red" to "blue":

Source Code

<cfset stObject["Color"] = "blue"> <cfoutput>#stBall["Color"]#</cfoutput>

Output

blue

As you can see, even though we changed the value of the "stObject" since the "stBall" is a pointer to the "stObject" it reflects the change we made to the original object.

Now, let's take an identical copy of the "stObject" that is not a pointer. At this point in time we want to simply take a "snapshot" of the "stObject" and store it in the "stBall" structure. To do that, we'll use the duplicate() function.

Source Code

<cfset stBall = duplicate(stObject)>

Now that we've made a copy of the object, let's try changing the "color" of the stObject structure back to "red" to see what happens:

Source Code

<cfoutput>stBall["Color"]: #stBall["Color"]#</cfoutput><br /> <cfoutput>stObject["Color"]: #stObject["Color"]#</cfoutput><br /> <cfset stObject["Color"] = "red"> <cfoutput>stBall["Color"]: #stBall["Color"]#</cfoutput><br /> <cfoutput>stObject["Color"]: #stObject["Color"]#</cfoutput><br />

Output

stBall["Color"]: blue stObject["Color"]: blue stBall["Color"]: blue stObject["Color"]: red

As you can see now that the "stBall" is no longer a pointer to the original structure, the changes to the original structure have no effect on the "stBall" structure.

You should now understand the basics of how structures work. Part 2 of this tutorial covers more advanced methods for using structures.

If you have any questions about this article, please feel free to contact the author at dswitzer@pengoworks.com.