cons(3scm)

💅 cons(3scm) — like, the pair-making icon

okay bestie, welcome to cons(3scm) from the Scheme Programmer's Manual 🎀 this is the one that makes pairs, and honestly? it's giving foundational. let's go ✨

📚 LIBRARY

import these, iykyk 🌸

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

✨ SYNOPSIS ✨

(cons obj1 obj2)

🦋 DESCRIPTION 🦋

So cons hands you back a newly allocated pair — its car is obj1 and its cdr is obj2. iconic behavior, no notes 💅

And like, the pair is guaranteed to be different (in the sense of eqv?) from every existing object. so it's literally a whole new vibe, not a recycled one 🫶

🔥 IMPLEMENTATION NOTES 🔥

ngl there's not a lot of room for differences between implementations of cons. the main difference is gonna be how fast a pair can be allocated and how allocation affects the garbage collector — that's the whole personality test right there 💀

An implementation can return a pair that cannot be changed (also known as an immutable pair), but heads up bestie — that is not standard 🙈

• Racket — Pairs in Racket are immutable. This does not apply to its R6RS language.

🎀 RETURN VALUES 🎀

Returns a new pair. and if the cdr is a list, then the return value is also considered to be a list. sneaky but slay 🌈

⭐ EXAMPLES ⭐

look at these, they ate:

(cons 'a '())         =>  (a)
(cons '(a) '(b c d))  =>  ((a) b c d)
(cons "a" '(b c))     =>  ("a" b c)
(cons 'a 3)           =>  (a . 3)
(cons '(a b) 'c)      =>  ((a b) . c)

💜 APPLICATION USAGE 💜

cons is used in programs that work with lists or other structures that consist of pairs. periodt.

but lowkey? in many cases it can be better to process a list with procedures like map(3scm), filter(3scm), fold-left(3scm), or one of the procedures from SRFI-1 👑

And for the bigger structures, you can create them with quasiquote(3scm) — which lets the code actually resemble the structure it creates. main character energy fr fr 🧚

🌸 RATIONALE 🌸

Pairs are a fundamental data structure. that's it, that's the whole reason 💀

💖 COMPATIBILITY 💖

The cons procedure appears in all Lisps. every single one. universal icon behavior 👑

🍓 ERRORS 🍓

This procedure can raise exceptions with the following condition types:

• &assertion (R6RS) — The wrong number of arguments was passed.
• 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.

😭 bestie note: "fail catastrophically" is real manpage text, not me being dramatic. R7RS said what it said.

🫶 SEE ALSO 🫶

• set-car!(3scm)
• set-cdr!(3scm)
• pairs(7scm)

🌈 STANDARDS 🌈

R4RS, IEEE Scheme, R5RS, R6RS, R7RS ✨ (it's in everything, the range is unmatched)

👑 HISTORY 👑

okay this part is genuinely so cool, gather round 🔥

The predecessor of cons was a subroutine cons(a,d,p,t) along with car, cdr, cpr, and ctr. The modern cons came from Herbert Gelernter and Carl Gerberich at IBM during the development of the FORTRAN List Processing Language (History of Lisp, John McCarthy, 1979).

The Lisp in MIT AI Memo No. 1 (September 1958) uses the four-argument cons. The modern two-argument cons appears in MIT AI Memo No. 3. we stan a glow-up 💅

🧚 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 💀

(the bugs section is empty — not me staring at it like 👁️👄👁️ — anyway)

---

okay that's the whole page bestie, go forth and cons responsibly 💜 this was cons(3scm) from the Scheme Programmer's Manual, dated 2020-08-19 — and yes, that empty BUGS section is canon, no cap 🎀✨