<html>
<head>
<link href="mmres://user_interface_reference.css" rel="stylesheet" type="text/css">
<title>STRUCTCOPY</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
   <div id="Description">
   <table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
      <tr> 
         <td valign="top" class="name">STRUCTCOPY</td>
         <td valign="top" nowrap class="compatibility">&nbsp;</td>
      </tr>
      <tr>
         <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
      </tr>


    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Description</span>
<p>
Copies a structure. Copies top-level keys, values, and arrays in the structure by value; copies nested structures by reference. 
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Returns</span>
<p>
A copy of a structure, with the same keys and values; if structure does not exist, throws an exception.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Category</span>
<p>
Structure functions
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Function syntax</span><pre>StructCopy(structure)
</pre>    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">See also</span>
<p>
Structure functions; "Structure functions" in Chapter&#160;5, "Using Arrays and Structures," in ColdFusion MX Developer's Guide
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Parameters</span>
<p>

</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Usage</span>
<p>
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: 
</p>
<pre>&lt;cfoutput&gt;
   &lt;cfset assignedCopy = StructNew()&gt;
  &lt;cfset assignedCopy.string = #struct.string#&gt;
   &lt;cfset assignedCopy.number = #struct.number#&gt;
   &lt;cfset assignedCopy.array = ArrayNew(2)&gt;
   &lt;cfset assignedCopy.array[1][1] = #struct.array[1][1]#&gt;
   &lt;cfset assignedCopy.array[1][2] = #sruct.array[1][2]#&gt;
&lt;/cfoutput&gt;
</pre>
<p>
The following code shows how StructCopy copies a nested structure:
</p>
<pre>&lt;cfoutput&gt;
  &lt;cfset assignedCopy.nestedStruct = struct.nestedStruct&gt;
&lt;/cfoutput&gt;
</pre>
<p>
To copy a structure entirely by value, use Duplicate on&#160;page&#160;829.
</p>

<p>
The following table shows how variables are assigned:
</p>

<p>
</p><div align="left">
<table border="1">
  <caption></caption>
  <tr align="center">    <th>&#160;</th>
    <th>&#160;</th>
</tr>
  <tr align="left">    <td>
<p>structure.any_simple_value</p>
<p>Boolean</p>
<p>Binary</p>
<p>Base64</p></td>
    <td>
<p>Value</p></td>
</tr>
  <tr align="left">    <td>
<p>structure.array</p></td>
    <td>
<p>Value</p></td>
</tr>
  <tr align="left">    <td>
<p>structure.nested_structure</p></td>
    <td>
<p>Reference</p></td>
</tr>
  <tr align="left">    <td>
<p>structure.object</p></td>
    <td>
<p>Reference</p></td>
</tr>
  <tr align="left">    <td>
<p>structure.query</p></td>
    <td>
<p>Reference</p></td>
</tr>
</table>
</div>
<p>
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Example</span><pre>&lt;!--- This code shows assignment by-value and by-reference. ---&gt;
// This script creates a structure that StructCopy copies by value. &lt;br&gt; 
&lt;cfscript&gt;
   // Create elements.
   s = StructNew();
   s.array = ArrayNew(2);

   // Assign simple values to original top-level structure fields.
   s.number = 99;
   s.string = &quot;hello tommy&quot;;

   // Assign values to original top-level array.
   s.array[1][1] = &quot;one one&quot;;
   s.array[1][2] = &quot;one two&quot;;
&lt;/cfscript&gt;

&lt;!--- Output original structure ---&gt;
&lt;hr&gt;
&lt;b&gt;Original Values&lt;/b&gt;&lt;br&gt;
&lt;cfoutput&gt;
   // Simple values &lt;br&gt;
   s.number = #s.number#&lt;br&gt;
   s.string = #s.string#&lt;br&gt;
   // Array value &lt;br&gt;
   s.array[1][1] = #s.array[1][1]#&lt;br&gt;
   s.array[1][2] = #s.array[1][2]#&lt;br&gt;
&lt;/cfoutput&gt;

// Copy this structure to a new structure. &lt;br&gt;
&lt;cfset copied = StructCopy(s)&gt;

&lt;cfscript&gt;
// Change the values of the original structure. &lt;br&gt;
   s.number = 100;
   s.string = &quot;hello tommy (modified)&quot;;
   s.array[1][1] = &quot;one one (modified)&quot;;
   s.array[1][2] = &quot;one two (modified)&quot;;
