StructInsert

Description

Inserts a key-value pair into a structure.

Return value

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

Syntax

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

History

New in ColdFusion MX: 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. Default: False.

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. Default: False.

Usage

A structure's keys are unordered.

Example

<h1>Add New Employees</h1>
<!--- Establish parms 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>