StructCopy

Description

Returns a new structure with the keys and values of a structure.

Syntax


StructCopy(structure)

Parameters

Parameter

Description

structure
Structure to copy

Parameter	Description
structure	Structure to copy

Usage

This function throws an exception if structure does not exist.

Top-level simple values and arrays are assigned by value. The following code shows how StructCopy would copy a structure that contains a string field, a number field, and a two-dimensional array.

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

A nested structure and fields beneath the structure are assigned by reference. The following code shows how StructCopy would copy a nested structure:

<cfoutput>

  <cfset assignedCopy.nestedStruct = struct.nestedStruct>

</cfoutput>

Use Duplicate to copy a structure entirely by value.

The following table shows how variables are assigned.

Variable Type

Assigned by

structure.any_simple_value

Boolean

Binary

Base64

value

structure.array
value

structure.nested_structure
reference

structure.object
reference

structure.query
reference

Variable Type	Assigned by
structure.any_simple_value Boolean Binary Base64	value
structure.array	value
structure.nested_structure	reference
structure.object	reference
structure.query	reference

Example

<!--------------------------------------------------------------------

Theis code shows examples of 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>