StructFind

StructFind(structure, key)

<!--- This view-only example shows the use of StructFind. --->
<p>This file is identical to addemployee.cfm, which is called by StructNew,
StructClear, and StructDelete. It adds employees. Employee information 
is passed through the employee structure (EMPINFO attribute). In UNIX,
you must also add the Emp_ID.
<!--- 
<cfswitch expression = "#ThisTag.ExecutionMode#">
  <cfcase value = "start">
   <cfif StructIsEmpty(attributes.EMPINFO)>
    <cfoutput>Error. No employee data was passed.</cfoutput>
     <cfexit method = "ExitTag">
   <cfelse>
     <cfquery name = "AddEmployee" datasource = "cfsnippets">
     INSERT INTO Employees (FirstName, LastName, Email, Phone, Department)
      VALUES 
       <cfoutput>
        (
         `#StructFind(attributes.EMPINFO, "firstname")#' ,
         `#StructFind(attributes.EMPINFO, "lastname")#' ,
         `#StructFind(attributes.EMPINFO, "email")#' ,
         `#StructFind(attributes.EMPINFO, "phone")#' ,
         `#StructFind(attributes.EMPINFO, "department")#' )
       </cfoutput> 
    </cfquery>
   </cfif>
   <cfoutput><hr>Employee Add Complete</cfoutput>
  </cfcase>
</cfswitch> --->

Comments

No screen name said on Dec 5, 2003 at 9:46 AM :

Much of this documentation is lacking a good deal of information. This entry is a prime example. What is returned if key is undefined?

And like nearly all the documentation in this reference, what types are allowed? What types are returned?

a440guy said on Jun 14, 2004 at 10:43 AM :

I "second" the comments of "No screen name".

The ColdFusion documentation is universally imprecise and ambiguous. One must experiment with the function to discover how to use it. This entry (StructFind) is a good example:

(1) The documentation glosses over the difference between a variable and a variable name, or a structure and a the name of a structure. The difference is critical. Although most things in ColdFusion are strings, Recent additions to the language require objects instead of strings. And unctions such as IsDefined and Evaluate are difficult to understand if one does not understand the difference between a variable name and a string. In the case of StructFind, the "usage" skeleton should say:

StructFind(structure, key)
where structure is the name of a variable containing the structure
and key is a string, or a variable containing a string.

Of course, elsewhere in the documentation, _string_ should be defined as alphanumeric characters enclosed by single- or double-quotes.

(2) Don't use the word "determine" to mean "find" or "deduce" or the like. Use "determine" only when you mean one thing is a result of the other thing. Examples:

If y is a function of x, then x determines y.
Your skill level will determine which class to take.

In this StructFind documentation, it says "[StructFind] determines the value associated with a key in a structure." It does NOT determine the value, the value is already in the structure. The key determines the value that is returned! A better short description would be: "Returns the value associated with a key from a structure." Note that one does not "return ... in" as the docs put it, but rather one "returns ... from." Even more clear would be: "returns from a structure the value associated with a key."

(3) Tline after the "short description" (as I am calling it), is not labeled. Apparently, this line describes what is returned from the function, although one has to guess at that. There should be the subheading: "Returns" immediatly above that line. The description of what is returned should also indicate the nature of the return value. Is it a string, an array, another structure, or the name of one of those things? For example, what is returned if you had done this:

StructInsert(mtstruct, key, ArrayNew(1))

In the Parameter, Description section of the documentation, the description adds nothing to what is obvious. Here is where you can actually describe the parameters.

The example, as in all examples in the ColdFusion documentation, is so simple that they add litle or nothing to what is given in the "usage" line. What happens if the value returned is an array (or another structure)? How do you use StructFind to return the value of a single element of that array?

No screen name said on Dec 9, 2004 at 11:29 AM :

I agree, though CF documentation has always been especially vague in its description of structures. The rest of the documentation is, at least, a little more explicit.

No screen name said on Jan 18, 2007 at 11:57 AM :

This article shows poor coding practice. The result of the StructFind call will not be escaped, allowing for the possibility of SQL injection. In coldfusion variables are escaped within cfquery tags, but function calls are not.