[PATCH] hash: deprecate poorly-named hash_insert0: use hash_insert_if_absent

[Jim Meyering]

Here's a proposed change to rename/deprecate a function in hash.c that
was so poorly named (by me!) that it was harder than necessary to use.
AFAICS (google, codesearch), the only existing use is in di-set.c,
and I've adjusted that.

While I've deprecated the offending function, hash_insert0, given that
there are no other users, removing it altogether might be better.
Opinions?

>From 74153190cd1d0b89d05c4a2d4f89f78e103fc37f Mon Sep 17 00:00:00 2001
From: Jim Meyering <address@hidden>
Date: Fri, 18 Nov 2011 12:09:16 +0100
Subject: [PATCH] hash: deprecate poorly-named hash_insert0: use
 hash_insert_if_absent

* lib/hash.c (hash_insert_if_absent): Rename from hash_insert0.
Add a sentence to the comment.
(hash_insert0): New function that simply calls hash_insert_if_absent.
* lib/hash.h (hash_insert_if_absent): Declare it.
(hash_insert0): Add deprecation attribute.
(_GL_ATTRIBUTE_DEPRECATED): Define.
* lib/di-set.c (di_set_insert): Use hash_insert_if_absent,
not hash_insert0.
Prompted by a question from Matthew Booth <address@hidden>.
---
 ChangeLog    |   12 ++++++++++++
 NEWS         |    4 ++++
 lib/di-set.c |    2 +-
 lib/hash.c   |   15 +++++++++++++--
 lib/hash.h   |   19 +++++++++++++++++--
 5 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index a373317..ffa3c36 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2011-11-18  Jim Meyering  <address@hidden>
+
+       hash: deprecate poorly-named hash_insert0: use hash_insert_if_absent
+       * lib/hash.c (hash_insert_if_absent): Rename from hash_insert0.
+       Add a sentence to the comment.
+       (hash_insert0): New function that simply calls hash_insert_if_absent.
+       * lib/hash.h (hash_insert_if_absent): Declare it.
+       (hash_insert0): Add deprecation attribute.
+       (_GL_ATTRIBUTE_DEPRECATED): Define.
+       * lib/di-set.c (di_set_insert): Use hash_insert_if_absent,
+       not hash_insert0.
+
 2011-11-17  Paul Eggert  <address@hidden>

        * modules/getcwd (Depends-on): Add fdopendir.
diff --git a/NEWS b/NEWS
index 495c81b..0322bd2 100644
--- a/NEWS
+++ b/NEWS
@@ -12,6 +12,10 @@ User visible incompatible changes

 Date        Modules         Changes

+2011-11-18  hash            This module deprecates the hash_insert0 function
+                            using gcc's "deprecated" attribute.  Use the 
better-
+                            named hash_insert_if_absent equivalent.
+
 2011-11-04  openat          This module no longer provides the mkdirat()
                             function. If you need this function, you now need
                             to request the 'mkdirat' module.
diff --git a/lib/di-set.c b/lib/di-set.c
index 4730e75..2f78448 100644
--- a/lib/di-set.c
+++ b/lib/di-set.c
@@ -233,7 +233,7 @@ di_set_insert (struct di_set *dis, dev_t dev, ino_t ino)
     return -1;

   /* Put I into the inode set.  */
-  return hash_insert0 (ino_set, (void const *) i, NULL);
+  return hash_insert_if_absent (ino_set, (void const *) i, NULL);
 }

 /* Look up the DEV,INO pair in the set DIS.
diff --git a/lib/hash.c b/lib/hash.c
index 4d76f76..0e44913 100644
--- a/lib/hash.c
+++ b/lib/hash.c
@@ -1018,7 +1018,9 @@ hash_rehash (Hash_table *table, size_t candidate)
   return false;
 }

-/* Return -1 upon memory allocation failure.
+/* Insert ENTRY into hash TABLE if there is not already a matching entry.
+
+   Return -1 upon memory allocation failure.
    Return 1 if insertion succeeded.
    Return 0 if there is already a matching entry in the table,
    and in that case, if MATCHED_ENT is non-NULL, set *MATCHED_ENT
@@ -1033,7 +1035,8 @@ hash_rehash (Hash_table *table, size_t candidate)
    when the ENTRY value is a simple scalar, you must use hash_insert0.
    ENTRY must not be NULL.  */
 int
-hash_insert0 (Hash_table *table, void const *entry, void const **matched_ent)
+hash_insert_if_absent (Hash_table *table, void const *entry,
+                       void const **matched_ent)
 {
   void *data;
   struct hash_entry *bucket;
@@ -1113,6 +1116,14 @@ hash_insert0 (Hash_table *table, void const *entry, void 
const **matched_ent)
   return 1;
 }

+/* hash_insert0 is the deprecated name for hash_insert_if_absent.
+   .  */
+int
+hash_insert0 (Hash_table *table, void const *entry, void const **matched_ent)
+{
+  return hash_insert_if_absent (table, entry, matched_ent);
+}
+
 /* If ENTRY matches an entry already in the hash table, return the pointer
    to the entry from the table.  Otherwise, insert ENTRY and return ENTRY.
    Return NULL if the storage required for insertion cannot be allocated.
diff --git a/lib/hash.h b/lib/hash.h
index 9f694be..572032d 100644
--- a/lib/hash.h
+++ b/lib/hash.h
@@ -35,6 +35,16 @@
 #  define _GL_ATTRIBUTE_WUR /* empty */
 # endif

+# ifndef _GL_ATTRIBUTE_DEPRECATED
+/* The __attribute__((__deprecated__)) feature
+   is available in gcc versions 3.1 and newer.  */
+#  if __GNUC__ < 3 || (__GNUC__ == 3 && __GNUC_MINOR__ < 1)
+#   define _GL_ATTRIBUTE_DEPRECATED /* empty */
+#  else
+#   define _GL_ATTRIBUTE_DEPRECATED __attribute__ ((__deprecated__))
+#  endif
+# endif
+
 typedef size_t (*Hash_hasher) (const void *, size_t);
 typedef bool (*Hash_comparator) (const void *, const void *);
 typedef void (*Hash_data_freer) (void *);
@@ -85,8 +95,13 @@ void hash_free (Hash_table *);
 /* Insertion and deletion.  */
 bool hash_rehash (Hash_table *, size_t) _GL_ATTRIBUTE_WUR;
 void *hash_insert (Hash_table *, const void *) _GL_ATTRIBUTE_WUR;
-int hash_insert0 (Hash_table *table, const void *entry,
-                  const void **matched_ent);
+
+/* Deprecate this interface.  It has been renamed to hash_insert_if_absent.  */
+int hash_insert0 (Hash_table *table, /* FIXME: remove in 2013 */
+                  const void *entry,
+                  const void **matched_ent) _GL_ATTRIBUTE_DEPRECATED;
+int hash_insert_if_absent (Hash_table *table, const void *entry,
+                           const void **matched_ent);
 void *hash_delete (Hash_table *, const void *);

 #endif
--
1.7.8.rc2.3.g0911