StructCopy

Description

Copies a structure. Copies top-level keys, values, and arrays in the structure by value; copies nested structures by reference.

Return value

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

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

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