User Guide

866 Chapter 3: ColdFusion Functions
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.
Category
Structure functions
Function syntax
StructInsert(structure, key, value [, allowoverwrite ])
See also
Structure functions; “Modifying a ColdFusion XML object” in Chapter 35, “Using XML and
WDDX,” in ColdFusion MX Developer’s Guide
History
ColdFusion MX: Changed behavior: this function can be used on XML objects.
Parameters
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);
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.