memq, memv, member, memp - list lookup

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs lists))               ;R6RS
(import (scheme r5rs))              ;R7RS
(import (scheme base))              ;R7RS

SYNOPSIS

(memq obj list)
(member obj list)
(memv obj list)

(memp proc list)                    ;R6RS
(member obj list compare)           ;R7RS

DESCRIPTION

These procedures return the first sublist of list whose car satisfies a given condition, where the sublists of lists are the lists returned by (list-tail list k) for k less than the length of list.

The member, memv, and memq procedures look for the first occurrence of obj. If list does not contain an element satisfying the condition, then #f is returned.

The member procedure uses equal? to compare obj with the elements of list, while memv uses eqv? and memq uses eq?.

memp (R6RS)
The memp procedure applies proc to the cars of the sublists of list until it finds one for which proc returns a true value. Proc is always called in the same dynamic environment as memp itself. Proc should accept one argument and return a single value. Proc should not mutate list.
member (R7RS)
The member procedure uses compare to compare obj with the elements of list, if given, and equal? otherwise.

RETURN VALUES

Returns a single value which is either list, a tail of list, or #f.

EXAMPLES

(memq 'a '(a b c))
          =>  (a b c)

(memq 'b '(a b c))
          => (b c)

(memq 'a '(b c d))
          => #f

(memq (list 'a) '(b (a) c))
          => #f

(member (list 'a) '(b (a) c))
          => ((a) c)

(memq 101 '(100 101 102))   => unspecified
(memv 101 '(100 101 102))   => (101 102)

;; R7RS
(member "B" '("a" "b" "c") string-ci=?)
          => ("b" "c")

;; R6RS
(memp even? '(3 1 4 1 5 9 2 6 5))
          => (4 1 5 9 2 6 5)

APPLICATION USAGE

These procedures are used to search for an object in a list. It can be used as a simple way to implement sets and it's commonly used to look up data in property lists.

COMPATIBILITY

R6RS imposes the following responsibly on implementations:

The implementation must check that list is a chain of pairs up to the found element, or that it is indeed a list if no element is found. It should not check that it is a chain of pairs beyond the found element. The implementation must check the restrictions on proc to the extent performed by applying it as described. An implementation may check whether proc is an appropriate argument before applying it.

ERRORS

This procedure can raise exceptions with the following condition types:
&assertion (R6RS)
The wrong number of arguments was passed or an argument was outside its domain.
R7RS
The assertions described above are errors. Implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically.

SEE ALSO

eq?(3scm), assq(3scm), find(3scm), exists(3scm)

STANDARDS

R4RS, IEEE Scheme, R5RS, R6RS, R7RS

HISTORY

The member and memq procedures appear in MacLISP, so they would have been available in the first Scheme implementation. LISP 1.5 had a member procedure that returned true of the element was in the list.

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/.

BUGS

Programs should not use the more discriminating memq and memv when the object is not comparable with eq?(3scm) and eqv?(3scm), respectively.


Markup created by unroff 1.0sc,    March 04, 2023.