Structure functions

You can use the following functions to create and manage structures in ColdFusion applications. The table describes each function's purpose and provides specific, but limited, information that can assist you in determining whether to use the function instead of other techniques:
Function
Description
Duplicate
Returns a complete copy of the structure.
IsStruct
Returns True if the specified variable is a ColdFusion structure or a Java object that implements the java.util.Map interface.
StructAppend
Appends one structure to another.
StructClear
Removes all data from the specified structure.
StructCopy
Returns a "shallow" copy of the structure. All embedded objects are references to the objects in the original structure. The Duplicate function has replaced this function for most purposes.
StructCount
Returns the number of keys in the specified structure.
StructDelete
Removes the specified item from the specified structure.
StructFind
Returns the value associated with the specified key in the specified structure. This function is redundant with accessing structure elements using associative array notation.
StructFindKey
Searches through a structure for the specified key name and returns an array containing data on the found key or keys.
StructFindValue
Searches through a structure for the specified simple data value (for example, a string or number) and returns an array containing information on the value location in the structure.
StructGet
Returns a reference to a substructure contained in a structure at the specified path. This function is redundant with using direct reference to a structure. If you accidentally use this function on a variable that is not a structure, it replaces the value with an empty structure.
StructInsert
Inserts the specified key-value pair into the specified structure. Unlike a direct assignment statement, this function generates an error by default if the specified key exists in the structure.
StructIsEmpty
Indicates whether the specified structure contains data. Returns True if the structure contains no data, and False if it does contain data.
StructKeyArray
Returns an array of keys in the specified structure.
StructKeyExists
Returns True if the specified key is in the specified structure. You can use this function in place of the IsDefined function to check for the existence of variables in scopes that are available as structures.
StructKeyList
Returns a list of keys in the specified structure.
StructNew
Returns a new structure.
StructSort
Returns an array containing the key names of a structure in the order determined by the sort criteria.
StructUpdate
Updates the specified key with the specified value. Unlike a direct assignment statement, this function generates an error if the structure or key does not exist.

All functions except StructDelete throw an exception if a referenced key or structure does not exist.

For more information on these functions, see CFML Reference.

Comments