View comments | RSS feed

Getting information about structures and keys

The following sections describe how to use ColdFusion functions to find information about structures and their keys.

Getting information about structures

To find out if a given value represents a structure, use the IsStruct function, as follows:

IsStruct(variable)

This function returns True if variable is a ColdFusion structure. (It also returns True if variable is a Java object that implements the java.util.Map interface.)

Structures are not indexed numerically, so to find out how many name-value pairs exist in a structure, use the StructCount function, as in the following example:

StructCount(employee)

To discover whether a specific Structure contains data, use the StructIsEmpty function, as follows:

StructIsEmpty(structure_name)

This function returns True if the structure is empty, and False if it contains data.

Finding a specific key and its value

To determine whether a specific key exists in a structure, use the StructKeyExists function, as follows:

StructKeyExists(structure_name, "key_name")

Do not put the name of the structure in quotation marks, but you do put the key name in quotation marks. For example, the following code displays the value of the MyStruct.MyKey only if it exists:

<cfif StructKeyExists(myStruct, "myKey")>
<cfoutput> #mystruct.myKey#</cfoutput><br>
</cfif>

You can use the StructKeyExists function to dynamically test for keys by using a variable to represent the key name. In this case, you do not put the variable in quotation marks. For example, the following code loops through the records of the GetEmployees query and tests the myStruct structure for a key that matches the query's LastName field. If ColdFusion finds a matching key, it displays the Last Name from the query and the corresponding entry in the structure.

<cfloop query="GetEmployees">
<cfif StructKeyExists(myStruct, LastName)>
<cfoutput>#LastName#: #mystruct[LastName]#</cfoutput><br>
</cfif>
</cfloop>

If the name of the key is known in advance, you can also use the ColdFusion IsDefined function, as follows:

IsDefined("structure_name.key")>

However, if the key is dynamic, or contains special characters, you must use the StructKeyExists function.

Note: Using StructKeyExists to test for the existence of a structure entry is more efficient than using IsDefined. ColdFusion scopes are available as structures and you can improve efficiency by using StructKeyExists to test for the existence of variables.

Getting a list of keys in a structure

To get a list of the keys in a CFML structure, you use the StructKeyList function, as follows:

<cfset temp=StructKeyList(structure_name, [delimiter] )>

You can specify any character as the delimiter; the default is a comma.

Use the StructKeyArray function to returns an array of keys in a structure, as follows:

<cfset temp=StructKeyArray(structure_name)>

Note: The StructKeyList and StructKeyArray functions do not return keys in any particular order. Use the ListSort or ArraySort functions to sort the results.

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments


Ashish-Saxena said on Jul 20, 2007 at 7:58 AM :
The case (Upper/Lower) of struct’s key name (not key value) is depends on the notation, we choose.
(1)With Dot (object property) Notation:
The key name will be in upper case always, no matter which case come first while assigning.

(2)With Array Notation:
The key name will be in that case, which comes first while assigning same as StructInsert().

(3)With StructInsert():
Likewise Array Notation, the key name will be in that case, which comes first while assigning.

<cfset myStruct=StructNew()>

<!--- Using Dot Notation --->
<cfset myStruct.key1="1">
<cfset myStruct.TYPE="Upper Dot Key">
<cfset myStruct.type="Lower Dot Key">

<cfset myStruct.typenew="Lower Dot Key">
<cfset myStruct.TYPENEW="Upper Dot Key">


<!--- Using Array Notation --->
<cfset myStruct["special-char"]="Lower Array Key">
<cfset myStruct["SPECIAL-CHAR"]="Upper Array Key">

<cfset myStruct["SPECIAL"]="Upper Array Key">
<cfset myStruct["special"]="Lower Array Key">

<!--- Using StructInsert() --->
<cfset StructInsert(myStruct,"name","Lower Ashish","yes")>
<cfset StructInsert(myStruct,"NAME","Upper Ashish","yes")>

<cfset StructInsert(myStruct,"SURNAME","Upper Saxena","yes")>
<cfset StructInsert(myStruct,"surname","Lower Saxena","yes")>


<cfdump var=#myStruct#><br>
<strong>Collection loop.</strong><br />
<cfloop collection="#myStruct#" item="key">
<cfoutput>#key# = #StructFind(myStruct,Key)#</cfoutput><br />
</cfloop>
<br />


<strong>List loop.</strong><br />
<cfset keyList = StructKeyList(myStruct)>
<cfloop list="#keyList#" index="i">
<cfoutput>#i# = #StructFind(myStruct,i)# </cfoutput><br />
</cfloop>

<br />
<strong>Array loop.</strong><br />
<cfset keyArray = StructKeyArray(myStruct)>
<cfloop from="1" to="#ArrayLen(keyArray)#" index="i">
<cfoutput>#keyArray[i]# = #StructFind(myStruct,keyArray[i])#</cfoutput><br />
</cfloop>

OutPut:
struct
KEY1 1
SPECIAL Lower Array Key
SURNAME Lower Saxena
TYPE Lower Dot Key
TYPENEW Upper Dot Key
name Upper Ashish
special-char Upper Array Key

Collection loop.
TYPE = Lower Dot Key
TYPENEW = Upper Dot Key
SPECIAL = Lower Array Key
name = Upper Ashish
special-char = Upper Array Key
SURNAME = Lower Saxena
KEY1 = 1

List loop.
TYPE = Lower Dot Key
TYPENEW = Upper Dot Key
SPECIAL = Lower Array Key
name = Upper Ashish
special-char = Upper Array Key
SURNAME = Lower Saxena
KEY1 = 1

Array loop.
TYPE = Lower Dot Key
TYPENEW = Upper Dot Key
SPECIAL = Lower Array Key
name = Upper Ashish
special-char = Upper Array Key
SURNAME = Lower Saxena
KEY1 = 1

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00000962.htm