Next: Boolean Tests, Previous: Accumulations, Up: Gathering Clauses
A finder is a clause whose value is an expression that meets some condition.
&optionally
into
var on-failure
failure-valueIf test (which is an expression) ever evaluates to non-
nil
, the loop is terminated, the epilogue code is run and the value of expr is returned. Otherwise,nil
(or failure-value, if provided) is returned. If var is provided, it will have either the non-nil
value of expr or failure-value when the epilogue code is run.As a special case, if the test expression is a sharp-quoted function, then it is applied to expr instead of being simply evaluated. E.g.
(finding x such-that #'evenp)
is equivalent to(finding x such-that (evenp x))
.
On-failure
is a misnomer. Because it is always evaluated, it behaves more like the default third argument to thegethash
function. As a result,on-failure (error "Not found")
makes no sense. Instead, the clausesleave
orthereis
can be used in conjunction withfinally
as follows:(iter (for x in '(1 2 3)) (if (evenp x) (leave x)) (finally (error "not found")))This clause may appear multiple times when all defaults are identical. It can also be used together with either
always
/never
orthereis
if their defaults match. More specifically,on-failure nil
is compatible withthereis
, whileon-failure t
is compatible withalways
andnever
clauses.(iter (for i in '(7 -4 2 -3)) (if (plusp i) (finding i such-that (evenp i)) (finding (- i) such-that (oddp i))))
&optional
into
var&optional
into
varComputes the extremum (maximum or minimum) value of m-expr over all iterations, and returns the value of expr corresponding to the extremum. expr is evaluated inside the loop at the time the new extremum is established. If m-expr is never evaluated (due to, for example, being embedded in a conditional clause), then the returned value depends on the type, if any, of expr (or var, if one is supplied). If there is no type, the returned value will be \nil; if the type is numeric, the returned value will be zero.
For these two clauses, var may be a list of two symbols; in that case, the first is used to record expr and the second, m-expr.
As with
finding... such-that
, if m-expr is a sharp-quoted function, then it is called on expr instead of being evaluated.