StructCopy

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

Structure functions

Function syntax

StructCopy(structure)

See also

Structure functions; Structure functions in Using Arrays and Structures in ColdFusion MX Developer’s Guide

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>