Function: map-elt

map-elt is a byte-compiled function defined in map.el.gz.

Signature

(map-elt MAP KEY &optional DEFAULT)

Documentation

Look up KEY in MAP and return its associated value.

If KEY is not found, return DEFAULT which defaults to nil.

TESTFN is the function to use for comparing keys. It is deprecated because its default and valid values depend on the MAP argument, and it was never consistently supported by the map.el API. Generally, alist keys are compared with equal, plist keys with eq, and hash-table keys with the hash-table's test function.

In the base definition, MAP can be an alist, plist, hash-table, or array.

Other relevant functions are documented in the map group.

Probably introduced at or before Emacs version 26.1.

Shortdoc

;; map
(map-elt (list 'bar 1 'foo 2 'baz 3) 'foo)
    => 2
  (map-elt (list '(bar . 1) '(foo . 2) '(baz . 3)) 'foo)
    => 2
  (map-elt [bar foo baz] 1)
    => foo
  (map-elt #s(hash-table data (bar 1 foo 2 baz 3)) 'foo)
    => 2

Implementations

(map-elt (MAP array) KEY &optional DEFAULT TESTFN) in `map.el'.

Undocumented

(map-elt (MAP hash-table) KEY &optional DEFAULT TESTFN) in `map.el'.

Undocumented

(map-elt (MAP list) KEY &optional DEFAULT TESTFN) in `map.el'.

Undocumented

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/map.el.gz
(cl-defgeneric map-elt (map key &optional default testfn)
  "Look up KEY in MAP and return its associated value.
If KEY is not found, return DEFAULT which defaults to nil.

TESTFN is the function to use for comparing keys.  It is
deprecated because its default and valid values depend on the MAP
argument, and it was never consistently supported by the map.el
API.  Generally, alist keys are compared with `equal', plist keys
with `eq', and hash-table keys with the hash-table's test
function.

In the base definition, MAP can be an alist, plist, hash-table,
or array."
  (declare
   ;; `testfn' is deprecated.
   (advertised-calling-convention (map key &optional default) "27.1")
   (gv-expander
    (lambda (do)
      (gv-letplace (mgetter msetter) `(gv-delay-error ,map)
        (macroexp-let2* nil
            ;; Eval them once and for all in the right order.
            ((key key) (default default) (testfn testfn))
          (funcall do
                   `(map-elt ,mgetter ,key ,default ,@(and testfn `(,testfn)))
                   (lambda (v)
                     (macroexp-let2 nil v v
                       `(condition-case nil
                            ;; Silence warnings about the hidden 4th arg.
                            (with-no-warnings
                              (map-put! ,mgetter ,key ,v ,testfn))
                          (map-not-inplace
                           ,(funcall msetter
                                     `(map-insert ,mgetter ,key ,v))
                           ;; Always return the value.
                           ,v)))))))))))