cons - construct a pair

LIBRARY

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

SYNOPSIS

(cons obj1 obj2)

DESCRIPTION

Returns a newly allocated pair whose car is obj1 and whose cdr is obj2. The pair is guaranteed to be different (in the sense of eqv?) from every existing object.

IMPLEMENTATION NOTES

There is not a lot of room for differences between implementations of cons. The main difference will be in how fast a pair can be allocated and how allocation affects the garbage collector.

It is possible for an implementation to return a pair that cannot be changed (also known as an immutable pair), but this is not standard.

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

RETURN VALUES

Returns a new pair. If the cdr is a list then the return value is also considered to be a list.

EXAMPLES

(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

The cons procedure is used in programs that work with lists or other structures that consist of pairs. 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.

Larger structures can be created with quasiquote(3scm), which lets the code resemble the structure it creates.

RATIONALE

Pairs are a fundamental data structure.

COMPATIBILITY

The cons procedure appears in all Lisps.

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.

SEE ALSO

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

STANDARDS

R4RS, IEEE Scheme, R5RS, R6RS, R7RS

HISTORY

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.

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

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