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

StructFindValue

Last update:
May 18, 2026

Description

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

Returns

An array that contains structures keys whose values match the search key value. If none are found, returns an array of size 0.

Category

Structure functions

Syntax

StructFindValue( struct, value [, scope])

See also

Structure functions; Structure functions in the Developing ColdFusion Applications

Parameters

Parameter
Description
struct
ColdFusion structure from which to start  search . This parameter requires an object, not a name of an object.
value
String or a variable that contains one for which to search. The type must be a simple object. Arrays and structures are not supported.
scope
  • one: function returns one matching key (default).
  • all: function returns all matching keys.

Usage

The fields of each structure in the returned array are:
  • Key: name of the key in which the value was found
  • Path: string which could be used to reach the found key
  • Owner: parent object that contains the found key A structure's keys are unordered.

Example with scope="one"

<cfscript>
       myStruct=StructNew();// Create struct myStruct
       myStruct={a=2,b=4,c=8,d=10,e=12,f=12};// Define keys in myStruct
       myStruct.mySecondStruct=StructNew(); //Create nested struct mySecondStruct
       myStruct.mySecondStruct.a1=50;//Define keys in mySecondStruct
       myStruct.mySecondStruct.a2=12;
       myStruct.mySecondStruct.myThirdStruct=StructNew();// Create another nested struct myThirdStruct
       myStruct.mySecondStruct.myThirdStruct.b1=12;//Define keys in myThirdStruct
       myStruct.mySecondStruct.myThirdStruct.b2=65;
       myValue=StructFindValue(myStruct,"12","one");//Search for one default occurrence of "12" in the structs and return appropriate key
       WriteDump(myValue);
</cfscript>

Output

Figure: Example with scope="one"

Example with scope="all"

<cfscript>
       myStruct=StructNew();// Create struct myStruct
       myStruct={a=2,b=4,c=8,d=10,e=12,f=12};// Define keys in myStruct
       myStruct.mySecondStruct=StructNew(); //Create nested struct mySecondStruct
       myStruct.mySecondStruct.a1=50;//Define keys in mySecondStruct
       myStruct.mySecondStruct.a2=12;
       myStruct.mySecondStruct.myThirdStruct=StructNew();// Create another nested struct myThirdStruct
       myStruct.mySecondStruct.myThirdStruct.b1=12;//Define keys in myThirdStruct
       myStruct.mySecondStruct.myThirdStruct.b2=65;
       myValue=StructFindValue(myStruct,"12","all");//Search all occurrences of "12" in the structs and return appropriate key
       WriteDump(myValue);
</cfscript>

Output

Figure: Example with scope="all"
Figure: Example with scope="all"
Figure: Example with scope="all"
Figure: Example with scope="all"

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