.EL File Format – Lists and hash tables

Cons cells and lists

A cons cell has two slots, the car and the cdr. A list is a chain of cells whose last cdr is nil; nil alone is the empty list. A cell whose cdr is not a list is a dotted pair, written (1 . 2). A list whose tail points back into itself is circular; printing it needs print-circle, and the reader writes #1=(a b . #1#) for it. Since Emacs 31, equal compares circular lists without signalling circular-list.

(let ((stack nil))
  (push 'a stack) (push 'b stack)   ; stack is (b a)
  (list (pop stack) (take 1 stack)))      ; => (b (a))
(flatten-tree '(1 (2 (3 nil)) 4))        ; => (1 2 3 4)
(number-sequence 0 10 5)                 ; => (0 5 10)

sort

(sort SEQ PREDICATE) sorts in place and returns the result, so keep the return value. Emacs 30 adds a second form, (sort SEQ &rest KEYWORD-ARGUMENTS), with :key (a function that gives the sort key), :lessp (default value<), :reverse and :in-place. In this form the default is to sort a copy. Emacs 30 also added the comparison function value<.

(sort '(3 1 2) :reverse t)               ; => (3 2 1), argument unchanged
(sort (list "b" "a") :key #'identity)    ; => ("a" "b")

Mapping and iteration

Association lists and property lists

An alist is a list of (KEY . VALUE) pairs. A plist is a flat list (KEY VALUE KEY VALUE …), written with keywords or symbols.

(let ((al '((a . 1) (b . 2))))
  (list (alist-get 'b al) (cdr (assq 'a al))))   ; => (2 1)
(plist-get '("x" 1 "y" 2) "y" #'equal)           ; => 2

Sequences and the seq library

The sequence functions work on lists, vectors, strings and bool-vectors: length, elt, copy-sequence, reverse, nreverse, sort, append (to a list), vconcat (to a vector), concat (to a string), sequencep. seq.el adds a generic, extensible interface; its functions put the sequence argument first.

(seq-let (a b &rest more) '(1 2 3 4)
  (list a b more))                         ; => (1 2 (3 4))
(seq-reduce #'+ [1 2 3] 0)                 ; => 6
(seq-into '(?a ?b) 'string)                ; => "ab"

map.el gives the same kind of interface for alists, plists, hash tables and arrays: map-elt, map-put!, map-keys, map-values, map-filter, map-apply, map-let.

Arrays, vectors and related types

An array has a fixed length and constant-time access by index. The read syntax of a vector is [a b c]; its elements are not evaluated.

Constant lists, vectors and strings in the source are shared with the code. Changing them with setcar, aset or nreverse is undefined, and the compiler warns about it in Emacs 30. Use copy-sequence or list to build a fresh object first.

Hash tables

A hash table is created with (make-hash-table &rest KEYWORDS).

The printed form is #s(hash-table test equal data (k1 v1 k2 v2)), which the reader accepts back. Keys that are strings need :test 'equal, since two equal strings are usually different objects. Since Emacs 27, eql and the hash functions treat NaNs consistently.

(let ((h (make-hash-table :test 'equal)))
  (puthash "one" 1 h)
  (puthash "two" 2 h)
  (list (gethash "one" h) (gethash "three" h 'none) (hash-table-count h)))
;; => (1 none 2)

Not described

Known, not yet covered

• Reference: the full argument lists of the seq- and map- functions, the generic functions behind them (cl-defgeneric methods for new sequence types), and the cl-lib sequence functions (cl-remove-if, cl-loop).
• Reference: the exact printed form of hash tables in each version, including the size, rehash-size and rehash-threshold entries of older versions.
• Reference: the full list of the cXXXr names and the additional list utilities of subr-x and cl-lib.

See also

• Data types – the types of Lisp objects and their read syntax
• Strings and characters – strings are sequences of characters
• Variables and scope – setf places and push
• Control structures – dolist, dotimes and loops
• Lists – the manual’s chapter on lists
• Sequences, Arrays, and Vectors – the manual’s chapter on sequences
• Hash Tables – the manual’s chapter on hash tables