Whatever message this page gives is out now! Go check it out!
About structures
Last update:
May 18, 2026
ColdFusion structures consist of key-value pairs. Structures let you build a collection of related variables that are grouped under a single name. You can define ColdFusion structures dynamically.
You can use structures to reference related values as a unit, rather than individually. To maintain employee lists, for example, you can create a structure that holds personnel information such as name, address, phone number, ID numbers, and so on. Then you can reference this collection of information as a structure called employee rather than as a collection of individual variables.
A structure key must be a string. The values associated with the key can be any valid ColdFusion value or object. It can be a string or integer, or a complex object such as an array or another structure. Because structures can contain any types of data, they provide a powerful and flexible mechanism for representing complex data.
You can use structures to reference related values as a unit, rather than individually. To maintain employee lists, for example, you can create a structure that holds personnel information such as name, address, phone number, ID numbers, and so on. Then you can reference this collection of information as a structure called employee rather than as a collection of individual variables.
A structure key must be a string. The values associated with the key can be any valid ColdFusion value or object. It can be a string or integer, or a complex object such as an array or another structure. Because structures can contain any types of data, they provide a powerful and flexible mechanism for representing complex data.
Structure notation
ColdFusion supports three types of notation for referencing structure contents. The notation that you use depends on your requirements.
Notation | Description |
Object.property | You can reference a property, prop, of an object, obj, as obj.prop. This notation, also called dot notation, is useful for simple assignments, as in this example:depts.John="Sales" Use this notation only when you know the property names (keys) in advance and they are strings, with no special characters, numbers, or spaces. You cannot use the dot notation when the property, or key, is dynamic. |
Associative arrays | If you do not know the key name in advance, or it contains spaces, numbers, or special characters, you can use associative array notation. This notation uses structures as arrays with string indexes; for example: depts["John"]="Sales" depts[employeeName] = "Sales" You can use a variable (such as employeeName) as an associative array index. Therefore, enclose any literal key names in quotation marks. For information on using associative array references containing variables, see Dynamically constructing structure references in Dynamic expressions and dynamic variables. |
Structure | Use structure notation only when you create structures and set their initial values, not when you are accessing or updating structure data, and only on the right side of an assignment expression. This notation has the following format: {keyName=value[,keyName=value]...} where the square braces ([]) and ellipses (\...) indicate optional contents that can be repeated.The following example creates a structure that uses structure notation: <cfset name={firstName = "John", lastName = "Smythe"}> |
Support for ordered structs
Ordered structs
When you iterate over a struct in ColdFusion, the order of the keys is random. In ColdFusion (2016 release), you can maintain the order of the keys in which you insert them. This insertion order is possible through Ordered structs.
Syntax
myStruct=StructNew("Ordered");
myStruct.first="I am number one.";
myStruct["second"]="I am number two";
You can also create an Ordered struct using literal syntax, as shown below:
myStruct=[first:"I am number one",second="I am number two"];Example of using ordered structs
<cfscript>
Beatles=StructNew("Ordered"); // ColdFusion (2016 release) supports ordered structs
// Set the values of this struct
Beatles.John="Vocals";
Beatles.Paul="Guitar and vocals";
Beatles.George="Lead guitar";
Beatles.Ringo="Drums";
// Loop through the struct and display struct values in the order
// of insertion
for (i in Beatles)
{
WriteOutput("#i#:#Beatles[i]#" & " ");
}
</cfscript>Output
JOHN:Vocals PAUL:Guitar and vocals GEORGE:Lead guitar R INGO:Drums
Sorted structs
In ColdFusion (2016 release) Update 3, there is support fro sorted structs. You can maintain a sort order in the structs. When sorting, the sorted order is maintained instead of sorting it every time at runtime.
Example of using sorted structs
<cfscript>
// Create a struct of type ordered with sort type as text and sort order as descending.
someStruct=StructNew("ordered","text","desc",false);
someStruct.google = "search";
someStruct.microsoft= "windows";
someStruct.apple = "mac";
someStruct.amazon = "shopping";
for (i in someStruct){
WriteOutput(#i# & "|");
}
</cfscript>Output
MICROSOFT|GOOGLE|APPLE|AMAZON|
Using callback function to sort in a struct
<cfscript>
sorted = structNew("ordered", function(e1,e3,e2,e4)
{
return compare(e1,e2);
});
sorted.azure = "blue";
sorted.adze = "tool";
sorted.baffle = 01;
sorted.adamantium = "dork";
sorted.alabama = 3;
sorted.ballad = 007;
sorted.age = 36;
sorted.aabc= "allardyce";
sorted.baleful="hodgson";
sorted.aardvark=-7;
sorted.back="sort";
writedump(sorted);
</cfscript>Referencing complex structures
When a structure contains another structure, you reference the data in the nested structure by extending either object.property or associative array notation. You can even use a mixture of both notations.
For example, if structure1 has a key key1 whose value is a structure that has keys struct2key1, struct2key2, and so on, you can use any of the following references to access the data in the first key of the embedded structure:
Structure1.key1.Struct2key1
Structure1["key1"].Struct2key1
Structure1.key1["Struct2key1"]
Structure1["key1"]["Struct2key1"]The following example shows various ways you can reference the contents of a complex structure:
<cfscript>
myArray=ArrayNew(1);
myArray[1]="2";
myArray[2]="3";
myStruct2=StructNew();
myStruct2.struct2key1="4";
myStruct2.struct2key2="5";
myStruct=StructNew();
myStruct.key1="1";
myStruct.key2=myArray;
myStruct.key3=myStruct2;
writeDump( var=myStruct );
key1Var="key1";
key2Var="key2";
key3Var="key3";
var2="2";
writeOutput("Value of the first key
#mystruct.key1#
#mystruct[""key1""]#
#mystruct[key1Var]#
Value of the second entry in the key2 array
#myStruct.key2[2]#
#myStruct[""key2""][2]#
#myStruct[key2Var][2]#
#myStruct[key2Var][var2]#
Value of the struct2key2 entry in the key3 structure
#myStruct.key3.struct2key2#
#myStruct[""key3""][""struct2key2""]#
#myStruct[key3Var][""struct2key2""]#
#myStruct.key3[""struct2key2""]#
#myStruct[""key3""].struct2key2#");
</cfscript>Reviewing the code
The following table describes the code:
Code | Description |
<cfscript> myArray=ArrayNew(1); myArray[1]="2"; myArray[2]="3"; myStruct2=StructNew(); myStruct2.struct2key1="4"; myStruct2.struct2key2="5"; myStruct=StructNew(); myStruct.key1="1"; myStruct.key2=myArray; myStruct.key3=myStruct2; </cfscript> | Create a structure with three entries: a string, an array, and an embedded structure. |
writeDump( var=myStruct ); | Display the complete structure. |
key1Var="key1"; key2Var=""key2; key3Var="key3"; | Create variables containing the names of the myStruct keys and the number 2. |
<cfoutput> Value of the first key<br> #mystruct.key1#<br> #mystruct["key1"]#<br> #mystruct[key1Var]#<br> <br> | Output the value of the key1 (string) entry using the following notation:
|
<br> Value of the second entry in the key2 array<br> #myStruct.key2[2]#<br> #myStruct["key2"][2]#<br> #myStruct[key2Var][2]#<br> #myStruct[key2Var][var2]#<br> <br> | Output the value of the second entry in the key2 array using the following notation:
|
Value of the struct2key2 entry in the key3 structure<br> #myStruct.key3.struct2key2#<br> #myStruct["key3"]["struct2key2"]#<br> #myStruct[key3Var]["struct2key2"]#<br> #myStruct.key3["struct2key2"]#<br> #myStruct["key3"].struct2key2#<br> <br> | Output the value of second entry in the key3 embedded structure using the following notation:
|
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
