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.

Category

Structure functions

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

Comments