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

(info "(elisp) Creating Hash")

Add Entry

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

(info "(elisp) Hash Tables")

Emacs Lisp Hash Table

Lisp Data Structure

ErgoEmacs mascot-s276x226
Buy Xah Emacs Tutorial

Lisp Basics

Basics

Lisp Data Structure

Function

Lisp Symbol

Lisp Misc

Working with Elisp