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>

Version 6

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments

spage-mm said on Nov 20, 2002 at 4:52 AM :

If you use structCopy to copy arguments scope in a function, it seems even simple values are copied by reference: if I change the values in the copy, the arguments scope changes.

Erik Westra said on Aug 30, 2007 at 3:37 AM :

This is correct and can be confirmed with the following code:

<cffunction name="testArguments" >
<cfargument name="testArgument" />

<cfset var newA1 = structCopy(arguments) />
<cfset var newA2 = structNew() />
<cfset var i = "" />

<cfloop collection="#arguments#" item="i">
<cfset newA2[i] = arguments[i] />
</cfloop>

<cfdump var="#arguments#" />
<cfset newA1.testArgument = "test1" />
<cfdump var="#arguments#" />
<cfset newA2.testArgument = "test2" />
<cfdump var="#arguments#" />
</cffunction>

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6/CFML_Reference/functions-pt289.htm