+/* Allocate and return a new hash table, or NULL upon failure. The
+ initial number of buckets is automatically selected so as to _guarantee_ that
+ you may insert at least CANDIDATE different user entries before any growth
+ of the hash table size occurs. So, if have a reasonably tight a-priori
+ upper bound on the
+ number of entries you intend to insert in the hash table, you may save some
+ table memory and insertion time, by specifying it here. If the
+ IS_N_BUCKETS field of the TUNING structure is true, the CANDIDATE argument
+ has its meaning changed to the wanted number of buckets.
+
+ TUNING points to a structure of user-supplied values, in case some fine
+ tuning is wanted over the default behavior of the hasher. If TUNING is
+ NULL, the default tuning parameters are used instead.
+
+ The user-supplied HASHER function should be provided. It accepts two
+ arguments ENTRY and TABLE_SIZE. It computes, by hashing ENTRY contents, a
+ slot number for that entry which should be in the range 0..TABLE_SIZE-1.
+ This slot number is then returned.
+
+ The user-supplied COMPARATOR function should be provided. It accepts two
+ arguments pointing to user data, it then returns true for a pair of entries
+ that compare equal, or false otherwise. This function is internally called
+ on entries which are already known to hash to the same bucket index.
+
+ The user-supplied DATA_FREER function, when not NULL, may be later called
+ with the user data as an argument, just before the entry containing the
+ data gets freed. This happens from within `hash_free' or `hash_clear'.
+ 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. */