procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; Minor improvements for doc strings in map.el

Browse source 
* lisp/emacs-lisp/map.el (map-let, map-put, map-apply)
(map-values-apply, map-some, map-every-p, map--merge)
(map-merge-with, map-put!): Doc fixes.
This commit is contained in:
Eli Zaretskii 2025-01-23 12:29:04 +02:00
parent cda78edc7d
commit f751b3afa4
1 changed files with 12 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
lisp/emacs-lisp/map.el
View file

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