&lt;/cfscript&gt;
&lt;hr&gt;
&lt;b&gt;Modified Original Values&lt;/b&gt;&lt;br&gt;
&lt;cfoutput&gt;
   // Simple values &lt;br&gt;
   s.number = #s.number#&lt;br&gt;
   s.string = #s.string#&lt;br&gt;
   // Array value &lt;br&gt;
   s.array[1][1] = #s.array[1][1]#&lt;br&gt;
   s.array[1][2] = #s.array[1][2]#&lt;br&gt;
&lt;/cfoutput&gt;
&lt;hr&gt;
&lt;b&gt;Copied structure values should be the same as the original.&lt;/b&gt;&lt;br&gt;
&lt;cfoutput&gt;
   // Simple values &lt;br&gt;
   copied.number = #copied.number#&lt;br&gt;
   copied.string = #copied.string#&lt;br&gt;
   // Array value &lt;br&gt;
   copied.array[1][1] = #copied.array[1][1]#&lt;br&gt;
   copied.array[1][2] = #copied.array[1][2]#&lt;br&gt;
&lt;/cfoutput&gt;

// This script creates a structure that StructCopy copies by reference. 
&lt;cfscript&gt;
   // 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 = &quot;hello tommy&quot;;
   // Assign values to nested array.
   s.nested.array[1][1] = &quot;one one&quot;;
   s.nested.array[1][2] = &quot;one two&quot;;
&lt;/cfscript&gt;

&lt;!--- Output original structure ---&gt;
&lt;hr&gt;
&lt;b&gt;Original Values&lt;/b&gt;&lt;br&gt;
&lt;cfoutput&gt;
   // Simple values &lt;br&gt;
   s.nested.number = #s.nested.number#&lt;br&gt;
   s.nested.string = #s.nested.string#&lt;br&gt;

   // Array values &lt;br&gt;
   s.nested.array[1][1] = #s.nested.array[1][1]#&lt;br&gt;
   s.nested.array[1][2] = #s.nested.array[1][2]#&lt;br&gt;
&lt;/cfoutput&gt;

// Use StructCopy to copy this structure to a new structure. &lt;br&gt;
&lt;cfset copied = StructCopy(s)&gt;
// Use Duplicate to clone this structure to a new structure. &lt;br&gt;
&lt;cfset duplicated = Duplicate(s)&gt;

&lt;cfscript&gt;
// Change the values of the original structure.
   s.nested.number = 100;
   s.nested.string = &quot;hello tommy (modified)&quot;;
   s.nested.array[1][1] = &quot;one one (modified)&quot;;
   s.nested.array[1][2] = &quot;one two (modified)&quot;;
&lt;/cfscript&gt;
&lt;hr&gt;
&lt;b&gt;Modified Original Values&lt;/b&gt;&lt;br&gt;
&lt;cfoutput&gt;
   // Simple values &lt;br&gt;
   s.nested.number = #s.nested.number#&lt;br&gt;
   s.nested.string = #s.nested.string#&lt;br&gt;

   // Array value &lt;br&gt;
   s.nested.array[1][1] = #s.nested.array[1][1]#&lt;br&gt;
   s.nested.array[1][2] = #s.nested.array[1][2]#&lt;br&gt;
&lt;/cfoutput&gt;

&lt;hr&gt;
&lt;b&gt;Copied structure values should reflect changes to original.&lt;/b&gt;&lt;br&gt;
&lt;cfoutput&gt;
   // Simple values &lt;br&gt;
   copied.nested.number = #copied.nested.number#&lt;br&gt;
   copied.nested.string = #copied.nested.string#&lt;br&gt;
   // Array values &lt;br&gt;
   copied.nested.array[1][1] = #copied.nested.array[1][1]#&lt;br&gt;
   copied.nested.array[1][2] = #copied.nested.array[1][2]#&lt;br&gt;
&lt;/cfoutput&gt;

&lt;hr&gt;
&lt;b&gt;Duplicated structure values should remain unchanged.&lt;/b&gt;&lt;br&gt;
&lt;cfoutput&gt;
   // Simple values &lt;br&gt;
   duplicated.nested.number = #duplicated.nested.number#&lt;br&gt;
   duplicated.nested.string = #duplicated.nested.string#&lt;br&gt;
   // Array value &lt;br&gt;
   duplicated.nested.array[1][1] = #duplicated.nested.array[1][1]#&lt;br&gt;
   duplicated.nested.array[1][2] = #duplicated.nested.array[1][2]#&lt;br&gt;
&lt;/cfoutput&gt;
</pre>
         </td>
      </tr>
   </table>
   </div>
<div id="STRUCTURE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">STRUCTURE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>


<p>Structure to copy</p>

  </td>
  </tr>
  </table>
</div>

  </body>
</html>
