On this page:
cons
consp
car
cdr
append
binary-append
mv
revappend
list
list*
atom-listp
character-listp
endp
eqlable-listp
integer-listp
keyword-value-listp
listp
null
proper-consp
rational-listp
standard-char-listp
string-listp
symbol-listp
true-list-listp
true-listp
butlast
fix-true-list
len
make-list
nth
nthcdr
reverse
take
update-nth
first
second
third
fourth
fifth
sixth
seventh
eighth
ninth
tenth
last
rest
Version: 4.1
2.4.8 Lists

List functions can also be found in the sections on Association Lists, Sets, and Sequences.

(cons x y)

Creates a new pair containing x and y.

Examples:

  > (cons 1 nil)

  (1)

  > (cons 2 (cons 3 nil))

  (2 3)

  > (cons 4 5)

  (4 . 5)

(consp x)

Returns true when x is a pair.

Examples:

  > (consp nil)

  ()

  > (consp 5)

  ()

  > (consp "string")

  ()

  > (consp (cons 1 nil))

  t

  > (consp '(1 2 3))

  t

(car x)  t

  x : (or (consp x) (equal x nil))

Returns the first element of a cons-pair, or nil for nil.

Examples:

  > (car '(1 2 4 6))

  1

  > (car nil)

  ()

  > (car "violates guard")

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> (or/c "nil" (cons/c any/c any/c)) any) on

  here; expected <(or/c nil (cons/c any/c any/c))>, given:

  "violates guard"

(cdr x)  t

  x : (or (consp x) (equal x nil))

Returns the second element of a cons-pair, or nil for nil.

Examples:

  > (cdr '(1 2 4 6))

  (2 4 6)

  > (cdr nil)

  ()

  > (cdr "violates guard")

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> (or/c "nil" (cons/c any/c any/c)) any) on

  here; expected <(or/c nil (cons/c any/c any/c))>, given:

  "violates guard"

(append lst ...)

Concatenates all the elements in the given lists into one list. This a macro that expands into calls of the function binary-append.

Examples:

  > (append nil nil)

  ()

  > (append nil (list 1 2))

  (1 2)

  > (append (list 1 2) (list 3 4))

  (1 2 3 4)

  > (append 1 nil)

  append: expected argument of type <proper list>; given 1

(binary-append x y)  t

  x : (true-listp x)

  y : t

Concatenates two lists. Returns a new list containing all the items from x followed by all the items from y.

Examples:

  > (binary-append (list 1 2 3) (list 4 5 6))

  (1 2 3 4 5 6)

  > (binary-append (list 1 2 3) 4)

  (1 2 3 . 4)

  > (binary-append 5 "<-error")

  append: expected argument of type <proper list>; given 5

(mv x ...)

Form for returning multiple values. This is like list, but with the restriction that if a function returns using mv, then it must always return the same number of values.

Examples:

  > (mv 1 2 3 4)

  (1 2 3 4)

(revappend x y)  t

  x : (true-listp x)

  y : t

append the reverse of x to y.

Examples:

  > (revappend nil nil)

  ()

  > (revappend nil (list 1 2))

  (1 2)

  > (revappend (list 1 2) (list 3 4))

  (2 1 3 4)

  > (revappend (list 1 2) 3)

  (2 1 . 3)

  > (revappend "not a list" nil)

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> (listof any/c) any/c any) on here; expected

  <(listof any/c)>, given: "not a list"

(list elem ...)

Creates a new true list containing all the given elements.

Examples:

  > (list)

  ()

  > (list 1 2 3)

  (1 2 3)

(list* elem ... tail)

Uses cons to add each elem to tail.

