StructInsert

Description

Inserts a key-value pair into a structure.

Returns

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

Function syntax

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

See also

Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications

History

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

Parameters

Parameter

Description

structure

Structure to contain the new key-value pair.

key

Key that contains the inserted value.

value

Value to add.

allowoverwrite

Optional. Whether to allow overwriting a key. The default value is False.

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 ""> 
    <p>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>  
 
    <p>First name is #StructFind(employee, "firstname")#</p> 
    <p>Last name is #StructFind(employee, "lastname")#</p> 
    <p>EMail is #StructFind(employee, "email")#</p> 
    <p>Phone is #StructFind(employee, "phone")#</p> 
    <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"> 
    <p>First Name:&nbsp; 
    <input name = "firstname" type = "text" hspace = "30" maxlength = "30"> 
    <p>Last Name:&nbsp; 
    <input name = "lastname" type = "text" hspace = "30" maxlength = "30"> 
    <p>EMail:&nbsp; 
    <input name = "email" type = "text" hspace = "30" maxlength = "30"> 
    <p>Phone:&nbsp; 
    <input name = "phone" type = "text" hspace = "20" maxlength = "20"> 
    <p>Department:&nbsp; 
    <input name = "department" type = "text" hspace = "30" maxlength = "30"> 
    <p> 
    <input type = "submit" value = "OK"> 
</form>