structures

nicric edited this page Mar 7, 2012 · 2 revisions

Previous Arrays --- Next Conditionals


8. Structures

A structure is a collection of data where each element of data is addressed by a name. As an analogy, think about a classroom of children. Under ideal circumstances, each student has a name and can be found by using that name. We might look in a science classroom for a child named Joey and that would result in finding an actual student. We could write this like science["Joey"] which could be read as "look in the collection named 'science' and find the thing named 'Joey'".

A structure is an unordered collection, it’s just a bunch of data collected together where each one has a unique name/key. Structures have a slightly more complicated syntax:

Tag Syntax

<cfset ages = {jack = 11, brian = 12, tracy = 11} />
<cfset ages.joey = 12 /> 
<cfset ages["jill"] = 14 />

<cfdump var = "#ages#" />

<cfoutput>
Joey is #ages["joey"]# years old.
</cfoutput>

Script Syntax

<cfscript>
ages = {jack = 11, brian = 12, tracy = 11};
ages.joey = 12;
ages["jill"] = 14;

writeDump (var = ages);
writeOutput ("Joey is #ages["joey"]# years old.");
</cfscript>

Here we create a structure named ages. Structures are made up what are called key-value pairs. The key is used as the address and the value is the object at that address. In the ages structure we have keys including joey and jill and values including "12" and "14". When creating a structure using {} the key and value are linked by the = symbol. So to create a structure, the structures start with a curly bracket {, have zero or more entries made up of a key, =, and a value separated by commas, then end with a closing curly bracket }. It is worth noting that when adding a key that is quoted, as is the case with "jill", the case sensitivity of the key will be preserved. Otherwise all keys will be uppercase.

Tag Syntax

<cfset ages["jimmy"] = 14 />
<cfset ages["joey"] = 9 />
<cfdump var = "#ages#" />

Script Syntax

<cfscript>
ages["jimmy"] = 14;
ages["joey"] = 9;
writeDump (var = ages);
</cfscript>

In the second chunk of the example, we add a new key and value to the structure. Since the jimmy key wasn't in the original structure, it's added with the value of "14". If the key jimmy already existed then the value would be replaced by "14". Every key in a structure must be unique! In the second line we reference the key joey which already exists, so the value gets replaced with the "9". Then, just to show you the state of the structure, we dump out the list of keys and the list of values.

Tag Syntax

<cfset StructSort(ages)>

<cfloop collection = "#ages#" item = "student">
 <cfoutput>"#student# is #ages[student]# years old."<br />
 </cfoutput>
</cfloop>

Script Syntax

<cfscript>
StructSort(ages);
for(student in ages) {
 WriteOutput ('"#student# is #ages[student]# years old.<br />"');
}
</cfscript>

The last chunk of the example used StructSort to get the sorted array "students" from "ages". Then, it iterated through the "students" array using a loop and gave each element of the array the name "student". It then printed out one line with that student’s name and age from "ages".

While that last part probably seemed complicated, it's just to illustrate that structures are unordered.

8.3 structKeyExists

When referencing a structure by key names, it is ususally good practice to make sure that the key exists in the structure first. This is done with the structKeyExists(structure, "key") function. Lets say we have a structure named Person and we want to check that it has a key named "yearBorn" before doing something with it. That would be done with the following code:

<cfscript>
if(structKeyExists(Person,"yearBorn")){
  Person.age = year(now()) - Person.yearBorn;
}
</cfscript>

8.2 Looping through a structure

Sometimes it is convienent to loop through all the keys of a structure. This is done with a for-in type of loop. Lets look at an example using the following struct:

<cfscript >
  myStruct = {apple = "Apple", banana = "Banana", pear = "Pear"};
</cfscript>

Tag Syntax

Using tag syntax we use what is called a "collection" loop. The cfloop syntax takes two parameters, the name of the collection, and the variable name that holds the collection's key:

<cfloop collection="#myStruct#" item="fruit">
  #myStruct[fruit]#
</cfloop>

Script Syntax

Using script syntax we use what is called a "for-in" loop. The syntax of a for-in loop looks like cfm for(key in structure). The code to loop through the structure we created earler would look like this:

<cfscript >
  for(fruit in myStruct){
    writeOutput(myStruct[fruit]);
  }
</cfscript>

Previous Arrays --- Next Conditionals