Whatever message this page gives is out now! Go check it out!

StructFindKey

Last update:
May 18, 2026

Description

Searches recursively through a substructure of nested arrays, structures, and other elements, for structures whose keys match the search key in the value parameter.

Returns

An array that contains structures with keys that match value.

Category

Structure functions

Syntax

StructFindKey(top, value, scope)

See also

Structure functions; Structure functions in the Developing ColdFusion Applications guide.

Parameters

Parameter
Description
top
ColdFusion structure from which to start  search .
value
String or a variable that contains one for which to search.
scope
  • one: returns one matching key. Default.
  • all: returns all matching keys. If the key is not found, an empty array is returned.

Usage

Returns an array that includes one structure for each of the specified keys it finds. The fields of each of these structures are:
  • Value: value held in the found key
  • Path: string that can be used to reach the found key
  • Owner: parent object that contains the found key A structure's keys are unordered.

Samples

In the example below, the struct Beatles contains nested structs. This sample searches for the key lastName in the struct and returns the last names of the members based on the scope.
The samples are for both ordered and normal struct.

Example with scope="one" in a normal struct

<cfscript>
    // Define struct
    Beatles = structNew();
    // Set struct values in nested form
    Beatles.person1 = structNew();
    Beatles.person1.id = 1;
    Beatles.person1.firstName = "John";
    Beatles.person1.lastName = "Lennon";
     
    Beatles.person2 = structNew();
    Beatles.person2.id = 2;
    Beatles.person2.firstName = "Paul";
    Beatles.person2.lastName = "McCartney";
     
    Beatles.person3 = structNew();
    Beatles.person3.id = 3;
    Beatles.person3.firstName = "George";
    Beatles.person3.lastName = "Harrison";
     
    Beatles.person5 = structNew();
    Beatles.person5.id = 5;
    Beatles.person5.firstName = "Abbey";
    Beatles.person5.lastName = "Road";
    
    Beatles.person4 = structNew();
    Beatles.person4.id = 4;
    Beatles.person4.firstName = "Ringo";
    Beatles.person4.lastName = "Starr";
        
    myKey=StructFindKey(Beatles,"lastName","one"); //Returns struct with key=lastName, scope="one"
    WriteOutput("Struct Find Key");
    WriteDump(myKey);
</cfscript>

Output

Figure: Scope="one" in a normal struct

Example with scope="one" in an ordered struct

<cfscript>
    // Define struct
    Beatles = structNew("Ordered");
    // Set struct values in nested form
    Beatles.person1 = structNew();
    Beatles.person1.id = 1;
    Beatles.person1.firstName = "John";
    Beatles.person1.lastName = "Lennon";
     
    Beatles.person2 = structNew();
    Beatles.person2.id = 2;
    Beatles.person2.firstName = "Paul";
    Beatles.person2.lastName = "McCartney";
     
    Beatles.person3 = structNew();
    Beatles.person3.id = 3;
    Beatles.person3.firstName = "George";
    Beatles.person3.lastName = "Harrison";
     
    Beatles.person5 = structNew();
    Beatles.person5.id = 5;
    Beatles.person5.firstName = "Abbey";
    Beatles.person5.lastName = "Road";
    
    Beatles.person4 = structNew();
    Beatles.person4.id = 4;
    Beatles.person4.firstName = "Ringo";
    Beatles.person4.lastName = "Starr";
        
    myKey=StructFindKey(Beatles,"lastName","one"); //Returns struct with key=lastName, scope="one"
    WriteOutput("Struct Find Key");
    WriteDump(myKey);
</cfscript>

Output

Figure: Scope="one" in an ordered struct

Example with scope="all"

<cfscript>
    // Define struct
    Beatles = structNew();
    // Set struct values in nested form
    Beatles.person1 = structNew();
    Beatles.person1.id = 1;
    Beatles.person1.firstName = "John";
    Beatles.person1.lastName = "Lennon";
     
    Beatles.person2 = structNew();
    Beatles.person2.id = 2;
    Beatles.person2.firstName = "Paul";
    Beatles.person2.lastName = "McCartney";
     
    Beatles.person3 = structNew();
    Beatles.person3.id = 3;
    Beatles.person3.firstName = "George";
    Beatles.person3.lastName = "Harrison";
     
    Beatles.person4 = structNew();
    Beatles.person4.id = 4;
    Beatles.person4.firstName = "Ringo";
    Beatles.person4.lastName = "Starr";
        
    myKey=StructFindKey(Beatles,"lastName","all"); //Returns struct with key=lastName, scope="all"
    WriteOutput("Struct Find Key");
    WriteDump(myKey);
</cfscript>

Output

Figure: Scope="all" output

Using member function

<cfscript>
    // Define struct
    Beatles = structNew("Ordered");
    // Set struct values in nested form
    Beatles.person1 = structNew();
    Beatles.person1.id = 1;
    Beatles.person1.firstName = "John";
    Beatles.person1.lastName = "Lennon";
     
    Beatles.person2 = structNew();
    Beatles.person2.id = 2;
    Beatles.person2.firstName = "Paul";
    Beatles.person2.lastName = "McCartney";
     
    Beatles.person3 = structNew();
    Beatles.person3.id = 3;
    Beatles.person3.firstName = "George";
    Beatles.person3.lastName = "Harrison";
     
    Beatles.person5 = structNew();
    Beatles.person5.id = 5;
    Beatles.person5.firstName = "Abbey";
    Beatles.person5.lastName = "Road";
    
    Beatles.person4 = structNew();
    Beatles.person4.id = 4;
    Beatles.person4.firstName = "Ringo";
    Beatles.person4.lastName = "Starr";
    
    memKey=Beatles.findkey("lastname","one");
    WriteDump(memKey);
</cfscript>

Share this page

Was this page helpful?
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Thank you for your feedback. Your response will help improve this page.

On this page