[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 78b4276: Improve documentation of 'assoc'
From: |
Eli Zaretskii |
Subject: |
master 78b4276: Improve documentation of 'assoc' |
Date: |
Wed, 18 Aug 2021 15:08:11 -0400 (EDT) |
branch: master
commit 78b427648b85d0f7e93ad5f18537ad9f2da055cb
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>
Improve documentation of 'assoc'
* doc/lispref/lists.texi (Association Lists):
* src/fns.c (Fassoc): Document how TESTFN is called. (Bug#50110)
---
doc/lispref/lists.texi | 10 ++++++----
src/fns.c | 3 ++-
2 files changed, 8 insertions(+), 5 deletions(-)
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index ac99835..bbe1dce 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1557,10 +1557,12 @@ of property lists and association lists.
@defun assoc key alist &optional testfn
This function returns the first association for @var{key} in
@var{alist}, comparing @var{key} against the alist elements using
-@var{testfn} if it is non-@code{nil} and @code{equal} otherwise
-(@pxref{Equality Predicates}). It returns @code{nil} if no
-association in @var{alist} has a @sc{car} equal to @var{key}. For
-example:
+@var{testfn} if it is a function, and @code{equal} otherwise
+(@pxref{Equality Predicates}). If @var{testfn} is a function, it is
+called with two arguments: the @sc{car} of an element from @var{alist}
+and @var{key}. The function returns @code{nil} if no
+association in @var{alist} has a @sc{car} equal to @var{key}, as
+tested by @var{testfn}. For example:
@smallexample
(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
diff --git a/src/fns.c b/src/fns.c
index 932800a..5126439 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -1755,7 +1755,8 @@ DEFUN ("assoc", Fassoc, Sassoc, 2, 3, 0,
doc: /* Return non-nil if KEY is equal to the car of an element of
ALIST.
The value is actually the first element of ALIST whose car equals KEY.
-Equality is defined by TESTFN if non-nil or by `equal' if nil. */)
+Equality is defined by the function TESTFN, defaulting to `equal'.
+TESTFN is called with 2 arguments: a car of an alist element and KEY. */)
(Lisp_Object key, Lisp_Object alist, Lisp_Object testfn)
{
if (eq_comparable_value (key) && NILP (testfn))
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master 78b4276: Improve documentation of 'assoc',
Eli Zaretskii <=