The list is searched for an element that satisfies the test. If none is found, nil is returned; otherwise, the tail of list beginning with the first element that satisfied the test is returned. The list is searched on the top level only. These functions are suitable for use as predicates.

For example:

Note, in the last example, that the value returned by member is eq to the portion of the list beginning with a. Thus rplaca on the result of member may be used to alter the found list element, if a check is first made that member did not return nil.

See also find and position.

tailp is true if and only if there exists an integer n such that

list may be a dotted list (implying that implementations must use atom and not endp to check for the end of the list).

adjoin is used to add an element to a set, provided that it is not already a member. The equality test defaults to eql.

In general, the test may be any predicate; the item is added to the list only if there is no element of the list that “satisfies the test.”

adjoin deviates from the usual rules described in chapter 14 for the treatment of arguments named item and :key. If a :key function is specified, it is applied to item as well as to each element of the list. The rationale is that if the item is not yet in the list, it soon will be, and so the test is more properly viewed as being between two elements rather than between a separate item and an element.

See pushnew.

union takes two lists and returns a new list containing everything that is an element of either of the lists. If there is a duplication between two lists, only one of the duplicate instances will be in the result. If either of the arguments has duplicate entries within it, the redundant entries may or may not appear in the result. For example:

There is no guarantee that the order of elements in the result will reflect the ordering of the arguments in any particular way. The implementation is therefore free to use any of a variety of strategies. The result list may share cells with, or be eq to, either of the arguments if appropriate.

In general, the test may be any predicate, and the union operation may be described as follows. For all possible ordered pairs consisting of one element from list1 and one element from list2, the test is used to determine whether they “match.” For every matching pair, at least one of the two elements of the pair will be in the result. Moreover, any element from either list that matches no element of the other will appear in the result. All this is very general, but probably not particularly useful unless the test is an equivalence relation.

The :test-not argument can be useful when the test function is the logical negation of an equivalence test. A good example of this is the function mismatch, which is logically inverted so that possibly useful information can be returned if the arguments do not match. This additional “useful information” is discarded in the following example; mismatch is used purely as a predicate.

Using :test-not #’mismatch differs from using :test #’equalp, for example, because mismatch will determine that #(a b) and (a b) are the same, while equalp would regard them as not the same.

nunion is the destructive version of union. It performs the same operation but may destroy the argument lists, perhaps in order to use their cells to construct the result.

intersection takes two lists and returns a new list containing everything that is an element of both argument lists. If either list has duplicate entries, the redundant entries may or may not appear in the result. For example:

There is no guarantee that the order of elements in the result will reflect the ordering of the arguments in any particular way. The implementation is therefore free to use any of a variety of strategies. The result list may share cells with, or be eq to, either of the arguments if appropriate.

In general, the test may be any predicate, and the intersection operation may be described as follows. For all possible ordered pairs consisting of one element from list1 and one element from list2, the test is used to determine whether they “match.” For every matching pair, exactly one of the two elements of the pair will be put in the result. No element from either list appears in the result that does not match an element from the other list. All this is very general, but probably not particularly useful unless the test is an equivalence relation.

nintersection is the destructive version of intersection. It performs the same operation, but may destroy list1, perhaps in order to use its cells to construct the result. (The argument list2 is not destroyed.)

set-difference returns a list of elements of list1 that do not appear in list2. This operation is not destructive.

There is no guarantee that the order of elements in the result will reflect the ordering of the arguments in any particular way. The implementation is therefore free to use any of a variety of strategies. The result list may share cells with, or be eq to, either of the arguments if appropriate.

In general, the test may be any predicate, and the set difference operation may be described as follows. For all possible ordered pairs consisting of one element from list1 and one element from list2, the test is used to determine whether they “match.” An element of list1 appears in the result if and only if it does not match any element of list2. This is very general and permits interesting applications. For example, one can remove from a list of strings all those strings containing one of a given list of characters:

nset-difference is the destructive version of set-difference. This operation may destroy list1.

set-exclusive-or returns a list of elements that appear in exactly one of list1 and list2. This operation is not destructive.

There is no guarantee that the order of elements in the result will reflect the ordering of the arguments in any particular way. The implementation is therefore free to use any of a variety of strategies. The result list may share cells with, or be eq to, either of the arguments if appropriate.

In general, the test may be any predicate, and the set-exclusive-or operation may be described as follows. For all possible ordered pairs consisting of one element from list1 and one element from list2, the test is used to determine whether they “match.” The result contains precisely those elements of list1 and list2 that appear in no matching pair.

nset-exclusive-or is the destructive version of set-exclusive-or. Both lists may be destroyed in producing the result.

subsetp is a predicate that is true if every element of list1 appears in (“matches” some element of) list2, and false otherwise.