structInsert

Description

Inserts a key-value pair into a structure.

History

ColdFusion MX: Changed behavior: this function can be used on XML objects.

Syntax

StructInsert(structure, key, value [, allowoverwrite ])

Attributes

Attribute	Description	Required	Default
allowoverwrite	Optional. Whether to allow overwriting a key. The default value is False.
key	Key that contains the inserted value.
structure	Structure to contain the new key-value pair.
value	Value to add.

Returns

True, upon successful completion. If structure does not exist, or if key exists and allowoverwrite = "False", ColdFusion throws an exception.

Usage

A structure’s keys are unordered.

Example

<h1>Add New Employees</h1> 
<!--- Establish params for first time through ---> 
<cfparam name = "FORM.firstname" default = ""> 
<cfparam name = "FORM.lastname" default = ""> 
<cfparam name = "FORM.email" default = ""> 
<cfparam name = "FORM.phone" default = ""> 
<cfparam name = "FORM.department" default = "">  
 
<cfif FORM.firstname EQ ""> 
    Please fill out the form. 
<cfelse> 
    <cfoutput> 
<CFScript> 
    employee = StructNew(); 
    StructInsert(employee, "firstname", FORM.firstname); 
    StructInsert(employee, "lastname", FORM.lastname); 
    StructInsert(employee, "email", FORM.email); 
    StructInsert(employee, "phone", FORM.phone); 
    StructInsert(employee, "department", FORM.department); 
    </CFScript>  
 
    First name is #StructFind(employee, "firstname")#</p> 
    Last name is #StructFind(employee, "lastname")#</p> 
    EMail is #StructFind(employee, "email")#</p> 
    Phone is #StructFind(employee, "phone")#</p> 
    Department is #StructFind(employee, "department")#</p> 
    </cfoutput> 
 
    <!--- Call the custom tag that adds employees ---> 
    <CF_ADDEMPLOYEE EMPINFO = "#employee#"> 
</cfif> 
 
<Hr> 
<form action = "structinsert.cfm"> 
    First Name:&nbsp; 
    <input name = "firstname" type = "text" hspace = "30" maxlength = "30"> 
    Last Name:&nbsp; 
    <input name = "lastname" type = "text" hspace = "30" maxlength = "30"> 
    EMail:&nbsp; 
    <input name = "email" type = "text" hspace = "30" maxlength = "30"> 
    Phone:&nbsp; 
    <input name = "phone" type = "text" hspace = "20" maxlength = "20"> 
    Department:&nbsp; 
    <input name = "department" type = "text" hspace = "30" maxlength = "30"> 
     
    <input type = "submit" value = "OK"> 
</form>

cfmldocs