BackUp LevelNext

Creating and Using Structures

This section explains how to use the structure functions to create and use structures in ColdFusion. We use as our example a sample structure called employee, which is used to add new employees to a corporate information system.

Creating structures

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.

Adding data to structures

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>

Example of adding data to a structure

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#")>

Finding information in Structures

To find the value associated with a specific key, use the StructFind function:

StructFind(structure_name, key)

Example

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 upper-case.

Getting information about structures

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.

Finding a specific key

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)>

Copying structures

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.

Deleting structures

To delete an individual name-value pair in a structure, use the StructDelete function:

StructDelete(structure_name, key)

This deletes the named key and its associated value.

You can also use the StructClear function, to delete all the data in a structure but keep the structure instance itself:

StructClear(structure_name)

BackUp LevelNext

allaire

AllaireDoc@allaire.com
Copyright © 1998, Allaire Corporation. All rights reserved.