set-car!, set-cdr! - change the fields of a pair

LIBRARY

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

RETURN VALUES

R6RS
These procedures return unspecified values.
R7RS
These procedures return an unspecified value.

EXAMPLES

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

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.

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.

COMPATIBILITY

When pair is a mutable pair, these procedures behave the same in all implementations.

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

SEE ALSO

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

STANDARDS

R4RS, IEEE Scheme, R5RS, R6RS, R7RS

HISTORY

These procedures first appeared with these names in R2RS. Earlier Scheme used the MacLisp functions rplaca and rplacd.

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.

Markup created by unroff 1.0sc,    March 04, 2023.