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 technique.
All functions except StructDelete throw an exception if a referenced key or structure does not exist.
For more information on these functions, see the CFML Reference.
|
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. |