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. For example, if your keys are integers or lisp symbols, you can use :test eq. If your keys are strings, you must use :test equal, because (eq "x" "x") returns nil.

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

There are more options for make-hash-table. Alt+x describe-function for detail.

Literal Expression for Hashtable

if the key and value for the hashtable have “read syntax” (aka literal expression), then you can also create a hash table by a literal expression, like this:

(setq my-hash
         size 30
         test equal
         data (
               "joe" 3
               "jane" 9
               "liz" 5 )))

;; test
(gethash "joe" my-hash ) ; 3

(info "(elisp) Creating Hash")

For example, buffer is a datatype in emacs lisp, however, it does not have a read syntax. So, if you want buffer to be key or value in a hash table, you cannot use the literal expression above.

Add Entry


puthash key table

(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


(let ((myHash (make-hash-table :test 'equal)))
  (puthash 'aa 9 myHash)
  (gethash 'bb myHash)    ; ⇒ nil
  (gethash 'bb myHash 10) ; ⇒ 10

Complete Hash Table Example

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

;; 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
(gethash "jane" myHash)

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

Elisp Data Structure

  1. List
  2. Vector
  3. Sequence: List, Array
  4. Sequence Functions
  5. Map List/Vector
  6. Exit Loop/Function
  7. Association List
  8. Property List
  9. Symbol Property List
  10. Hash Table

If you have a question, put $5 at patreon and message me.
Or Buy Xah Emacs Tutorial
Or buy a nice keyboard: Best Keyboards for Emacs


Emacs Lisp