Whatever message this page gives is out now! Go check it out!
StructCopy
Last update:
May 18, 2026
Description
Copies a structure. Copies top-level keys, values, and arrays in the structure by value; copies nested structures by reference.
Returns
A copy of a structure, with the same keys and values; if structure does not exist, throws an exception.
Category
Syntax
StructCopy(structure)See also
Structure functions in the Developing ColdFusion Applications
Parameters
Parameter | Description |
structure | Structure to copy |
Usage
The following code shows how this function copies a structure that contains a string field, a number field, and a two-dimensional array at the top-level:
<cfset assignedCopy = StructNew()>
<cfset assignedCopy.string = #struct.string#>
<cfset assignedCopy.number = #struct.number#>
<cfset assignedCopy.array = ArrayNew(2)>
<cfset assignedCopy.array[1][1] = #struct.array[1][1]#>
<cfset assignedCopy.array[1][2] = #sruct.array[1][2]#>
</cfoutput>The following code shows how StructCopy copies a nested structure:
<cfset assignedCopy.nestedStruct = struct.nestedStruct>
</cfoutput>To copy a structure entirely by value, use Duplicate.The following table shows how variables are assigned:
Variable type | Assigned by |
structure.any_simple_valueBooleanBinaryBase64 | Value |
structure.array | Value |
structure.nested_structure | Reference |
structure.object | Reference |
structure.query | Reference |
Example 1
<!--- This code shows assignment by-value and by-reference. --->
// This script creates a structure that StructCopy copies by value. <br>
<cfscript>
// Create elements.
s = StructNew();
s.array = ArrayNew(2);
// Assign simple values to original top-level structure fields.
s.number = 99;
s.string = "hello tommy";
// Assign values to original top-level array.
s.array[1][1] = "one one";
s.array[1][2] = "one two";
</cfscript>
<!--- Output original structure --->
<hr>
<b>Original Values</b><br>
<cfoutput>
// Simple values <br>
s.number = #s.number#<br>
s.string = #s.string#<br>
// Array value <br>
s.array[1][1] = #s.array[1][1]#<br>
s.array[1][2] = #s.array[1][2]#<br>
</cfoutput>
// Copy this structure to a new structure. <br>
<cfset copied = StructCopy(s)>
<cfscript>
// Change the values of the original structure. <br>
s.number = 100;
s.string = "hello tommy (modified)";
s.array[1][1] = "one one (modified)";
s.array[1][2] = "one two (modified)";
</cfscript>
<hr>
<b>Modified Original Values</b><br>
<cfoutput>
// Simple values <br>
s.number = #s.number#<br>
s.string = #s.string#<br>
// Array value <br>
s.array[1][1] = #s.array[1][1]#<br>
s.array[1][2] = #s.array[1][2]#<br>
</cfoutput>
<hr>
<b>Copied structure values should be the same as the original.</b><br>
<cfoutput>
// Simple values <br>
copied.number = #copied.number#<br>
copied.string = #copied.string#<br>
// Array value <br>
copied.array[1][1] = #copied.array[1][1]#<br>
copied.array[1][2] = #copied.array[1][2]#<br>
</cfoutput>
// This script creates a structure that StructCopy copies by reference.
<cfscript>
// Create elements.
s = StructNew();
s.nested = StructNew();
s.nested.array = ArrayNew(2);
// Assign simple values to nested structure fields.
s.nested.number = 99;
s.nested.string = "hello tommy";
// Assign values to nested array.
s.nested.array[1][1] = "one one";
s.nested.array[1][2] = "one two";
</cfscript>
<!--- Output original structure --->
<hr>
<b>Original Values</b><br>
<cfoutput>
// Simple values <br>
s.nested.number = #s.nested.number#<br>
s.nested.string = #s.nested.string#<br>
// Array values <br>
s.nested.array[1][1] = #s.nested.array[1][1]#<br>
s.nested.array[1][2] = #s.nested.array[1][2]#<br>
</cfoutput>
// Use StructCopy to copy this structure to a new structure. <br>
<cfset copied = StructCopy(s)>
// Use Duplicate to clone this structure to a new structure. <br>
<cfset duplicated = Duplicate(s)>
<cfscript>
// Change the values of the original structure.
s.nested.number = 100;
s.nested.string = "hello tommy (modified)";
s.nested.array[1][1] = "one one (modified)";
s.nested.array[1][2] = "one two (modified)";
</cfscript>
<hr>
<b>Modified Original Values</b><br>
<cfoutput>
// Simple values <br>
s.nested.number = #s.nested.number#<br>
s.nested.string = #s.nested.string#<br>
// Array value <br>
s.nested.array[1][1] = #s.nested.array[1][1]#<br>
s.nested.array[1][2] = #s.nested.array[1][2]#<br>
</cfoutput>
<hr>
<b>Copied structure values should reflect changes to original.</b><br>
<cfoutput>
// Simple values <br>
copied.nested.number = #copied.nested.number#<br>
copied.nested.string = #copied.nested.string#<br>
// Array values <br>
copied.nested.array[1][1] = #copied.nested.array[1][1]#<br>
copied.nested.array[1][2] = #copied.nested.array[1][2]#<br>
</cfoutput>
<hr>
<b>Duplicated structure values should remain unchanged.</b><br>
<cfoutput>
// Simple values <br>
duplicated.nested.number = #duplicated.nested.number#<br>
duplicated.nested.string = #duplicated.nested.string#<br>
// Array value <br>
duplicated.nested.array[1][1] = #duplicated.nested.array[1][1]#<br>
duplicated.nested.array[1][2] = #duplicated.nested.array[1][2]#<br>
</cfoutput>Example 2
<cfscript>
myStruct=StructNew();// Create struct myStruct
myStruct={a=2,b=4,c=8,d=10,e=12,f=12};// Define keys in myStruct
myStruct.mySecondStruct=StructNew(); //Create nested struct mySecondStruct
myStruct.mySecondStruct.a1=50;//Define keys in mySecondStruct
myStruct.mySecondStruct.a2=12;
myStruct.mySecondStruct.myThirdStruct=StructNew();// Create another nested struct myThirdStruct
myStruct.mySecondStruct.myThirdStruct.b1=12;//Define keys in myThirdStruct
myStruct.mySecondStruct.myThirdStruct.b2=65;
copyStruct=StructCopy(myStruct)
writeDump(copyStruct)
</cfscript>
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
|
