set-car!(3scm)

💖 NAME 💖

okay so this is set-car! and set-cdr! from the Scheme Programmer's Manual, and they literally change the fields of a pair. like, set-car! changes the car field and set-cdr! changes the cdr field — that's the whole assignment, bestie. periodt.

---

✨ LIBRARY ✨

where you get these from, depending on your flavor of Scheme:

(import (rnrs mutable-pairs))       ;R6RS
(import (scheme r5rs))              ;R7RS
(import (scheme base))              ;R7RS

---

🎀 SYNOPSIS 🎀

(set-car! pair obj)
(set-cdr! pair obj)

---

🌸 DESCRIPTION 🌸

Stores obj in the car or cdr field of pair, respectively. so set-car! puts obj in the car field, and set-cdr! puts obj in the cdr field. iconic behavior, no notes 💅

---

🦋 RETURN VALUES 🦋

• R6RS — These procedures return unspecified values. plural, bestie.
• R7RS — These procedures return an unspecified value. singular unspecified value this time.

---

🔥 EXAMPLES 🔥

here's the code, kept exactly as it is because code is sacred:

       (define (f) (list 'not-a-constant-list))
       (define (g) '(constant-list))
       (set-car! (f) 3)                  => unspecified
       (set-car! (g) 3)                  => unspecified
                  ; should raise &assertion exception

       (let ((x (list 'a 'b 'c 'a))
             (y (list 'a 'b 'c 'a 'b 'c 'a)))
         (set-cdr! (list-tail x 2) x)
         (set-cdr! (list-tail y 5) y)
         (list
          (equal? x x)
          (equal? x y)
          (equal? (list x y 'a) (list y x 'b))))
                  => (#t #t #f)

and yes, that comment is important: (set-car! (g) 3) should raise &assertion exception because (g) is giving constant-list energy. the outputs shown are unspecified, unspecified, and then the let expression gives (#t #t #f).

---

🌈 APPLICATION USAGE 🌈

These procedures are used to manipulate list structures. They can be quite confusing to use because of the normal issues caused by shared state. shared state is lowkey the villain of this whole page.

In some sense, these procedures are being phased out. Racket already uses immutable pairs, and R6RS moved these procedures to their own library to hide them away a little bit. Modern code that needs to mutate structures is often written with mutable records instead. so like… they're still here, but the vibe is very "legacy icon".

---

💀 COMPATIBILITY 💀

When pair is a mutable pair, these procedures behave the same in all implementations. no cap, that's the compatibility tea.

---

🚨 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. In particular, this is raised if pair is not a mutable pair. so if pair isn't mutable, it's giving &assertion, 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. "fail catastrophically" is doing a lot, but okay 😭

---

👀 SEE ALSO 👀

• vector-set!(3scm)
• record-mutator(3scm)

---

👑 STANDARDS 👑

R4RS, IEEE Scheme, R5RS, R6RS, R7RS. that's the whole standards squad ✨

---

🕰️ HISTORY 🕰️

These procedures first appeared with these names in R2RS. Earlier Scheme used the MacLisp functions rplaca and rplacd. so they've been around for a minute — not quite main character debut energy, but close.

---

🫶 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 🐛

It is an error to mutate constants from program code, but implementations do not have to check that this restriction is followed.

Because of this, sometimes a buggy program will work in an interpreter but fail when compiled. It is not portable (and generally not possible) to use these procedures to create self-modifying programs. so yeah — do not try to make your Scheme program edit itself like some sci-fi main character. it's not portable, and generally not possible. 💀

---

xoxo, this was set-car!(3scm), dated 2022-05-01 — leaving you with pair-mutation realness and a little Scheme Programmer's Manual sparkle 💜✨