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>

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy