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 functionsModifying a ColdFusion XML object in the Developing ColdFusion Applications

History

ColdFusion (2018 release): Returns the updated struct.

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

StructInsert

Using member function

<cfscript>
       myStruct={a=1,b=2,c=3,d=4,e=5};
       myInsert=myStruct.insert("k",10,true);
       WriteDump(myStruct);
</cfscript>

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy