StructAppend

Description

Appends one structure to another.

Return value

True, upon successful completion; False, otherwise.

Syntax

StructAppend(struct1, struct2, overwriteFlag)

History

New in ColdFusion MX: this function can be used on XML objects.

Parameters

Parameter Description

struct1
Structure to append.

struct2
Structure that contains the data to append to struct1

overwriteFlag

Yes: values in struct2 overwrite corresponding values in struct1. Default.

No

Parameter	Description
struct1	Structure to append.
struct2	Structure that contains the data to append to `struct1`
overwriteFlag	Yes: values in `struct2` overwrite corresponding values in `struct1`. Default. No

Usage

This function appends the fields and values of struct2 to struct1; struct2 is not modified. If struct1 already contains a field of struct2, overwriteFlag determines whether the value in struct2 overwrites it.

A structure's keys are unordered.

Example

<html>
<body>
<!---- Create a Name structure --->
<cfset nameCLK=StructNew()>
<cfset nameCLK.first="Chris">
<cfset nameCLK.middle="Lloyd">
<cfset nameCLK.last="Gilson">
<!--- Create an address struct --->
<cfset addrCLK=StructNew()>
<cfset addrCLK.street="17 Gigantic Rd">
<cfset addrCLK.city="Watertown">
<cfset addrCLK.state="MA">
<cfset addrCLK.zip="02472">
<!---- Create a Person structure --->
<cfset personCLK=StructNew()>
<cfset personCLK.name=#nameCLK#>
<cfset personCLK.addr=#addrCLK#>
<!--- Display the contents of the person struct before the Append --->
<p>
The person struct <b>before</b> the Append call:<br>
<cfloop collection=#personCLK# item="myItem">
<cfoutput>
#myItem#<br>
</cfoutput>
</cfloop>
<!--- Merge the Name struct into the top-level person struct --->
<cfset bSuccess = StructAppend( personCLK, addrCLK )>

<!--- Display the contents of the person struct, after the Append --->
<p>
The person struct <b>after</b> the Append call:<br>
<cfloop collection=#personCLK# item="myItem">
  <cfoutput>
    #myItem#<br>
  </cfoutput>
</cfloop>

Version 6

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

Comments

spage-mm said on May 27, 2003 at 5:12 PM :

Doesn't say whether it does a deep copy of the appended structure values or just a shallow copy. This is important information -- compare Duplicate() vs. StructCopy().

spage-mm said on May 27, 2003 at 6:05 PM :

I wrote a test and it seems structAppend does a shallow copy of values, not a deep copy.

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-pt287.htm