diff options
Diffstat (limited to 'lisp/emacs-lisp/map.el')
| -rw-r--r-- | lisp/emacs-lisp/map.el | 22 |
1 files changed, 12 insertions, 10 deletions
diff --git a/lisp/emacs-lisp/map.el b/lisp/emacs-lisp/map.el index 9c19dfdda78..72ff5e2221d 100644 --- a/lisp/emacs-lisp/map.el +++ b/lisp/emacs-lisp/map.el @@ -71,7 +71,7 @@ to match if any element of ARGS fails to match." ,@(map--make-pcase-bindings args))) (defmacro map-let (keys map &rest body) - "Bind the variables in KEYS to the elements of MAP then evaluate BODY. + "Bind the variables in KEYS to the elements of MAP, then evaluate BODY. KEYS can be a list of symbols, in which case each element will be bound to the looked up value in MAP. @@ -192,7 +192,7 @@ or array." "Associate KEY with VALUE in MAP and return VALUE. If KEY is already present in MAP, replace the associated value with VALUE. -When MAP is an alist, test equality with TESTFN if non-nil, +If MAP is an alist, test equality with TESTFN if non-nil, otherwise use `equal'. MAP can be an alist, plist, hash-table, or array." @@ -318,7 +318,7 @@ The default implementation delegates to `map-do'." (cl-defgeneric map-apply (function map) "Apply FUNCTION to each element of MAP and return the result as a list. -FUNCTION is called with two arguments, the key and the value. +FUNCTION is called with two arguments, the key of an element and its value. The default implementation delegates to `map-do'." (let ((res '())) (map-do (lambda (k v) (push (funcall function k v) res)) map) @@ -339,7 +339,7 @@ The default implementation delegates to `map-apply'." map)) (cl-defgeneric map-values-apply (function map) - "Return the result of applying FUNCTION to each value in MAP. + "Return the result of applying FUNCTION to the value of each key in MAP. The default implementation delegates to `map-apply'." (map-apply (lambda (_ val) (funcall function val)) @@ -407,8 +407,9 @@ If MAP is a plist, TESTFN defaults to `eq'." (not (eq v (gethash key map v))))) (cl-defgeneric map-some (pred map) - "Return the first non-nil (PRED key val) in MAP. + "Return the first non-nil value from applying PRED to elements of MAP. Return nil if no such element is found. +PRED is called with two arguments: the key of an element and its value. The default implementation delegates to `map-do'." ;; FIXME: Not sure if there's much benefit to defining it as defgeneric, ;; since as defined, I can't think of a map-type where we could provide an @@ -422,7 +423,8 @@ The default implementation delegates to `map-do'." nil)) (cl-defgeneric map-every-p (pred map) - "Return non-nil if (PRED key val) is non-nil for all elements of MAP. + "Return non-nil if calling PRED on all elements of MAP returns non-nil. +PRED is called with two arguments: the key of an element and its value. The default implementation delegates to `map-do'." ;; FIXME: Not sure if there's much benefit to defining it as defgeneric, ;; since as defined, I can't think of a map-type where we could provide an @@ -436,7 +438,7 @@ The default implementation delegates to `map-do'." (defun map--merge (merge type &rest maps) "Merge into a map of TYPE all the key/value pairs in MAPS. -MERGE is a function that takes the target MAP, a KEY, and a +MERGE is a function that takes the target MAP, a KEY and its VALUE, merges KEY and VALUE into MAP, and returns the result. MAP may be of a type other than TYPE." ;; Use a hash table internally if `type' is a list. This avoids @@ -466,7 +468,7 @@ See `map-into' for all supported values of TYPE." (defun map-merge-with (type function &rest maps) "Merge into a map of TYPE all the key/value pairs in MAPS. When two maps contain the same key, call FUNCTION on the two -values and use the value returned by it. +values and use the value FUNCTION returns. Each of MAPS can be an alist, plist, hash-table, or array. See `map-into' for all supported values of TYPE." (let ((not-found (list nil))) @@ -502,8 +504,8 @@ See `map-into' for all supported values of TYPE." "Associate KEY with VALUE in MAP. If KEY is already present in MAP, replace the associated value with VALUE. -This operates by modifying MAP in place. -If it cannot do that, it signals a `map-not-inplace' error. +This operates by modifying MAP in place. If it cannot do that, +it signals the `map-not-inplace' error. To insert an element without modifying MAP, use `map-insert'." ;; `testfn' only exists for backward compatibility with `map-put'! (declare (advertised-calling-convention (map key value) "27.1"))) |