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
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 | Value
Boolean |
Binary |
Base64 |
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>

structure |
Structure to copy