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.

Syntax

StructCopy(structure)

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

<!--- 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>