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

Probably introduced at or before Emacs version 26.1.

Implementations

(map 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.  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
   (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)
                   (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)))))))))
   ;; `testfn' is deprecated.
   (advertised-calling-convention (map key &optional default) "27.1"))
  ;; Can't use `cl-defmethod' with `advertised-calling-convention'.
  (map--dispatch map
    :list (if (map--plist-p map)
              (let ((res (plist-member map key)))
                (if res (cadr res) default))
            (alist-get key map default nil (or testfn #'equal)))
    :hash-table (gethash key map default)
    :array (if (map-contains-key map key)
               (aref map key)
             default)))