A few days ago I talked about a rarely used function called structSort. Today I'm going to talk about a related set of functions, structFindValue and structFindKey.

As you can imagine, these two functions will search a structure for either a particular value, or a particular key. Here is a simple example of structFindValue:

<cfscript>
s = structNew();
s["Jacob"] = structNew();
s["Jacob"].gender = "male";
s["Jacob"].age = "3";
s["Lynn"] = structNew();
s["Lynn"].gender = "female";
s["Lynn"].age = "2";
s["Noah"] = structNew();
s["Noah"].gender = "male";
s["Noah"].age = "1";

males = structFindValue(s,"male","all");
writeOutput("There are #arraylen(males)# male children.");
</cfscript>

We define a simple structure, s, then a set of children under it. Then we use the structFindValue function to search the structure. We pass it "male" as the value to look for, and "all" to make it return all matches. The result is an array of matches. Each element of the array contains three keys: The key where the value matched. The "owner", which is a pointer to the parent structure of the key. Lastly, it returns path, which is the specific path from the root structure to the key matched. structFindKey pretty much works the same way, except that "value" is returned instead of key, and obviously value is the value of the matched key.

So, obviously these functions would be useful to search complex structures. If you have any questions, please post them in the comments field.