When an object O is being considered iteratively against each element Ei
of a sequence S by an operator F listed in the next figure, 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.
|
Figure 17.2: Operators that have Two-Argument Tests to be Satisfied
The object O might not be compared directly to Ei. If a :key argument is provided, it is a designator for a function of one argument to be called with each Ei as an argument, and yielding an object Zi to be used for comparison. (If there is no :key argument, Zi is Ei.)
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 Zi. An Ei is said (or, sometimes, an O and an Ei 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 Zi. An Ei is said (or, sometimes, an O and an Ei 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.
(remove "FOO" '(foo bar "FOO" "BAR" "foo" "bar") :test #'equal) → (foo bar "BAR" "foo" "bar") (remove "FOO" '(foo bar "FOO" "BAR" "foo" "bar") :test #'equalp) → (foo bar "BAR" "bar") (remove "FOO" '(foo bar "FOO" "BAR" "foo" "bar") :test #'string-equal) → (bar "BAR" "bar") (remove "FOO" '(foo bar "FOO" "BAR" "foo" "bar") :test #'string=) → (BAR "BAR" "foo" "bar") (remove 1 '(1 1.0 #C(1.0 0.0) 2 2.0 #C(2.0 0.0)) :test-not #'eql) → (1) (remove 1 '(1 1.0 #C(1.0 0.0) 2 2.0 #C(2.0 0.0)) :test-not #'=) → (1 1.0 #C(1.0 0.0)) (remove 1 '(1 1.0 #C(1.0 0.0) 2 2.0 #C(2.0 0.0)) :test (complement #'=)) → (1 1.0 #C(1.0 0.0)) (count 1 '((one 1) (uno 1) (two 2) (dos 2)) :key #'cadr) → 2 (count 2.0 '(1 2 3) :test #'eql :key #'float) → 1 (count "FOO" (list (make-pathname :name "FOO" :type "X") (make-pathname :name "FOO" :type "Y")) :key #'pathname-name :test #'equal) → 2