Last updated on
Apr 27, 2021 06:02:38 AM GMT
|
Also Applies to ColdFusion
Description
Inserts a key-value pair into a structure.
Returns
Returns the updated struct. If a structure does not exist, ColdFusion throws an exception. If a key exists and allowoverwrite = "False", there is also an exception.
Category
Syntax
StructInsert(structure, key, value [, allowoverwrite ])
See also
Structure functions; Modifying a ColdFusion XML object in the Developing ColdFusion Applications
History
ColdFusion (2018 release): Returns a boolean.
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. |
Example
<cfscript>
myStruct=StructNew(); // Create a struct
/*Populate struct key-value items*/
myStruct.item1="JavaSctipt";
myStruct["item2"]="PHP";
WriteOutput("The original struct:");
WriteDump(myStruct); //Struct with two key-value pairs
StructInsert(myStruct,"item3","AJAX",false); // Insert a key-value pair
WriteOutput("The updated struct:");
WriteDump(myStruct); // New struct with three key-value pairs
// Try to insert a new item MySQL with the same key item3.
// This will cause an exception because the key item3 already exists
// To override, set the allowoverwrite flag to true
try{
StructInsert(myStruct,"item3","MySQL",false);
}
catch (any e){
WriteOutput(e.message & "<br/>");
WriteOutput(e.detail);
}
</cfscript>
Output
Using member function
<cfscript>
myStruct={a=1,b=2,c=3,d=4,e=5};
myInsert=myStruct.insert("k",10,true);
WriteDump(myStruct);
</cfscript>
Sign in to your account