list-set!(3scm)

💅 list-set! — like, the one page where you get to change stuff in a list

okay so real talk, this is list-set!(3scm) from the Scheme Programmer's Manual, and honestly? she's a little icon. let's get into it 🎀

---

✨ NAME ✨

list-set! — modify an element in a list. yes bestie, that exclamation mark is doing work, it means she MUTATES 💀

---

📚 LIBRARY 📚

(import (scheme base))              ;R7RS

that's the import, no cap. (scheme base), and the comment says ;R7RS so you know where she comes from 🦋

---

🌸 SYNOPSIS 🌸

(list-set! list k obj)

three little arguments, that's the whole vibe ✨

---

💜 DESCRIPTION 💜

So what does she actually do? She stores obj in element k of list. That's it. That's the whole thing. She takes element number k and she's like "nope, we're putting obj there now" 💅

---

🫶 RETURN VALUES 🫶

Returns an unspecified value. like, she did the thing, she's not gonna brag about it, she just hands you back ~vibes~ and you move on 😌

---

🍓 EXAMPLES 🍓

okay this first one is giving main character energy:

(let ((ls (list 'one 'two 'five!)))
  (list-set! ls 2 'three)
  ls)
        => (one two three)

look at that glow-up 😭 five! got absolutely replaced by three and the list is thriving.

and then... the cautionary tale 🙈

(list-set! '(0 1 2) 1 "oops")
        error    ; constant list should not be mutated

⚠️ bestie DO NOT. that's a constant list and she should not be mutated. you will get an error and it will be embarrassing. we do not touch constants. periodt.

---

🧚 RATIONALE 🧚

This procedure was added in R7RS to round out the sequence operations. so like, she's the missing puzzle piece, the group chat member who finally joined, the one who completes the set 🔥

---

🌈 COMPATIBILITY 🌈

This procedure is unique to R7RS. nobody else has her like that 💅

An alternative? sure, you could use set-car!(3scm) and list-tail(3scm) — that's the route if you're feeling old-school — but honestly, why would you when she's right here 🦋

---

💀 ERRORS 💀

okay this is the serious part, lowkey:

It is an error if:

• the wrong number of arguments was passed, or
• an argument was outside its domain.

And in particular — this is the big one — it is an error if k is not a valid index of list. 🚨

Now, what happens then is genuinely implementation-dependent, and the manpage says it straight: implementations may signal an error, may extend the procedure's domain of definition to include such arguments, or may fail catastrophically 💀💀💀

yeah. fail catastrophically. they really wrote that. no cap. be careful with your k bestie 🙏

---

👑 SEE ALSO 👑

• set-car!(3scm) — the other one, go say hi 🫶

---

⭐ STANDARDS ⭐

R7RS — that's the standard, that's the whole standard, iconic behaviour ✨

---

🎀 HISTORY 🎀

This procedure first appeared in R7RS. her debut. her origin story. we love a queen who arrived fully formed 💖

---

🌸 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/ 🦋

---

and that's the page!! tysm for reading, go mutate something (not a constant tho, i'm literally begging you) 💜✨

— from the Scheme Programmer's Manual, dated 2023-08-13, page list-set!(3scm). mwah 💋