Elisp: 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.

For alist and difference between hashtable, see Elisp: Association List

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. Alt+x 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")

Data Structure Topic

  1. Elisp: Sequence: List, Array
  2. Elisp: Vector
  3. Elisp: List
  4. Elisp: Association List
  5. Elisp: Property List
  6. Elisp: Symbol Property List
  7. Elisp: Map / Loop Thru List / Vector
  8. Elisp: Filter a List
  9. Elisp: Hash Table
Liket it? Put $5 at patreon. Or Buy Xah Emacs Tutorial. Thanks.