Elisp: Hash Table

What is Hash Table

Hash table is a collection of (key and value) pairs.

Emacs lisp has 2 types of collection of (key and value) pairs.

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

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 are:

• 'eq → For keys of Symbol or int type.
• 'eql → The default. Like 'eq, but also for floats.
• 'equal → Like 'eql, but also for strings.

〔see Elisp: Equality Test〕

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 . See elisp manual.

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

(gethash "aa" xx )
;; 3

Length (Count of Entries)

(hash-table-count myHash)

Add Entry

puthash

(puthash KEY VALUE TABLE)

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

(puthash 'aa 9 xx)
;; 9

Remove Entry

remhash

(remhash KEY TABLE)

Remove KEY from TABLE.

(setq xx (make-hash-table))

(puthash 'aa 9 xx)
;; 9

(puthash 'bb 10 xx)
;; 10

(remhash 'aa xx)
;; nil

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)

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

• Hash Tables (ELISP Manual)