Emacs Lisp: Hash Table

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

• Association List (aka alist) → A ordered list of key val pairs. Keys may repeat. Slow for random access.
• Hash Table → Unordered set of key val pairs. No duplicate keys. Constant access time.

Create Hash Table

make-hash-table

(make-hash-table :test 'equal)

Returns a new hashtable.

The :test 'equal is to specify what function to use to test key existence. [see Emacs Lisp: Test Equality]

• If the keys are strings, use equal (it's error if you use string-equal)
• If the keys are all Symbol or all int, use eq
• Otherwise, in general, use equal (works for all above cases.)

Key or Value can be any lisp object (any type).

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)

Creating Hash (ELISP Manual)

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 :test 'equal)))
  (puthash 'aa 9 xx)
  (puthash 'bb 10 xx)
  (remhash 'aa xx)
  xx
  )

;; #s(hash-table size 65 test equal 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

;; 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

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

Hash Tables (ELISP Manual)