Skip to main content

gethash

gethash Accessor

Syntax:

gethash key hash-table &optional default → value, present-p

(setf (gethash key hash-table &optional default) new-value)

Arguments and Values:

key—an object.

hash-table—a hash table.

default—an object. The default is nil.

value—an object.

present-p—a generalized boolean.

Description:

Value is the object in hash-table whose key is the same as key under the hash-table’s equivalence test. If there is no such entry, value is the default.

Present-p is true if an entry is found; otherwise, it is false.

setf may be used with gethash to modify the value associated with a given key, or to add a new entry. When a gethash form is used as a setf place, any default which is supplied is evaluated according to normal left-to-right evaluation rules, but its value is ignored.

Examples:

(setq table (make-hash-table)) → #<HASH-TABLE EQL 0/120 32206334> 
(gethash 1 table) → NIL, *false* 
(gethash 1 table 2) → 2, *false* 
(setf (gethash 1 table) "one") → "one" 
(setf (gethash 2 table "two") "two") → "two" 
(gethash 1 table) → "one", *true* 
(gethash 2 table) → "two", *true* 
(gethash nil table) → NIL, *false* 
(setf (gethash nil table) nil) → NIL 
(gethash nil table) → NIL, *true* 
(defvar \*counters\* (make-hash-table)) → \*COUNTERS\* 
(gethash ’foo \*counters\*) → NIL, *false* 
(gethash ’foo \*counters\* 0) → 0, *false* 

(defmacro how-many (obj) ‘(values (gethash ,obj \*counters\* 0))) → HOW-MANY 
(defun count-it (obj) (incf (how-many obj))) → COUNT-IT 
(dolist (x ’(bar foo foo bar bar baz)) (count-it x)) 
(how-many ’foo) → 2 
(how-many ’bar) → 3 
(how-many ’quux) → 0

See Also:

remhash

Notes:

The secondary value, present-p, can be used to distinguish the absence of an entry from the presence of an entry that has a value of default.

Expanded Reference: gethash​

Basic Lookup and Storage​

gethash retrieves values by key, returning two values: the value (or default) and a boolean indicating whether the key was found.

(let ((ht (make-hash-table)))
  (setf (gethash 'color ht) "blue")
  (gethash 'color ht))
=> "blue"
=> T

Missing Keys and Defaults​

When a key is not found, gethash returns nil and nil. An optional third argument provides a custom default.

(let ((ht (make-hash-table)))
  ;; Key not present: returns NIL, NIL
  (gethash 'missing ht))
=> NIL
=> NIL

(let ((ht (make-hash-table)))
  ;; Custom default value
  (gethash 'missing ht :not-found))
=> :NOT-FOUND
=> NIL

Distinguishing NIL Values from Missing Keys​

The second return value is essential when nil is a valid stored value.

(let ((ht (make-hash-table)))
  (setf (gethash 'flag ht) nil)
  ;; The value is NIL, but the key IS present
  (multiple-value-bind (value present-p)
      (gethash 'flag ht)
    (list value present-p)))
=> (NIL T)

(let ((ht (make-hash-table)))
  ;; The key is NOT present at all
  (multiple-value-bind (value present-p)
      (gethash 'flag ht)
    (list value present-p)))
=> (NIL NIL)

Using setf with gethash​

setf of gethash inserts or updates an entry.

(let ((ht (make-hash-table :test #'equal)))
  ;; Insert
  (setf (gethash "x" ht) 10)
  ;; Update
  (setf (gethash "x" ht) 20)
  (gethash "x" ht))
=> 20
=> T

Counting Pattern with incf​

;; incf works with gethash when a default of 0 is provided
(let ((counts (make-hash-table)))
  (dolist (item '(a b a c a b))
    (incf (gethash item counts 0)))
  (values (gethash 'a counts)
          (gethash 'b counts)
          (gethash 'c counts)))
=> 3
=> 2
=> 1

Building a Lookup Table​

;; Creating a simple lookup table for HTTP status codes
(let ((status (make-hash-table)))
  (setf (gethash 200 status) "OK"
        (gethash 404 status) "Not Found"
        (gethash 500 status) "Internal Server Error")
  (values (gethash 200 status)
          (gethash 404 status)
          (gethash 999 status "Unknown")))
=> "OK"
=> "Not Found"
=> "Unknown"