Examples:

  > (list* 1 2 nil)

  (1 2)

  > (list* 5 6 '(7 8 9))

  (5 6 7 8 9)

  > (list* 1 2 3)

  (1 2 . 3)

  > (list*)

  list*: expects at least 1 argument, given 0

(atom-listp x)  t

  x : t

Reports whether x is a list of atoms.

Examples:

  > (atom-listp (list 2 3 4))

  t

  > (atom-listp (list (list 23 34) 45))

  ()

(character-listp x)  t

  x : t

Reports whether x is a list of characterp elements.

Examples:

  > (character-listp (list #\a #\b))

  t

  > (character-listp (list #\a "b"))

  ()

(endp x)  t

  x : (or (consp lst) (equal x nil))

Same as atom, but with the guard that x is either a consp or is nil.

Examples:

  > (endp nil)

  t

  > (endp (cons 2 nil))

  ()

  > (endp "violates guard")

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> (or/c "nil" pair?) any) on here; expected

  <(or/c nil pair?)>, given: "violates guard"

(eqlable-listp x)  t

  x : t

Reports whether x is a list of eqlablep elements.

Examples:

  > (eqlable-listp nil)

  t

  > (eqlable-listp (cons 4 nil))

  t

  > (eqlable-listp t)

  ()

(integer-listp x)  t

  x : t

Reports whether x is a list of integerp elements.

Examples:

  > (integer-listp nil)

  t

  > (integer-listp (list 24 -21 95))

  t

  > (integer-listp (list 53 44 "number"))

  ()

(keyword-value-listp x)  t

  x : t

Reports whether x is of even length and every other element in the list satisfies keywordp.

Examples:

  > (keyword-value-listp (list :a 1 :b 2 :c 3))

  t

  > (keyword-value-listp (list 'a 1 'b 'c 3))

  ()

(listp x)  t

  x : t

Reports whether x is either a consp or nil.

Examples:

  > (listp nil)

  t

  > (listp (cons 4 nil))

  t

  > (listp t)

  ()

(null x)  t

  x : t

Returns true if x equals nil (using eq).

Examples:

  > (null nil)

  t

  > (null (list 1 2 3))

  ()

(proper-consp x)  t

  x : t

Reports whether x is a proper (nil-terminated) nonempty list

Examples:

  > (proper-consp nil)

  ()

  > (proper-consp (list 1 2 3))

  t

  > (proper-consp (cons 1 2))

  ()

(rational-listp x)  t

  x : t

Reports whether x is a list of rationalp elements.

Examples:

  > (rational-listp (list 1 2/5 3))

  t

  > (rational-listp (list 1 2/5 "number"))

  ()

(standard-char-listp x)  t

  x : t

Reports whether x is a list of standard-char-p elements.

Examples:

  > (standard-char-listp (list #\a #\b #\c))

  t

  > (standard-char-listp (list 1 2 3))

  ()

(string-listp x)  t

  x : t

Reports whether x is a list of stringp elements.

Examples:

  > (string-listp (list "ab" "cd" "ef"))

  t

  > (string-listp (list 1 2 3))

  ()

(symbol-listp x)  t

  x : t

Reports whether x is a list of symbolp elements.

Examples:

  > (symbol-listp (list 'ab 'cd 'ef))

  t

  > (symbol-listp (list 1 2 3))

  ()

(true-list-listp x)  t

  x : t

Reports whether x is a list of true-listp elements.

Examples:

  > (true-list-listp (list 1 2 3 4 5))

  ()

  > (true-list-listp '((1) (2) (3) (4) (5)))

  t

(true-listp x)  t

  x : t

Reports whether x is a proper nil-terminated list.

Examples:

  > (true-listp (list 1 2 3 4 5))

  t

  > (true-listp "list")

  ()

(butlast l n)  t

  l : (true-listp l)

  n : (and (integerp n) (<= 0 n))

(butlast l n) is the list obtained by removing the last n elements from the true list l.

Examples:

  > (butlast nil 1)

  ()

  > (butlast (list 1 2 3) 1)

  (1 2)

  > (butlast (list 1 2 3) 3)

  ()

  > (butlast (list 1 2 3) 10)

  ()

  > (butlast (list 1 2 3) -1)

  drop-right: expected argument of type <non-negative exact

  integer>; given -1

(fix-true-list x)  t

  x : t

Coerces x to a true list by replacing the final cdr with nil.

Examples:

  > (fix-true-list (list 1 2 3))

  (1 2 3)

  > (fix-true-list (cons 1 (cons 2 3)))

  (1 2)

  > (fix-true-list "abc")

  ()

  > (fix-true-list 5)

  ()

(len lst)  t

  lst : t

Finds the length of the given list. Returns 0 if lst is not a list.

Examples:

  > (len nil)

  0

  > (len (list 1 2 3 4 5))

  5

  > (len "string")

  0

  > (len t)

  0

(make-list n)  true-listp

  n : (and (integerp n) (<= 0 n))

Make a list of the given size.

Examples:

  > (make-list 0)

  ()

  > (make-list 3)

  (() () ())

  > (make-list -1)

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/primitive-procedures/acl2-prims-scheme.scm:38:28:

  Dracula program broke the contract (case-> (->

  natural-number/c any) (-> natural-number/c

  (symbols ’:initial-element) any/c any)) on here;

  expected <natural-number/c>, given: -1

(nth n lst)  t

  n : (and (integerp n) (>= n 0))

  lst : (true-listp lst)

Gets the nth element of lst

Examples:

  > (nth 2 (list 1 2 3))

  3

  > (nth 4 (list 1 2 1))

  ()

  > (nth "string" (list 1 2 3))

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> natural-number/c (listof any/c) any) on

  here; expected <natural-number/c>, given: "string"

  > (nth 2 "string")

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> natural-number/c (listof any/c) any) on

  here; expected <(listof any/c)>, given: "string"

(nthcdr n lst)  t

  n : (and (integerp n) (>= n 0))

  lst : (true-listp lst)

Gets the nth cdr of the given list

Examples:

  > (nthcdr 2 (list 1 2 3))

  (3)

  > (nthcdr 3 (list 1 2 1))

  ()

(reverse x)  t

  x : (or (true-listp x) (stringp x))

Reverse the given list or string

Examples:

  > (reverse (list 1 2 3 4))

  (4 3 2 1)

  > (reverse "abcd")

  "dcba"

  > (reverse 12345)

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> (or/c string? (listof any/c)) any) on here;

  expected <(or/c string? (listof any/c))>, given: 12345

(take n l)  t

  n : (and (integerp n) (not (< n 0)))

  l : (true-listp l)

Examples:

  > (take 3 (list 1 2 3 4 5))

  (1 2 3)

  > (take 0 (list 1 2 3 4 5))

  ()

  > (take -1 (list 1 2 3 4 5))

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> natural-number/c any) on here; expected

  <natural-number/c>, given: -1

  > (take 2 (cons 1 2))

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> (or/c "nil" (cons/c any/c any/c)) any) on

  here; expected <(or/c nil (cons/c any/c any/c))>, given: 2

(update-nth n v lst)  t

  n : (and (integerp n) (<= 0 n))

  v : t

  lst : (true-listp l)

Replaces the nth (0-based) position in lst with the value v. If n is greater than the length of lst, then update-nth will add padding to the end of the list consisting of nil values.

Examples:

  > (update-nth 0 'z '(a b c d e))

  (z b c d e)

  > (update-nth 8 'z '(a b c d e))

  (a b c d e () () () z)

  > (update-nth -1 'z '(a b c d e))

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> natural-number/c any) on here; expected

  <natural-number/c>, given: -1

  > (update-nth 1 'z "not a list")

  /Volumes/Maldis/Users/cce/plt/research/dracula/release/src/l

  anguage/checking-proc.scm:36:21: Dracula program broke the

  contract (-> (or/c "nil" (cons/c any/c any/c)) any) on

  here; expected <(or/c nil (cons/c any/c any/c))>, given:

  "not a list"

(first lst)

first member of the list

Examples:

  > (first (list 1 2 3 4 5 6 7 8))

  1

(second lst)

Examples:

  > (second (list 1 2 3 4 5))

  2

(third lst)

Examples:

  > (third (list 1 2 3 4 5 6 7 8 9 10))

  3

(fourth lst)

fourth member of the list

Examples:

  > (fourth (list 1 2 3 4 5 6 7 8))

  4

(fifth lst)

fifth member of the list

Examples:

  > (fifth (list 1 2 3 4 5 6 7 8))

  5

(sixth lst)

Sixth member of the list

Examples:

  > (sixth (list 1 2 3 4 5 6 7 8 9 10))

  6

(seventh lst)

Examples:

  > (seventh (list 1 2 3 4 5 6 7 8 9 10))

  7

(eighth lst)

eighth member of the list

Examples:

  > (eighth (list 1 2 3 4 5 6 7 8))

  8

(ninth x)

Examples:

  > (ninth (list 1 2 3 4 5 6 7 8 9 10))

  9

(tenth lst)

Examples:

  > (tenth (list 1 2 3 4 5 6 7 8 9 10))

  10

(last lst)

last member of the list

Examples:

  > (last (list 1 2 3 4 5))

  (5)

(rest lst)

The same as cdr

Examples:

  > (rest (list 'w 'x 'y 'z))

  (x y z)