**(find: // [[harlowe:Lambda|lambda]], ...Any//) -> //[[harlowe:Array|array]]//** This searches through the given values, and produces an [[harlowe:array|array]] of those which match the given search test (which is expressed using a temp variable, the ''%%where%%'' keyword, and a [[harlowe:boolean|boolean]] condition). If none match, an empty array is produced. === Example usage: === * ''%%(find: _person where _person is not "Alice", ...$people)%%'' produces a subset of $people not containing the [[harlowe:string|string]] ''%%"Alice"%%''. * ''%%(find: _item where _item's 1st is "A", "Thorn", "Apple", "Cryptid", "Anchor")%%'' produces ''%%(a: "Apple", "Anchor")%%''. * ''%%(find: _num where (_num >= 12) and (it % 2 is 0), 9, 10, 11, 12, 13, 14, 15, 16)%%'' produces ''%%(a: 12, 14, 16)%%''. * ''%%(find: _val where _val + 2, 9, 10, 11)%%'' produces an error, because ''%%_item + 2%%'' isn't a boolean. * ''%%1st of (find: _room where _room's objs contains "Egg", ...$rooms)%%'' finds the first [[harlowe:datamap|datamap]] in $rooms whose "objs" contains the string ''%%"Egg"%%''. === Rationale: === Selecting specific data from arrays or sequences based on a user-provided boolean condition is one of the more common and powerful operations in programming. This macro allows you to immediately work with a subset of the array's data, without caring what kind of subset it is. The subset can be based on each string's characters, each datamap's values, each [[harlowe:number|number]]'s evenness or oddness, whether a variable matches it... anything you can write. This macro uses a [[harlowe:lambda|lambda]] (which is just the "temp variable ''%%where%%'' a condition" expression) to check every one of the values given after it. For ''%%(find: _item where _item > 40, 30, 60, 90)%%'', it will first check if ''%%30 > 40%%'' (which is ''%%false%%''), if ''%%60 > 40%%'' (which is ''%%true%%''), and if ''%%90 > 40%%'' (which is ''%%true%%''), and include in the returned array those values which resulted in ''%%true%%''. === Details: === Of course, if any condition should cause an error, such as checking if a number contains a number, then the error will appear. However, an error will NOT appear if you provide no values after the lambda - searching an empty sequence will simply result in an empty array being returned. This allows you to write `(find: $lambda, ...$array)` without checking whether $array contains any values (which you may not be certain of, if it contains the result of a previous (find:)). The temp variable, which you can name anything you want, is controlled entirely by the lambda - it doesn't exist outside of it, it won't alter identically-named temp variables outside of it, and you can't manually [[harlowe:set|(set:)]] it within the lambda. You can refer to other variables, including other temp variables, in the ''%%where%%'' condition. For instance, you can write ''%%(set: _name to "Eva")(find: _item where _item is _name, "Evan", "Eve", "Eva")%%''. However, for obvious reasons, if the outer temp variable is named the same as the lambda's temp variable, it can't be referred to in the condition. There isn't a way to examine the position of a value in the condition - you can't write, say, ''%%(find: _item where _pos % 2 is 0, "A", "B", "C", "D")%%'' to select just "B" and "D". You shouldn't use this macro to try and alter the given values! Consider the [[harlowe:altered|(altered:)]] or [[harlowe:folded|(folded:)]] macro instead. === See also: === [[harlowe:sorted|(sorted:)]], [[harlowe:all-pass|(all-pass:)]], [[harlowe:some-pass|(some-pass:)]], [[harlowe:none-pass|(none-pass:)]]