Structures

Structures are similar to the data types that we've discussed to this point, and they are quite similar to arrays. The main difference is that a value within a structure is not identified by an index. However, it can be called by name.

ColdFusion structures utilize familiar dot notation, such as MyStructure.Name, to identify a structure name and key. This type of identification is much more manageable in an application setting where you need to be able to associate a variable name with its value. Believe me, you can easily get lost in the index numbers and values of an array.

One structure that is typical to ColdFusion applications is the form. When you submit a form, you pass key/value pairs to the action page. The form structure keys are represented by the form control names and the values are those associated with each form control. These values are stored in a structure called form. I'm sure that you're familiar with outputting variables such as form.name, form.address, and form.email. You might not have known it, but you were outputting values from a structure.

Creating a Structure

It's easy to create a structure in ColdFusion. Structures are created by using the StructNew() function. The function call does not require any additional parameters. Let's stay with our authors and email theme for a bit longer and try the following code:

 <cfset st_AuthorData=StructNew()>

There's nothing more to it than that.

Adding Elements to a Structure

After you have created a structure, it remains empty until you add data to it. There are different ways to add data to a structure. These methods vary in the syntax technique that is used:

Dot notation syntax. This is probably the easiest notation method to read. You simply refer to the structure name and then to the key name:
```
 <cfset st_AuthorData.FullName="Neil Ross"> 
```
Function syntax. Using the StructInsert() function, you can add keys and values to the specified structure. One advantage of this method is that it does not enable you to overwrite an existing key/value pair without adding additional parameters to the function call:
```
 <cfset tmp=StructInsert(st_AuthorData, "Email", "neil@codesweeper.com")> 
```
Associative array syntax. ColdFusion structures are sometime referred to as associative arrays. The syntax is similar to a reference to an array, with the exception that the index number is replaced with a reference to the key name string:
```
 <cfset st_AuthorData["City"]="Mechanicsburg"> 
```

Let's look at some real code that shows what you've learned so far about structures and that employs each method of adding data:

 <cfset st_AuthorData=StructNew()>  <cfset st_AuthorData.FullName="Neil Ross">  <cfset tmp=StructInsert(st_AuthorData, "Email", "neil@codesweeper.com")>  <cfset st_AuthorData["City"]="Mechanicsburg">

Now let's dump this structure and check out how it differs from an array or query object:

 <cfdump var="#st_AuthorData#">

Outputting a Structure

Outputting a structure key value is simple. You just use the dot notation that we looked at earlier to specify the structure and key:

 Name: <cfoutput>#st_AuthorData.FullName#</cfoutput>

Now let's put it all together in Listing 7.7 and see what you've learned:

Listing 7.7 Outputting AuthorData Structure

 <html>  <head>       <title>Inside ColdFusion MX - Structures</title>  </head>  <body>  <table>       <tr>            <td>            <!--- Create the structure --->                 <cfset st_AuthorData=StructNew()>            <!--- Set structure key/value pairs --->                 <cfset st_AuthorData.FullName="Neil Ross">                 <cfset st_AuthorData.Email="neil@codesweeper.com">                 <cfset st_AuthorData.City="Mechanicsburg">                 <cfset st_AuthorData.State="Pennsylvania">                 <cfset st_AuthorData.FavoriteTeam="Arkansas Razorbacks">            <!--- Dump the structure because we can --->                 <cfdump var="#st_AuthorData#">                 <br>                 <br>            <!--- Output the structure --->                 <cfoutput>                      The author's name is: #st_AuthorData.FullName#<br>                      He can be reached by email at: #st_AuthorData.Email#<br>                      He currently resides in: #st_AuthorData.City#,  #st_AuthorData.State#<br>                      His favorite team is: #st_AuthorData.FavoriteTeam#                 </cfoutput>            </td>       </tr>  </table>  </body>  </html>

Figure 7.8 shows what the template generates in a browser.

Figure 7.8. `AuthorData` structure in a browser.

graphics/07fig08.gif

If you need to loop through the entire structure and output all the key values, you'll want to code a collection loop. A collection loop loops over a component object model (COM) collection or a ColdFusion structure. It's similar to the simple index loop that we did for the one-dimensional array. Let's take a look at the syntax:

 <cfloop collection="structure_name" item="key">        <cfoutput>code code code</cfoutput>  </cfloop>

The collection attribute names the structure through which your code will loop. The item attribute identifies the variable that holds the values, or keys of the structure, through which you want to loop. Examine the following code, which demonstrates the use of a collection loop to output the key/value pairs in the st_AuthorData structure:

 <cfset st_AuthorData=StructNew()>  <cfset st_AuthorData.FullName="Neil Ross">  <cfset st_AuthorData.Email="neil@codesweeper.com">  <cfset st_AuthorData.City="Mechanicsburg">  <cfloop collection="#st_AuthorData#" item="key">        <cfoutput>               #key# - #StructFind(st_AuthorData,key)#          </cfoutput><br>  </cfloop>

Structure Functions

Once again, ColdFusion gives us a number of native functions to manipulate our structures:

`StructNew`	`IsStruct`	`StructClear`
`Duplicate`	`StructCount`	`StructGet`
`StructKeyList`	`StructDelete`	`StructInsert`
`StructAppend`	`StructFind`	`StructIsEmpty`
`StructSort`	`StructFindKey`	`StructKeyArray`
`StructUpdate`	`StructCopy`	`StructFindValue`
`StructKeyExists`

Popular structure functions include the following:

IsStruct(). Checks whether the variable is a structure and returns Yes or No :
```
 <cfset tmp=IsStruct(st_AuthorData)> 
```
StructClear(). Removes all the data from the structure, but does not delete it:
```
 <cfset StructClear(st_AuthorData)> 
```
StructDelete(). Deletes the specified key from the specified structure. This function requires that you provide the structure name and key name:
```
 <cfset StructDelete(st_AuthorData, "City"> 
```
StructFind(). Returns the value of the specified structure key:
```
 <cfset keyvalue=StructFind(st_AuthorData, "Email")> 
```

If you're going to be using structures in your ColdFusion applications, consider all the structure functions and put together a dummy structure to run tests, as we've done in the preceding example.