From: Bruno Haible Date: Tue, 29 Apr 2025 20:29:20 +0000 (+0200) Subject: hash: Add more comments. X-Git-Url: https://gitweb.git.savannah.gnu.org/gitweb/?a=commitdiff_plain;h=44f556ff499526dfbed2fde6929c536ae75b52fa;p=gnulib.git hash: Add more comments. * lib/hash.h (Hash_hasher, Hash_comparator, Hash_data_freer): Add comments. --- diff --git a/ChangeLog b/ChangeLog index bd50776c9f..4bde285e94 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2025-04-29 Bruno Haible + + hash: Add more comments. + * lib/hash.h (Hash_hasher, Hash_comparator, Hash_data_freer): Add + comments. + 2025-04-28 Bruno Haible sigsegv: Fix compilation error on Mac OS X 10.4/powerpc. diff --git a/lib/hash.h b/lib/hash.h index 397b421feb..4dfaf56d06 100644 --- a/lib/hash.h +++ b/lib/hash.h @@ -130,21 +130,36 @@ typedef bool (*Hash_processor) (void *entry, void *processor_data); extern size_t hash_do_for_each (const Hash_table *table, Hash_processor processor, void *processor_data); -/* - * Allocation and clean-up. - */ - /* Return a hash index for a NUL-terminated STRING between 0 and N_BUCKETS-1. This is a convenience routine for constructing other hashing functions. */ extern size_t hash_string (const char *string, size_t n_buckets) _GL_ATTRIBUTE_PURE; -extern void hash_reset_tuning (Hash_tuning *tuning); - +/* Return a hash code of ENTRY, in the range 0..TABLE_SIZE-1. + This hash code function must have the property that if the comparator of + ENTRY1 and ENTRY2 returns true, the hasher returns the same value for ENTRY1 + and for ENTRY2. + The hash code function typically computes an unsigned integer and at the end + performs a % TABLE_SIZE modulo operation. This modulo operation is performed + as part of this hash code function, not by the caller, because in some cases + the unsigned integer will be a 'size_t', in other cases an 'uintmax_t' or + even larger. */ typedef size_t (*Hash_hasher) (const void *entry, size_t table_size); + +/* Compare two entries, ENTRY1 (being looked up or being inserted) and + ENTRY2 (already in the table) for equality. Return true for equal, + false otherwise. */ typedef bool (*Hash_comparator) (const void *entry1, const void *entry2); + +/* This function is invoked when an ENTRY is removed from the hash table. */ typedef void (*Hash_data_freer) (void *entry); +/* + * Allocation and clean-up. + */ + +extern void hash_reset_tuning (Hash_tuning *tuning); + /* Reclaim all storage associated with a hash table. If a data_freer function has been supplied by the user when the hash table was created, this function applies it to the data of each entry before freeing that