append(3scm)

🎀 append(3scm) 🎀

okay bestie, welcome to the append(3scm) page from the Scheme Programmer's Manual — this is the little icon that glues your lists together and it's genuinely SO useful, i'm obsessed. let's get into it 💖

---

✨ NAME ✨

append — appends an object onto one list, or smashes multiple lists together. it's giving "group project but everyone actually shows up" 🫶

---

📚 LIBRARY 📚

like, which import do you need? here's the tea, one of these:

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

pick your era, they all serve 💅

---

🌸 SYNOPSIS 🌸

(append)
(append list ... obj)

that's it. that's the whole vibe check. ⭐

---

💫 DESCRIPTION 💫

So append returns a possibly improper list — and the way it builds it is: all the elements of the first list, then all the elements of the other lists, and then obj gets stapled on as the cdr of that final pair. no cap.

If obj is not a list, you get an improper list out of it. that's just how it do. 🦋

Called with zero arguments? you get the empty list back. (append) is literally just (). periodt.

And here's the detail that lowkey matters a lot: the return value is made from new pairs for every argument except the last one — the last one is merely placed at the end of the new structure. so like, the last argument isn't copied, it's just... relocated. main character energy, it gets to keep its own identity. 👑

---

🎁 RETURN VALUES 🎁

Returns a single value. If obj isn't a proper list, what comes back is an improper list. that's it, one value, no surprises (well, the improper-list thing, but we covered that). 💜

---

🔥 EXAMPLES 🔥

these are the receipts, run them in your head and watch it slay:

(append '(x) '(y))         =>  (x y)
(append '(a) '(b c d))     =>  (a b c d)
(append '(a (b)) '((c)))   =>  (a (b) (c))
(append '(a b) '(c . d))   =>  (a b c . d)
(append '() 'a)            =>  a
(append)                   =>  ()
(append 'a)                =>  a

look at that last one. (append 'a) returns a. no list. just a. iconic, honestly. 😭

---

🌈 COMPATIBILITY 🌈

except for differences in error behavior, this procedure works the same everywhere. so like, the vibes are portable, the error handling is where implementations get quirky. 🙈

---

💀 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. you did too much, bestie.
• 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. yeah. catastrophically. no pressure. 🔥

fr fr, that "fail catastrophically" line is not a joke, don't be out here passing nonsense and expecting mercy.

---

🫶 SEE ALSO 🫶

go read these next, they're the friend group:

• cons*(3scm)
• cons(3scm)
• list-tail(3scm)

---

⭐ STANDARDS ⭐

R4RS, IEEE Scheme, R5RS, R6RS, R7RS. certified everywhere. 💅

---

🧚 HISTORY 🧚

okay history time, and it's kind of a flex: the append procedure has existed in LISP since at least 1959. iykyk. 🎀

the variants before R3RS only accepted proper lists. then Scheme before R2RS, running on MacLISP, would accept any number of arguments — while in LISP 1.5 the procedure only accepted two arguments. two! that's it! imagine the restraint. 😭

---

👑 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 whole page, bestie — go forth and append responsibly 💖✨🌸

sign-off: this was append(3scm), dated 2023-02-08, from the scheme-manpages project. love u, bye! 🎀