Until now, you’ve created structures only by using StructNew(). You can also create structures just by using dot notation, as follows:

<cfset aNewStruct.SomeKey.SomeValue = 1>

That line creates a structure named aNewStruct with a substructure named SomeKey that has an element named SomeValue with a value of 1. Notice that the names of all newly created structures and keys are all uppercase, regardless of the capitalization that you use in the code. As convenient as this method may seem, it does have a drawback. Consider the following snippet:

<cfset aNewStruct = StructNew()>
   <cfset aNewStruct.myKey = 2>
   <cfset aNewStruct.yourKey = 3>

After running the preceding snippet, two new keys, named myKey and yourKey, are created. Suppose that you now attempt to call the following snippet to create a nested structure named myKey:

<cfset aNewStruct.myKey.subKey = 4>

If the previous line had worked, it would have overwritten the previous simple value of myKey with a substructure named myKey. Fortunately, however, attempting to overwrite a simple key with a substructure throws an error in ColdFusion MX. You do face a limitation in creating structure keys by using this method. ColdFusion MX can create nested structures only up to three levels deep in a single call, as in this example:

<cfset a = StructNew()>
   <cfset a.b.c.d = “some value”>

Attempting to create a key more than three levels deep gives you unexpected results. ColdFusion ignores all but the last three keys. Running the following code, for example, outputs “some value”:

<cfset a = StructNew()>
   <cfset a.b.c.d.e.f.g = “some value”>
   <cfoutput>
   #a.e.f.g#
   </cfoutput>

You can, however, create structures nested as deeply as you want as long as you don’t attempt to go more than three levels deeper than currently exists. Sometimes data is useful only if it is sorted in a specific order. Although this is easy to do with tabular data in a database, sorting data in a structure takes a little more understanding and effort. Say that you have a structure containing the prices per pound of different fruits, as following:

<cfset FruitCosts = StructNew()>
   <cfset FruitCosts[“Oranges”] = 1.99>
   <cfset FruitCosts[“Apples”] = 1.50>
   <cfset FruitCosts[“Peaches”] = 1.75>
   <cfset FruitCosts[“Cherries”] = 2.25>
   <cfset FruitCosts[“Lemons”] = 1.65>

You can loop over these prices and output them by using the code.

<cfoutput>
   <cfloop collection=”#FruitCosts#” item=”Fruit”>
   #Fruit#: #FruitCosts[Fruit]# / lb.<br>
   </cfloop>
 </cfoutput>

The problem here is that structures don’t have any kind of inherent order. Structure keys are stored in an internal order that only ColdFusion Server understands, and if you loop over the structure, that’s the order that you see. The order in which you insert the keys doesn’t even matter. StructSort() returns an array of key names sorted by their values (not their key names). The code uses StructSort() to put the fruit costs out in order.

<cfset keyArray = StructSort(FruitCosts, “numeric”, “asc”)>
   <cfoutput>
   <cfloop from=”1” to=”#ArrayLen(keyArray)#” index=”i”>
   #keyArray[i]#: #FruitCosts[keyArray[i]]# / lb.<br>
   </cfloop>
 </cfoutput>

The biggest difference between the codes is the approach that each takes to looping over the structure. In the first one, we just use a standard collection loop, relying on whatever order ColdFusion stored the structure in. In the second one, we call StructSort() first, which returns an array of key names that look as follows:

1: Apples
   2: Lemons
   3: Peaches
   4: Oranges
 5: Cherries

These elements still may not seem to be in any particular order, but look at the following prices associated with each element (although the values in parentheses are not actually part of the array):

1: Apples (1.50)
   2: Lemons (1.65)
   3: Peaches (1.75)
   4: Oranges (1.99)
 5: Cherries (2.25)

Although the key names appear in the array, the values remain back in the structure. After calling StructSort(), the code loops through keyArray, which contains the sorted key names. During this loop, keyArray[i] contains the current key name, which can in turn be used to supply the key name to the FruitCosts structure. If you follow the ColdFusion processing engine along step-by-step, the resolution of this reference is as follows:

Step 1: #FruitCosts[keyArray[i]]#
   Step 2: #FruitCosts[keyArray[1]]#
   Step 3: #FruitCosts[“Apples”]#
 Result: 1.50

But what if you want to sort by a key in a nested structure? We’ve modified the FruitCosts structure from earlier in the article by using the following code:

<cfset FruitCosts = StructNew()>
   <cfset FruitCosts[“Oranges”] = StructNew()>
   <cfset FruitCosts[“Oranges”][“lb”] = 1.99>
   <cfset FruitCosts[“Oranges”][“sack”] = 15.50>
   <cfset FruitCosts[“Apples”] = StructNew()>
   <cfset FruitCosts[“Apples”][“lb”] = 1.50>
   <cfset FruitCosts[“Apples”][“sack”] = 13.00>
   <cfset FruitCosts[“Peaches”] = StructNew()>
   <cfset FruitCosts[“Peaches”][“lb”] = 1.75>
   <cfset FruitCosts[“Peaches”][“sack”] = 16.25>
   <cfset FruitCosts[“Cherries”] = StructNew()>
   <cfset FruitCosts[“Cherries”][“lb”] = 2.25>
   <cfset FruitCosts[“Cherries”][“sack”] = 14.00>
   <cfset FruitCosts[“Lemons”] = StructNew()>
   <cfset FruitCosts[“Lemons”][“lb”] = 1.65>
   <cfset FruitCosts[“Lemons”][“sack”] = 15.00>

Each element in the FruitCosts structure is a substructure containing two keys: “lb” (price per pound) and “sack” (price per sack). So now that you have this set of nested structures, how do you sort by price per pound? A fourth attribute of StructSort()describes a dot path to the sort value, as shown in the code.

<cfset keyArray = StructSort(FruitCosts, “numeric”, “asc”, “lb”)>
   <cfoutput>
   <cfloop from=”1” to=”#ArrayLen(keyArray)#” index=”i”>
   #keyArray[i]#: #FruitCosts[keyArray[i]].lb# / lb.<br>
   </cfloop>
 </cfoutput>

The good thing about this method is that you can very easily switch to sorting by price per sack, as shown in the code.

<cfset keyArray = StructSort(FruitCosts, “numeric”, “asc”, “sack”)>
   <cfoutput>
   <cfloop from=”1” to=”#ArrayLen(keyArray)#” index=”i”>
   #keyArray[i]#: #FruitCosts[keyArray[i]].sack# / sack.<br>
   </cfloop>
 </cfoutput>

You can sort by a key any number of levels deep by adding elements to the dot path:

<cfset keyArray = StructSort(FruitCosts, “numeric”, “asc”,
   “sack.10lb.fresh”)>

Be aware that, if the specified subkey doesn’t exist for every top-level element in the main structure, ColdFusion throws an error.