Satisfying a Two-Argument Test (ANSI and GNU Common Lisp Document)

Next: Satisfying a One-Argument Test, Previous: Rules about Test Functions, Up: Rules about Test Functions

#### 17.2.1 Satisfying a Two-Argument Test

When an object O is being considered iteratively against each element E_i of a sequence S by an operator F listed in Figure 17–2, it is sometimes useful to control the way in which the presence of O is tested in S is tested by F. This control is offered on the basis of a function designated with either a `:test` or `:test-not` argument.

      adjoin           nset-exclusive-or  search
      assoc            nsublis            set-difference
      count            nsubst             set-exclusive-or
      delete           nsubstitute        sublis
      find             nunion             subsetp
      intersection     position           subst
      member           pushnew            substitute
      mismatch         rassoc             tree-equal
      nintersection    remove             union
      nset-difference  remove-duplicates

      Figure 17–2: Operators that have Two-Argument Tests to be Satisfied

The object O might not be compared directly to E_i. If a `:key` argument is provided, it is a designator for a function of one argument to be called with each E_i as an argument, and yielding an object Z_i to be used for comparison. (If there is no `:key` argument, Z_i is E_i.)

The function designated by the `:key` argument is never called on O itself. However, if the function operates on multiple sequences (e.g., as happens in set-difference), O will be the result of calling the `:key` function on an element of the other sequence.

A `:test` argument, if supplied to F, is a designator for a function of two arguments, O and Z_i. An E_i is said (or, sometimes, an O and an E_i are said) to satisfy the test

if this `:test` function returns a generalized boolean representing true.

A `:test-not` argument, if supplied to F, is designator for a function of two arguments, O and Z_i. An E_i is said (or, sometimes, an O and an E_i are said) to satisfy the test

if this `:test-not` function returns a generalized boolean representing false.

If neither a `:test` nor a `:test-not` argument is supplied, it is as if a `:test` argument of `#'eql` was supplied.

The consequences are unspecified if both a `:test` and a `:test-not` argument are supplied in the same call to F.

Next: Satisfying a One-Argument Test, Previous: Rules about Test Functions, Up: Rules about Test Functions