Emacs Lisp: Hash Table

By Xah Lee. Date: . Last updated: .

This page is a tutorial on emacs lisp hash table.

Emacs lisp has 2 types of list of key/value pairs.

What's the Difference Between Alist and Hash Table?

Alist is actually a list, with each element being a cons pair (cons key val). The element may repeat. The list is ordered. Emacs provides high level functions to let you use it as a key value pairs. See (info "(elisp) Association Lists")

emacs lisp hash table is a datatype by itself. (info "(elisp) Hash Tables")

Create Hash Table

(make-hash-table :test 'equal) → returns a new hashtable.

;; create a hash table
(setq myHash (make-hash-table :test 'equal))

The :test 'equal is to specify what function to use to test key existence. This is especially important if your keys are complex lisp objects.

Key or Value can be any lisp object (aka datatype).

There are more options for make-hash-table. Call describe-function for detail.

Add Entry


(puthash "joe" "19" myHash)

Remove Entry


(remhash "liz" myHash)

Get Key's Value


(gethash "jane" myHash)

Count Length


(hash-table-count myHash)

Remove All Entries

To clear all entries in a hash table, use (clrhash myHash).

Check If a Key Exists

To check if a key exists, use the (gethash myKey myHash). If it exists, its value is returned, else nil. Example:

(let ((myHash (make-hash-table :test 'equal)))

  (puthash 'aa 9 myHash)

  (gethash 'bb myHash) ; ⇒ nil

  (gethash 'bb myHash 10) ; ⇒ 10


gethash has a optional third parameter. If the key does not exist, that value is returned.

Complete Hash Table Example

Here's a complete code that shows how to create a hash table, then add, change, remove, entries:

(let (myHash val)

  ;; create a hash table
  (setq myHash (make-hash-table :test 'equal))

  ;; add entries
  (puthash "joe" "19" myHash)
  (puthash "jane" "20" myHash)
  (puthash "carrie" "17" myHash)
  (puthash "liz" "21" myHash)

  ;; modify a entry's value
  (puthash "jane" "16" myHash)

  ;; remove a entry
  (remhash "liz" myHash)

  ;; get a entry's value
  (setq val (gethash "jane" myHash))

  (message val) ; print it

Apply a Function to All Entries

(maphash myfun myHashtable) → apply a function to all entries in a hash table. The function myfun must take 2 arguments, key and value.

;; example of using maphash

(defsubst hash-table-keys (hash-table)
  "Return a list of keys in HASH-TABLE."
  (let ((keys '()))
    (maphash (lambda (k _v) (push k keys)) hash-table)

;; above is from emacs 24.4 subr-x.el

Get All Keys

(get-hash-keys hashtable) → returns a list of all keys. 〔It's in emacs 24.4, need (require 'subr-x)

;; emacs 24.4, example of getting all keys from a hash table

;; creating a hash
(setq myHash (make-hash-table :test 'equal))
(puthash "joe" "19" myHash)
(puthash "jane" "20" myHash)

;; get all keys
(require 'subr-x)
(hash-table-keys myHash) ; ⇒ ("jane" "joe")

Get All Values

(hash-table-values hashtable) → returns a list of all values. 〔It's in emacs 24.4, need (require 'subr-x)

;; getting all keys from a hash table.

;; creating a hash
(setq myHash (make-hash-table :test 'equal))
(puthash "joe" "19" myHash)
(puthash "jane" "20" myHash)

;; get all keys.
(require 'subr-x)          ; emacs 24.4
(hash-table-values myHash) ; ⇒ ("20" "19")
;; from emacs 24.4 (require 'subr-x)

(defsubst hash-table-values (hash-table)
  "Return a list of values in HASH-TABLE."
  (let ((values '()))
    (maphash (lambda (_k v) (push v values)) hash-table)

Hash to List

(defun xah-hash-to-list (hash-table)
  "Return a list that represent the HASH-TABLE
Each element is a list: (list key value).

See also, emacs 24.4's new functions.
 (require 'subr-x)

Version 2015-04-25"
  (let (result)
     (lambda (k v)
       (push (list k v) result))

Print All Entries Sorted by Key

Here's a example how you can print out all entries in a hash table by sorted key.

;; example of turning a hash table into list then sort it
(let (myHash myList)

  ;; add items to the hash
  (setq myHash (make-hash-table :test 'equal))
  (puthash "joe" "19" myHash)
  (puthash "jane" "20" myHash)
  (puthash "carrie" "17" myHash)
  (puthash "liz" "21" myHash)

  ;; get the hash table into a list
  (setq myList (xah-hash-to-list myHash))

  ;; sort and print it out
  (sort myList (lambda (a b) (string< (car a) (car b))))

;; prints (("carrie" "17") ("jane" "20") ("liz" "21") ("joe" "19"))

Warning: elisp's sort function is destructive. Once sort is used on a variable, that variable's value is essentially destroyed. (the sorted result is returned.) If you want to keep the variable, make a copy first.

(info "(elisp) Rearrangement")

(info "(elisp) Hash Tables")

Like it? Buy Xah Emacs Tutorial. Thanks.

or, buy something from Best Keyboard for Emacs