[PATCH] Add new function to test whether a key is present in a hash table.

[Philipp Stephani]

Such a function is useful because in Emacs Lisp, 'gethash' cannot
return whether the key is present as in Common Lisp, and using
'gethash' alone to test for presence is nontrivial.

* src/fns.c (Fhash_table_contains_p): New function.
* test/src/fns-tests.el (hash-table-contains-p): New unit test.
* doc/lispref/hash.texi (Hash Access): Document new function.
---
 doc/lispref/hash.texi | 12 ++++++++++++
 etc/NEWS              |  3 +++
 src/fns.c             | 10 ++++++++++
 test/src/fns-tests.el |  8 ++++++++
 4 files changed, 33 insertions(+)

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index ddd46a55ed..8848f0462e 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -195,6 +195,18 @@ Hash Access
 association in @var{table}.
 @end defun
 
+While it might be tempting to use @code{gethash} to check whether a
+key is present in a hash table, keep in mind that you often need to
+distinguish between @var{key} being absent and @var{key} being mapped
+to @var{default}.  To easily distinguish between these two cases,
+there's another function to explicitly check whether a key is present:
+
address@hidden hash-table-contains-p key table
+This function looks up @var{key} in @var{table}; it returns @code{t}
+if @var{key} is present, and @code{nil} otherwise.  The associated
+value is ignored.
address@hidden defun
+
 @defun puthash key value table
 This function enters an association for @var{key} in @var{table}, with
 value @var{value}.  If @var{key} already has an association in
diff --git a/etc/NEWS b/etc/NEWS
index 71569c95ad..5c9363c052 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -282,6 +282,9 @@ depending on the new customizable variable 
'read-answer-short'.
 Specifically, it puts the module name into 'load-history', prints
 loading messages if requested, and protects against recursive loads.
 
+** New function 'hash-table-contains-p' to check whether a hash table
+contains a certain key.
+
 
 * Changes in Emacs 27.1 on Non-Free Operating Systems
 
diff --git a/src/fns.c b/src/fns.c
index 47457e44c8..6075544c69 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -4650,6 +4650,15 @@ DEFUN ("clrhash", Fclrhash, Sclrhash, 1, 1, 0,
 }
 
 
+DEFUN ("hash-table-contains-p", Fhash_table_contains_p, Shash_table_contains_p,
+       2, 2, NULL,
+       doc: /* Return t if TABLE contains KEY, nil otherwise.  */)
+  (Lisp_Object key, Lisp_Object table)
+{
+  return hash_lookup (check_hash_table (table), key, NULL) >= 0 ? Qt : Qnil;
+}
+
+
 DEFUN ("gethash", Fgethash, Sgethash, 2, 3, 0,
        doc: /* Look up KEY in TABLE and return its associated value.
 If KEY is not found, return DFLT which defaults to nil.  */)
@@ -5145,6 +5154,7 @@ syms_of_fns (void)
   defsubr (&Shash_table_weakness);
   defsubr (&Shash_table_p);
   defsubr (&Sclrhash);
+  defsubr (&Shash_table_contains_p);
   defsubr (&Sgethash);
   defsubr (&Sputhash);
   defsubr (&Sremhash);
diff --git a/test/src/fns-tests.el b/test/src/fns-tests.el
index f8554636ba..f651ee8985 100644
--- a/test/src/fns-tests.el
+++ b/test/src/fns-tests.el
@@ -575,4 +575,12 @@ dot2
                                :type 'wrong-type-argument)
                  '(wrong-type-argument plistp (:foo 1 . :bar)))))
 
+(ert-deftest hash-table-contains-p ()
+  (let ((h (make-hash-table)))
+    (puthash 1.5 'foo h)
+    (puthash 2.5 nil h)
+    (should (equal (hash-table-contains-p 1.5 h) t))
+    (should (equal (hash-table-contains-p 2.5 h) t))
+    (should (equal (hash-table-contains-p 2 h) nil))))
+
 (provide 'fns-tests)
-- 
2.16.1