7.5.3.7 Searching

The procedures for searching elements in lists either accept a predicate or a comparison object for determining which elements are to be searched.

Scheme Procedure: find pred lst

Return the first element of lst that satisfies the predicate pred and #f if no such element is found.

Scheme Procedure: find-tail pred lst

Return the first pair of lst whose CAR satisfies the predicate pred and #f if no such element is found.

Scheme Procedure: take-while pred lst
Scheme Procedure: take-while! pred lst

Return the longest initial prefix of lst whose elements all satisfy the predicate pred.

take-while! is allowed, but not required to modify the input list while producing the result.

Scheme Procedure: drop-while pred lst

Drop the longest initial prefix of lst whose elements all satisfy the predicate pred.

Scheme Procedure: span pred lst
Scheme Procedure: span! pred lst
Scheme Procedure: break pred lst
Scheme Procedure: break! pred lst

span splits the list lst into the longest initial prefix whose elements all satisfy the predicate pred, and the remaining tail. break inverts the sense of the predicate.

span! and break! are allowed, but not required to modify the structure of the input list lst in order to produce the result.

Note that the name break conflicts with the break binding established by while (see Iteration mechanisms). Applications wanting to use break from within a while loop will need to make a new define under a different name.

Scheme Procedure: any pred lst1 lst2 …

Test whether any set of elements from lst1 lst2 … satisfies pred. If so, the return value is the return value from the successful pred call, or if not, the return value is #f.

If there are n list arguments, then pred must be a predicate taking n arguments. Each pred call is (pred elem1 elem2 … ) taking an element from each lst. The calls are made successively for the first, second, etc. elements of the lists, stopping when pred returns non-#f, or when the end of the shortest list is reached.

The pred call on the last set of elements (i.e., when the end of the shortest list has been reached), if that point is reached, is a tail call.

Scheme Procedure: every pred lst1 lst2 …

Test whether every set of elements from lst1 lst2 … satisfies pred. If so, the return value is the return from the final pred call, or if not, the return value is #f.

If there are n list arguments, then pred must be a predicate taking n arguments. Each pred call is (pred elem1 elem2 …) taking an element from each lst. The calls are made successively for the first, second, etc. elements of the lists, stopping if pred returns #f, or when the end of any of the lists is reached.

The pred call on the last set of elements (i.e., when the end of the shortest list has been reached) is a tail call.

If one of lst1 lst2 …is empty then no calls to pred are made, and the return value is #t.

Scheme Procedure: list-index pred lst1 lst2 …

Return the index of the first set of elements, one from each of lst1 lst2 …, which satisfies pred.

pred is called as (elem1 elem2 …). Searching stops when the end of the shortest lst is reached. The return index starts from 0 for the first set of elements. If no set of elements pass, then the return value is #f.

(list-index odd? '(2 4 6 9))      ⇒ 3
(list-index = '(1 2 3) '(3 1 2))  ⇒ #f
Scheme Procedure: member x lst [=]

Return the first sublist of lst whose CAR is equal to x. If x does not appear in lst, return #f.

Equality is determined by equal?, or by the equality predicate = if given. = is called (= x elem), ie. with the given x first, so for example to find the first element greater than 5,

(member 5 '(3 5 1 7 2 9) <) ⇒ (7 2 9)

This version of member extends the core member (see List Searching) by accepting an equality predicate.