Function Definitions

9 - List Manipulation

car ..... Returns the first element from a list. When used with a point (a list of three coordinates) car extracts the X coordinate. See note below.

(car (list 2 4 6 8)) returns 2
(car (list 2.75 8.875 3.00)) returns 2.75
(car (list (list 1 2) (list 3 4) (list 5 6) (list 7 8))) returns (1 2)

cadr ..... Returns the second element from a list. When used with a point (a list of three coordinates) cadr extracts the Y coordinate. See note below.

(cadr (list 2 4 6 8)) returns 4
(cadr (list 2.75 8.875 3.00)) returns 8.875
(cadr (list (list 1 2) (list 3 4) (list 5 6) (list 7 8))) returns (3 4)

caddr ..... Returns the third element from a list. When used with a point (a list of three coordinates) caddr extracts the Z coordinate. See note below.

(caddr (list 2 4 6 8)) returns 6
(caddr (list 2.75 8.875 3.00)) returns 3.00
(caddr (list (list 1 2) (list 3 4) (list 5 6) (list 7 8))) returns (5 6)

cdr ..... Returns a list containing all elements but the first. See note below.

(cdr (list 2 4 6 8)) returns (4 6 8)
(cdr (list (list 1 2) (list 3 4) (list 5 6) (list 7 8))) returns ((3 4) (5 6) (7 8))
(cdr (list 9)) returns nil

NOTE regarding the four functions listed above (car, cadr, caddr, and cdr):

The names "car," "cadr," etc. are derived from the way a list is stored in memory. Each element in a list is stored in two adjacent registers -- an address register and a decrement register. The address register holds the value, the decrement register holds a pointer to the next pair of registers. "car" stands for contents of address register, while "cdr" stands for contents of decrement register. These are the two basic functions and all other similar functions are derived from them by combining them in various ways. For example, cadr is an abbreviation for (car (cdr ___)), and caddr is an abbreviation for (car (cdr (cdr ___))). These and other combinations are illustrated below.

After (setq L1 (list 1 2 3 4 5 6 7 8 9))
(car L1) returns 1
(cdr L1) returns (2 3 4 5 6 7 8 9)
(car (cdr L1)) returns 2 (compare next example)
(cadr L1) returns 2 (compare previous example)
(car (cdr (cdr L1))) returns 3 (compare next example)
(caddr L1) returns 3 (compare previous example)
(car (cdr (cdr (cdr L1)))) returns 4 (compare next example)
(cadddr L1) returns 4 (compare previous example)

AutoLISP includes, as built-in functions, not only the two basic functions car and cdr, but all the abbreviated combinations involving up to four a's and/or d's, as shown below.

a
d

............

aa
ad
da
dd

............

aaa
aad
ada
add
daa
dad
dda
ddd

............

aaaa
aaad
aada
aadd
adaa
adad
adda
addd
daaa
daad
dada
dadd
ddaa
ddad
ddda
dddd

When dealing with nested lists, remember that car, cdr, and their derived functions all deal with top level elements as illustrated below.

After (setq L2 (list "one" (list "two" "three") "four"))
(cdr L2) returns (("two" "three") "four")
(cadr L2) returns ("two" "three")
(caadr L2) returns "two"
(cadadr L2) returns "three"

Dotted pairs are stored differently than regular lists. They occupy two adjacent registers, but the second register holds a value rather than a pointer. Thus, when dealing with a dotted pair, cdr return the second element as an atom, as shown below.

After (setq L3 (cons 5 6)), which produces the dotted pair (5 . 6) and assigns it to L3
(cdr L3) returns 6 (notice that an atom is returned, not a list)

nth ..... Returns the nth element of a list, the first element is numbered 0

After (setq L1 (list 2 4 6 8))
(nth 0 L1) returns 2
(nth 2 L1) returns 6
(nth 4 L1) returns nil
After (setq L2 (list "a" (list "b" "c") "d" "e" (list "f" "g")))
(nth 1 L2) returns ("b" "c")
(nth 5 L2) returns nil

last ..... Returns the last element of a list

(last (list "one" "two" "three" "four")) returns "four"
After (setq L1 (list 9 8 7))
(last L1) returns 7

reverse ..... Returns a list with its elements in reverse order

(reverse (list 5.0 10.0 15.0) returns (15.0 10.0 5.0)
(reverse (list 1 (list 2 3) 4 5)) returns (5 4 (2 3) 1)

list ..... Groups one or more expressions into a list and returns the list

(list 2.5 3.5 0.0) returns (2.5 3.5 0.0) This is a typical use of the list function -- to define a point by grouping its X, Y, and Z coordinates.
(list "a" (list "b" "c")) returns ("a" ("b" "c"))

cons ..... Adds an element at the beginning of a list

(cons "toast" (list "with" "jam")) returns ("toast" "with" "jam")
After (setq a 11 b (list 12 13 14))
(cons a b) returns (11 12 13 14)

cons creates a dotted pair when the second argument is an atom
(cons "m" "n") returns ("m" . "n")
(cons 40 0.5) returns (40 . 0.5)
After (setq w 1.25)
(cons 40 w) returns (40 . 12.5)

append ..... Combines two or more lists into one list. All arguments must be lists.

(append (list 1 2 3) (list 4 5)) returns (1 2 3 4 5)
The above is different than (list (list 1 2 3) (list 4 5)) which would return ((1 2 3) (4 5))
After (setq L1 (list "see" "hear") L2 (list "smell" "taste") L3 (list "touch"))
(append L1 L2 L3) returns ("see "hear" "smell" "taste" "touch")

length ..... Returns an integer indicating the number of top-level elements in a list

(length (list 88 87 86 85)) returns 4
(length (list 1 (list 2 3) 4 (list 5 6 7))) returns 4
(length ()) returns 0

member ..... Searches for an expression in a list and returns a list containing the expression and the remainder of the list

(member "b" (list "a" "b" "c" "d")) returns ("b" "c" "d")
(member "b" (list "e" "f" "g" "h")) returns nil
(member "b" (list (list "a" "b") (list "c" "d"))) returns nil. The expression must be a top-level expression in the list in order to be found.

assoc ..... Searches an association list for a key element and returns the sublist starting including the key element.

After (setq carlist (list (list "year" "1940") (list "make" "buick") (list "model" "sedan")))
(assoc "make" carlist) returns ("make" "buick")

subst ..... Returns a list which substitutes one element for another in a given list

(subst 9 3 (list 1 2 3 4 5)) returns (1 2 9 4 5)
(subst 9 6 (list 1 2 3 4 5)) returns (1 2 3 4 5)
(subst (list "p" "q" "r") "c" (list "a" "b" "c" "d" "e")) returns ("a" "b" ("p" "q" "r") "d" "e")

acad_strlsort ..... Accepts a list of strings and returns a list containing the same strings sorted alphabetically

After (setq L1 (list "carrot" "apple" "dart" "board"))
(acad_strlsort L1) returns ("apple" "board" "carrot" "dart")

HOME