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

Syntax

StructFindKey(top, value, scope)

See also

Structure functionsStructure 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

Scope="one" in a normal struct
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

Scope="one" in an ordered struct
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

Scope="all" output
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>

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy