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'.

Implementation of `map-elt' for maps that are arrays. In a map that is an array, the keys are the slot indices, and slot contents are the values.

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

Implementation of `map-elt' for maps that are hash-tables. In a map that is a hash-table, the keys in the table serve as the map keys and the associated values are the key values.

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

Implementation of `map-elt' for maps that are alists or plists. In a map that is a plist, property names are the keys, and the corresponding property values are the values of those keys. In a map that is an alist, the `car' of each cons cell is the key and the `cdr' is the value.

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