Emacs Lisp: Hash Table

By Xah Lee. Date: . Last updated: .

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

Create Hash Table

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

Returns a new hashtable.

Key or Value can be any lisp object (any type). Key type should be the same for all keys.

The :test 'equal is to specify what test to check key match. Tree possible choices by default:

  • 'eq → For keys of Symbol or int type.
  • 'eql → The default. Like 'eq, but can also test number equality between int and float.
  • 'equal → Like 'eql, but can also test strings.

[see Emacs Lisp: Test Equality]

if you want to use a different test, you have to write one by define-hash-table-test. see elisp manual.

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

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

Literal Expression for Hashtable

You can create a hash table by a literal expression, like this:

(setq xx
      #s(hash-table
         size 30
         test equal
         data (
               "aa" 3
               "bb" 9
               "cc" 5 )))

;; test
(equal (gethash "aa" xx ) 3)

Add Entry

puthash
(puthash KEY VALUE TABLE)
(let ((xx (make-hash-table :test 'equal)))
  (puthash 'aa 9 xx)
  xx
  )

;; #s(hash-table size 65 test equal rehash-size 1.5 rehash-threshold 0.8125 data (aa 9))

Remove Entry

remhash
(remhash KEY TABLE)

Remove KEY from TABLE.

(let ((xx (make-hash-table)))
  (puthash 'aa 9 xx)
  (puthash 'bb 10 xx)
  (remhash 'aa xx)
  xx
  )

;; #s(hash-table size 65 test eql rehash-size 1.5 rehash-threshold 0.8125 data (bb 10))

Check Key Exist

gethash
(gethash key table)

if a key exist, return key's value. Else, return nil

(let ((xx (make-hash-table :test 'equal)))
  (puthash 'aa 9 xx)
  (gethash 'bb xx)    ;  nil
  (gethash 'bb xx 10) ; 10
  )
gethash
(gethash key table default)

Return default if key does not exist.

Get Key's Value

(gethash "bb" myHash)

Number of Entries

(hash-table-count myHash)

Remove All Entries

(clrhash myHash)

Apply a Function to All Entries

maphash
(maphash f hashtable)

Apply a function to all entries in a hash table. The function f must take 2 arguments, key and value.

(setq xx (make-hash-table :test 'equal))
(puthash "aa" 19 xx)
(puthash "bb" 20 xx)
(puthash "dd" 17 xx)
(puthash "cc" 21 xx)

(maphash
   (lambda (k v)
     (princ (format "%s , %s" k v))
     (princ "\n"))
   xx
   )

Get All Keys

hash-table-keys
(hash-table-keys hash)

Return a list of keys in HASH-TABLE. (require 'subr-x)

New in Emacs 24.4 (Released 2014-10)

;; get all keys from a hash table

(setq xx
      #s(hash-table
         size 30
         test equal
         data (
               "aa" 3
               "bb" 9
               "cc" 5 )))

;; get all keys
(require 'subr-x)
(hash-table-keys xx) ; ("aa" "bb" "cc")

Get All Values

hash-table-values
(hash-table-values hash)

Return a list of values. (require 'subr-x)

New in Emacs 24.4 (Released 2014-10)

;; getting all keys from a hash table.

;; hash table
(setq xx (make-hash-table :test 'equal))
(puthash "aa" "19" xx)
(puthash "bb" "20" xx)

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

Reference

Emacs Lisp Hash Table

Lisp Data Structure

List

Specialized Lists

Vector

Sequence (List, Vector)

Hash Table