Skip to main content

member, member-if, member-if-not

member, member-if, member-if-not Function

Syntax:

member item list &key key test test-not → tail

member-if predicate list &key key → tail

member-if-not predicate list &key key → tail

Arguments and Values:

item—an object.

list—a proper list.

predicate—a designator for a function of one argument that returns a generalized boolean. test—a designator for a function of two arguments that returns a generalized boolean. test-not—a designator for a function of two arguments that returns a generalized boolean. key—a designator for a function of one argument, or nil.

tail—a list.

Description:

member, member-if, and member-if-not each search list for item or for a top-level element that satisfies the test. The argument to the predicate function is an element of list.

If some element satisfies the test, the tail of list beginning with this element is returned; otherwise nil is returned.

list is searched on the top level only.

Examples:

(member 2 ’(1 2 3)) → (2 3) 
(member 2 ’((1 . 2) (3 . 4)) :test-not #’= :key #’cdr) → ((3 . 4)) 
(member ’e ’(a b c d)) → NIL 
(member-if #’listp ’(a b nil c d)) → (NIL C D) 
(member-if #’numberp ’(a #\Space 5/3 foo)) → (5/3 FOO) 
(member-if-not #’zerop 
		 ’(3 6 9 11 . 12) 
		 :key #’(lambda (x) (mod x 3))) → (11 . 12)

Exceptional Situations:

Should be prepared to signal an error of type type-error if list is not a proper list.

See Also:

find, position, Section 3.6 (Traversal Rules and Side Effects)

Notes:

The :test-not parameter is deprecated.

The function member-if-not is deprecated.

In the following

(member ’a ’(g (a y) c a d e a f)) → (A D E A F)

the value returned by member is identical to the portion of the list beginning with a. Thus rplaca on the result of member can be used to alter the part of the list where a was found (assuming a check has been made that member did not return nil).

Expanded Reference: member, member-if, member-if-not​

Basic membership test with member​

member searches a list for an item. If found, it returns the tail of the list starting with that item; otherwise it returns NIL. The default test is eql.

(member 'c '(a b c d e))
=> (C D E)

(member 'z '(a b c d e))
=> NIL

Using member as a boolean test​

Since member returns a non-NIL tail when the item is found, it works naturally in boolean contexts.

(if (member 3 '(1 2 3 4 5))
    "found"
    "not found")
=> "found"

String membership with :test​

The default eql test does not work for strings. Use :test #'equal or :test #'string= for string comparison.

(member "b" '("a" "b" "c") :test #'equal)
=> ("b" "c")

(member "b" '("a" "b" "c"))
=> NIL

member-if: search with a predicate​

member-if searches for the first element that satisfies a predicate.

(member-if #'evenp '(1 3 5 4 7))
=> (4 7)

(member-if #'stringp '(1 :key "hello" 42))
=> ("hello" 42)

Using the :key argument​

The :key function extracts the part of each element to test against.

(member 'b '((a 1) (b 2) (c 3)) :key #'car)
=> ((B 2) (C 3))

(member-if #'evenp '((a 1) (b 2) (c 3)) :key #'cadr)
=> ((B 2) (C 3))

Practical use: finding and processing from a point​

Because member returns the tail of the list starting from the match, you can process everything from that point onward.

(let ((data '(setup load :start process1 process2 cleanup)))
  (rest (member :start data)))
=> (PROCESS1 PROCESS2 CLEANUP)