StructCopy  
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
Structure functions
 
Function syntax
StructCopy(structure)
 
See also
Structure functions
 
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:
<cfoutput>
   <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:
<cfoutput>
  <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_value Value
Boolean  
Binary  
Base64  
structure.array Value
structure.nested_structure Reference
structure.object Reference
structure.query Reference
 
Example
<!--- 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>
structure  
Structure to copy