memq(3scm)

📦 version 0-unstable-2024-02, in nixpkgs unstable

💅 memq — list lookup (yeah, all four of them)

okay bestie, so this is a page from the Scheme Programmer's Manual and it's literally about finding stuff in lists. four little functions, one big vibe. let's go ✨

🫶 LIBRARY

import these depending on which flavour of Scheme you're living in:

  • (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

okay so here's the whole thing, no cap: these procedures return the first sublist of list whose car satisfies a given condition — and "sublists of list" means the lists you get back from (list-tail list k) for k less than the length of list. iconic behaviour.

member, memv and memq are all out here looking for the first occurrence of obj. If list doesn't contain an element satisfying the condition? congrats, you get #f back. 🙈

the difference is literally just the comparison function, and it's giving:

  • member uses equal? to compare obj with the elements of list
  • memv uses eqv?
  • memq uses eq?

🦋 memp (R6RS)

memp applies proc to the cars of the sublists of list until it finds one for which proc returns a true value. main character energy, honestly.

some rules bestie, don't come for me:

  • 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 R7RS member uses compare to compare obj with the elements of list, if given — and equal? otherwise. slay, configurable.

⭐ RETURN VALUES

returns a single value which is either list, a tail of list, or #f. that's it, that's the whole return value situation 💅

🌈 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)
not the memq 101 returning unspecified 💀 that's your warning right there, bestie — numbers and eq? are NOT it.

🔥 APPLICATION USAGE

these procedures are used to search for an object in a list. you can use them as a simple way to implement sets, and they're commonly used to look up data in property lists. like, genuinely useful, not just cute 🫶

👑 COMPATIBILITY

R6RS imposes the following responsibility on implementations (yes, responsibly, that's the original wording, I'm not touching it):

  • 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. 😭 catastrophic. the drama.

🧚 SEE ALSO

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

🍓 STANDARDS

R4RS, IEEE Scheme, R5RS, R6RS, R7RS — she's certified in literally all of them, periodt.

📜 HISTORY

member and memq appear in MacLISP, so they would have been available in the first Scheme implementation. like, they were there from day one, the OGs. and LISP 1.5 had a member procedure that returned true of the element was in the list.

ngl that last sentence is worded exactly like that in the original — "returned true of the element was in the list" — not my typo, I'm just the messenger 🙈

💖 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.

fr fr, this is the one that bites people. memq on numbers? memq on strings? don't do it bestie, use member and live your truth 💅

okay that's the whole page! this was the memq(3scm) page from the Scheme Programmer's Manual, dated 2021-03-06, and she ate. go find your elements, queen 👑✨

📦 where this page comes from