@Mark Takata (Adobe) / @saghosh yer missing some stuff from https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-s/structfind.html. • The function signature doesn't mention that can take a key name instead of a callback for the second parameter value. • The parameters sections doesn't mention it can take a callback instead of a key name for the second parameter value. • The history section doesn't mention that the callback option was added in CF2018. • Bad English in the

parallel

parameter description. Should be "Parallelism is supported only when the second parameter is a closure . When the second parameter is a key, paralellism is not supported.". My emphasis. Also, really, it's the argument (value) not the parameter (name). "Parameter value" would work.

image.png

*toucan

are ye callin meh a fruit loop!?!?

image.png

NP man. Is funny. I'dn't've mentioned the grammar thing if I wasn't already mentioning the more important missing documentation thing.

for sure... the parameters list definitely needs some clarification on the second parameter

Why do they call it a pairameter if there's only one of them?

🍐 🐏 🥩 💨

OMG.

I'm absolutely 💀 lol

Thank you Adam. I've updated the doc.

@saghosh it's a great start. You still only have mention of the callback approach in the function signature though:

structFind(structure, closure, [, parallel][, maxThreadCount] )

You need to also list the key version:

structFind(structure, key)

I note now you have you have a duplicated comma in that first version:

, [, parallel]

, and the spacing around the paretheses is uniform and a bit sloppy (ie:

(

vs

)

. Also note: the function doesn't take a closure as the that parameter value, it takes a function. Those are two different things: a closure is a subset of function, but

structFind

takes any user-defined function, be it defined via statement or expression. Lastly I note there is some behaviour that is not documented, and probably ought to be: https://trycf.com/gist/11243a998180b10b46ad2e523e5927d9/acf2021?theme=monokai

normal = {
    "tahi" = "one",
    "two" = "rua",
    "toru" = "toru",
    "four" = "four"
}


function keyValueMatcher(k, v) { // not a closure
    return k == v
}

result = normal.find(keyValueMatcher)
writeDump(result)

ordered = [
    "tahi" = "one",
    "two" = "rua",
    "toru" = "toru",
    "four" = "four"
]
result = ordered.find(keyValueMatcher)
writeDump(result)

four toru

A matcher handler could match more than one element in the struct. What should the behaviour even be here? On an ordered struct, it's clear it's returning the first match. What's the behaviour for an unodered sruct? I presume it needs to be documented as "any one match, and which specific match it is is not guaranteed"? There's no sense of "first" in a data structure that is unordered. I could even see a case for it throwing an exception if there's this sort of ambiguity. Anyhow, all the docs need to do is clearly state what happens.