list-ref(3scm)

💖 list-ref — the manual, but make it a group chat 💖

okay so bestie, you're reading list-ref(3scm) from the Scheme Programmer's Manual, and honestly? this one's a little icon. it's the "gimme the *k*th thing outta this list" procedure. let's get into it 🎀

---

✨ NAME ✨

list-ref — access an element of a list. that's it. that's the whole vibe. she grabs one thing out of the list and hands it to you 🫶

---

📚 LIBRARY 📚

depending on which Scheme you're living in, import it like this (comments are the original flavor, keep 'em):

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

---

🌸 SYNOPSIS 🌸

(list-ref list k)

---

💅 DESCRIPTION 💅

so basically: returns the kth element of list. main character behavior fr fr, she just reaches in and pulls out exactly the one you asked for ✨

🌀 Circular lists 🌀

okay this is the part where it gets spicy 🌶️ — R7RS explicitly allows list to be circular. and R6RS also allows that, but it also limits the implementation to only checking that list is a chain of pairs whose length is at least k + 1. so like, R6RS is doing the bare minimum vibe check on it, no cap 💀

---

🎁 RETURN VALUES 🎁

returns a single value — one object from the list. just one. not a list of one. one object. periodt 👑

---

🧪 EXAMPLES 🧪

the classics, look:

(list-ref '(a b c d) 2)  =>  c
(list-ref '(a b c d)
          (exact (round 1.8)))
        =>  c

and now the fun one where we make a list eat its own tail 🐍🍓

(define lst (list 'a 'b 'c 'd))
(set-cdr! (cdddr lst) lst)   ;lst is now circular
(list-ref lst 4)
        =>  a

like?? she's circular and list-ref still ate that. iconic 💅🔥

---

🦋 COMPATIBILITY 🦋

except for different error behavior, this procedure works the same everywhere. that's it. she travels well, she's lowkey universal 🌈

---

😭 ERRORS 😭

this procedure can raise exceptions with the following condition types — heads up bestie, here's where it can go sideways:

• &assertion (R6RS) — the wrong number of arguments was passed or an argument was outside its domain. in particular, list must be a list whose length is at least k + 1, and k must be an exact nonnegative integer. no shortcut, no wiggle room 🙈
• 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 😭💀 (yes, that's the actual wording, and yes it's giving horror movie)

fr fr don't just assume it'll politely error. R7RS implementations are allowed to go feral.

---

👀 SEE ALSO 👀

go touch some grass (or these other pages): car(3scm), vector-ref(3scm), assoc(3scm) 💖

---

⭐ STANDARDS ⭐

R4RS, IEEE Scheme, R5RS, R6RS, R7RS — she's certified in all of them, an overachiever fr 🎓✨

---

🧚 HISTORY 🧚

this procedure first appeared in R2RS. a true elder, an OG, we respect her 👑💜

---

🫶 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/. go say hi to the maintainers, they're the real MVPs 💖

---

and that's a wrap bestie!! this page is dated 2023-01-29 and it's the list-ref(3scm) entry from the Scheme Programmer's Manual — go forth and index things responsibly 🌸💅✨