diff options
Diffstat (limited to 'lib/hash.h')
| -rw-r--r-- | lib/hash.h | 25 |
1 files changed, 14 insertions, 11 deletions
@@ -1,5 +1,5 @@ /* hash - hashing table processing. - Copyright (C) 1998-1999, 2001, 2003, 2009-2023 Free Software Foundation, + Copyright (C) 1998-1999, 2001, 2003, 2009-2024 Free Software Foundation, Inc. Written by Jim Meyering <meyering@ascend.com>, 1998. @@ -148,7 +148,7 @@ typedef void (*Hash_data_freer) (void *entry); /* 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 - entry. */ + entry. This function preserves errno, like 'free'. */ extern void hash_free (Hash_table *table); /* Allocate and return a new hash table, or NULL upon failure. The initial @@ -183,7 +183,9 @@ extern void hash_free (Hash_table *table); You should specify this function only if you want these functions to free all of your 'data' data. This is typically the case when your data is simply an auxiliary struct that you have malloc'd to aggregate several - values. */ + values. + + Set errno on failure; otherwise errno is unspecified. */ _GL_ATTRIBUTE_NODISCARD extern Hash_table *hash_initialize (size_t candidate, const Hash_tuning *tuning, @@ -192,7 +194,7 @@ extern Hash_table *hash_initialize (size_t candidate, Hash_data_freer data_freer) _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC (hash_free, 1); -/* Same as hash_initialize, but invokes xalloc_die on memory exhaustion. */ +/* Like hash_initialize, but invokes xalloc_die instead of returning NULL. */ /* This function is defined by module 'xhash'. */ _GL_ATTRIBUTE_NODISCARD extern Hash_table *hash_xinitialize (size_t candidate, @@ -204,7 +206,7 @@ extern Hash_table *hash_xinitialize (size_t candidate, _GL_ATTRIBUTE_RETURNS_NONNULL; /* Make all buckets empty, placing any chained entries on the free list. - Apply the user-specified function data_freer (if any) to the datas of any + Apply the user-specified function data_freer (if any) to the data of any affected entries. */ extern void hash_clear (Hash_table *table); @@ -218,25 +220,26 @@ extern void hash_clear (Hash_table *table); the table may receive at least CANDIDATE different user entries, including those already in the table, before any other growth of the hash table size occurs. If TUNING->IS_N_BUCKETS is true, then CANDIDATE specifies the - exact number of buckets desired. Return true iff the rehash succeeded. */ + exact number of buckets desired. Return true iff the rehash succeeded, + false (setting errno) otherwise. */ _GL_ATTRIBUTE_NODISCARD extern bool hash_rehash (Hash_table *table, size_t candidate); /* 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. - This implementation does not support duplicate entries or insertion of - NULL. */ + Return NULL (setting errno) if the storage required for insertion + cannot be allocated. This implementation does not support + duplicate entries or insertion of NULL. */ _GL_ATTRIBUTE_NODISCARD extern void *hash_insert (Hash_table *table, const void *entry); -/* Same as hash_insert, but invokes xalloc_die on memory exhaustion. */ +/* Same as hash_insert, but invokes xalloc_die instead of returning NULL. */ /* This function is defined by module 'xhash'. */ extern void *hash_xinsert (Hash_table *table, const void *entry); /* Insert ENTRY into hash TABLE if there is not already a matching entry. - Return -1 upon memory allocation failure. + Return -1 (setting errno) 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 |