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?

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)
  (setq myHash (make-hash-table :test 'equal))
  (puthash 'joe "19" myHash)

  (gethash 'vicky myHash) ; ⇒ nil

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 Key-Value Pairs

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

;; from emacs 24.4 (require 'subr-x)

(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)

Get All Keys

In emacs 24.4, use hash-table-keys from (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")

With this function, you can use it like this: (get-hash-keys hashtable).

Get All Values

in emacs 24.4, use hash-table-values from (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 my keyboard store.