This section explains how to use the structure functions to create and use structures in ColdFusion. The sample structure is called employee, and is used to add new employees to a corporate information system.
You create structures by assigning a variable name to the structure with the StructNew function:
<CFSET mystructure=StructNew()>
For example, to create a structure named employee, use this syntax:
<CFSET employee=StructNew()>
Now the structure exists and you can add data to it.
After you've created a structure, you add key-value pairs to the structure using the StructInsert function:
<CFSET value=StructInsert(structure_name, key, value [, AllowOverwrite])>
The AllowOverwrite parameter is optional and can be either TRUE or FALSE. It can be used to specify whether an existing key should be overwritten or not. The default is FALSE.
When adding string values to a structure, enclose the string in quotation marks. For example, to add a key, John, with a value, Sales, to an existing structure called Departments, use this syntax:
<CFSET value=StructInsert(Departments, "John", "Sales")>
To change the value associated with a specific key, use the StructUpdate function. For example, if John moves from the Sales department to the Marketing department, you would use this syntax to update the Departments associative array:
<CFOUTPUT> Personnel moves: #StructUpdate(Departments, "John", "Marketing")# </CFOUTPUT>
The following example shows how to add content to a sample structure named employee, building the content of the value fields dynamically using form variables:
<CFSET rc=StructInsert(employee, "firstname", "#FORM.firstname#")>
<CFSET rc=StructInsert(employee, "lastname", "#FORM.lastname#")>
<CFSET rc=StructInsert(employee, "email", "#FORM.email#")>
<CFSET rc=StructInsert(employee, "phone", "#FORM.phone#")>
<CFSET rc=StructInsert(employee, "department", "#FORM.department#")>
To find the value associated with a specific key, use the StructFind function:
StructFind(structure_name, key)
The following example shows how to generate a list of keys defined for a structure.
<CFLOOP COLLECTION=#department# ITEM="person"> <CFOUTPUT> Key - #person#<BR> Value - #StructFind(department,person)#<BR> </CFOUTPUT>
Note that the StructFind function is case-insensitive. When you enumerate key-value pairs using a loop, the keys appear in uppercase.
To find out if a given value represents a structure, use the IsStruct function:
IsStruct(variable)
This function returns TRUE if variable is a structure.
Structures are not indexed numerically, so to find out how many name-value pairs exist in a structure, use the StructCount function, as in this example:
StructCount(employee)
To discover whether a specific Structure contains data, use the StructIsEmpty function:
StructIsEmpty(structure_name)
This function returns TRUE if the structure is empty and FALSE if it contains data.
To learn whether a specific key exists in a structure, use the StructKeyExists function.
StructKeyExists(structure_name, key)
If the name of the key is known in advance, you can use the ColdFusion function IsDefined, as in this example:
<CFSET temp=IsDefined("structure_name.key")>
But if the key is dynamic, or contains special characters, you must use the StructKeyExists function:
<CFSET temp=StructKeyExists(structure_name, key)>
To get a list of the keys in a CFML structure, you use the StructKeyList function:
<CFSET temp=StructKeyList(structure_name, [delimiter] )>
The delimiter can be any delimiter, but the default is a comma ( , ).
The StructKeyArray function returns an array of keys in a structure:
<CFSET temp=StructKeyArray(structure_name)>
Note | The StructKeyList and StructKeyArray functions do not return keys in any particular order. Use the ListSort or ArraySort function to sort the results. |
To copy a structure, use the StructCopy function. This function takes the name of the structure you want to copy and returns a new structure with all the keys and values of the named structure.
StructCopy(structure)
This function throws an exception if structure doesn't exist.
Use the StructCopy function when you want to create a physical copy of a structure. You can also use assignment to create a copy by reference.
To delete an individual name-value pair in a structure, use the StructDelete function:
StructDelete(structure_name, key [, indicatenotexisting ])
This deletes the named key and its associated value. Note that the indicatenotexisting parameter indicates whether the function returns FALSE if the named key does not exist. The default is FALSE, which means that the function returns Yes regardless of whether key exists. If you specify TRUE for this parameter, the function returns Yes if key exists and No if it does not.
You can also use the StructClear function to delete all the data in a structure but keep the structure instance itself:
StructClear(structure_name)