.TH "libwget-hashmap" 3 "Tue Jan 26 2021" "Version 1.99.1" "wget2" \" -*- nroff -*- .ad l .nh .SH NAME libwget-hashmap \- Hashmap functions .SH SYNOPSIS .br .PP .SS "Functions" .in +1c .ti -1c .RI "wget_hashmap_t * \fBwget_hashmap_create\fP (int max, wget_hashmap_hash_t hash, wget_hashmap_compare_t cmp)" .br .ti -1c .RI "int \fBwget_hashmap_put_noalloc\fP (wget_hashmap_t *h, const void *key, const void *value)" .br .ti -1c .RI "int \fBwget_hashmap_put\fP (wget_hashmap_t *h, const void *key, size_t keysize, const void *value, size_t valuesize)" .br .ti -1c .RI "int \fBwget_hashmap_get_null\fP (const wget_hashmap_t *h, const void *key, void **value)" .br .ti -1c .RI "void * \fBwget_hashmap_get\fP (const wget_hashmap_t *h, const void *key)" .br .ti -1c .RI "int \fBwget_hashmap_contains\fP (const wget_hashmap_t *h, const void *key)" .br .ti -1c .RI "int \fBwget_hashmap_remove\fP (wget_hashmap_t *h, const void *key)" .br .ti -1c .RI "int \fBwget_hashmap_remove_nofree\fP (wget_hashmap_t *h, const void *key)" .br .ti -1c .RI "void \fBwget_hashmap_free\fP (wget_hashmap_t **h)" .br .ti -1c .RI "void \fBwget_hashmap_clear\fP (wget_hashmap_t *h)" .br .ti -1c .RI "int \fBwget_hashmap_size\fP (const wget_hashmap_t *h)" .br .ti -1c .RI "int \fBwget_hashmap_browse\fP (const wget_hashmap_t *h, wget_hashmap_browse_t browse, void *ctx)" .br .ti -1c .RI "void \fBwget_hashmap_setcmpfunc\fP (wget_hashmap_t *h, wget_hashmap_compare_t cmp)" .br .ti -1c .RI "void \fBwget_hashmap_sethashfunc\fP (wget_hashmap_t *h, wget_hashmap_hash_t hash)" .br .ti -1c .RI "void \fBwget_hashmap_set_key_destructor\fP (wget_hashmap_t *h, wget_hashmap_key_destructor_t destructor)" .br .ti -1c .RI "void \fBwget_hashmap_set_value_destructor\fP (wget_hashmap_t *h, wget_hashmap_value_destructor_t destructor)" .br .ti -1c .RI "void \fBwget_hashmap_setloadfactor\fP (wget_hashmap_t *h, float factor)" .br .ti -1c .RI "void \fBwget_hashmap_set_growth_policy\fP (wget_hashmap_t *h, int off)" .br .in -1c .SH "Detailed Description" .PP Hashmaps are key/value stores that perform at O(1) for insertion, searching and removing\&. .SH "Function Documentation" .PP .SS "wget_hashmap_t* wget_hashmap_create (int max, wget_hashmap_hash_t hash, wget_hashmap_compare_t cmp)" .PP \fBParameters\fP .RS 4 \fImax\fP Initial number of pre-allocated entries .br \fIhash\fP Hash function to build hashes from elements .br \fIcmp\fP Comparison function used to find elements .RE .PP \fBReturns\fP .RS 4 New hashmap instance .RE .PP Create a new hashmap instance with initial size \fCmax\fP\&. It should be free'd after use with \fBwget_hashmap_free()\fP\&. .PP Before the first insertion of an element, \fChash\fP and \fCcmp\fP must be set\&. So if you use NULL values here, you have to call \fBwget_hashmap_setcmpfunc()\fP and/or wget_hashmap_hashcmpfunc() with appropriate function pointers\&. No doing so will result in undefined behavior (likely you'll see a segmentation fault)\&. .SS "int wget_hashmap_put_noalloc (wget_hashmap_t * h, const void * key, const void * value)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap to put data into .br \fIkey\fP Key to insert into \fCh\fP .br \fIvalue\fP Value to insert into \fCh\fP .RE .PP \fBReturns\fP .RS 4 0 if inserted a new entry, 1 if entry existed .RE .PP Insert a key/value pair into hashmap \fCh\fP\&. .PP \fCkey\fP and \fCvalue\fP are \fInot\fP cloned, the hashmap takes 'ownership' of both\&. .PP If \fCkey\fP already exists and the pointer values the old and the new key differ, the old key will be destroyed by calling the key destructor function (default is free())\&. .PP To realize a hashset (just keys without values), \fCvalue\fP may be NULL\&. .PP Neither \fCh\fP nor \fCkey\fP must be NULL\&. .SS "int wget_hashmap_put (wget_hashmap_t * h, const void * key, size_t keysize, const void * value, size_t valuesize)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap to put data into .br \fIkey\fP Key to insert into \fCh\fP .br \fIkeysize\fP Size of \fCkey\fP .br \fIvalue\fP Value to insert into \fCh\fP .br \fIvaluesize\fP Size of \fCvalue\fP .RE .PP \fBReturns\fP .RS 4 0 if inserted a new entry, 1 if entry existed .RE .PP Insert a key/value pair into hashmap \fCh\fP\&. .PP If \fCkey\fP already exists it will not be cloned\&. In this case the value destructor function will be called with the old value and the new value will be shallow cloned\&. .PP If \fCdoesn't\fP exist, both \fCkey\fP and \fCvalue\fP will be shallow cloned\&. .PP To realize a hashset (just keys without values), \fCvalue\fP may be NULL\&. .PP Neither \fCh\fP nor \fCkey\fP must be NULL\&. .SS "int wget_hashmap_get_null (const wget_hashmap_t * h, const void * key, void ** value)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIkey\fP Key to search for .br \fIvalue\fP Value to be returned .RE .PP \fBReturns\fP .RS 4 1 if \fCkey\fP has been found, 0 if not found .RE .PP Get the value for a given key\&. .PP If there are NULL values in the hashmap, you should use this function to distinguish between 'not found' and 'found NULL value'\&. .PP Neither \fCh\fP nor \fCkey\fP must be NULL\&. .SS "void* wget_hashmap_get (const wget_hashmap_t * h, const void * key)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIkey\fP Key to search for .RE .PP \fBReturns\fP .RS 4 Found value or NULL if not found .RE .PP Get the value for a given key\&. .PP If there are NULL values in the hashmap, you should use \fBwget_hashmap_get_null()\fP to distinguish between 'not found' and 'found NULL value'\&. .PP Neither \fCh\fP nor \fCkey\fP must be NULL\&. .SS "int wget_hashmap_contains (const wget_hashmap_t * h, const void * key)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIkey\fP Key to search for .RE .PP \fBReturns\fP .RS 4 1 if \fCkey\fP has been found, 0 if not found .RE .PP Check if \fCkey\fP exists in \fCh\fP\&. .SS "int wget_hashmap_remove (wget_hashmap_t * h, const void * key)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIkey\fP Key to be removed .RE .PP \fBReturns\fP .RS 4 1 if \fCkey\fP has been removed, 0 if not found .RE .PP Remove \fCkey\fP from hashmap \fCh\fP\&. .PP If \fCkey\fP is found, the key and value destructor functions are called when removing the entry from the hashmap\&. .SS "int wget_hashmap_remove_nofree (wget_hashmap_t * h, const void * key)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIkey\fP Key to be removed .RE .PP \fBReturns\fP .RS 4 1 if \fCkey\fP has been removed, 0 if not found .RE .PP Remove \fCkey\fP from hashmap \fCh\fP\&. .PP Key and value destructor functions are \fInot\fP called when removing the entry from the hashmap\&. .SS "void wget_hashmap_free (wget_hashmap_t ** h)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap to be free'd .RE .PP Remove all entries from hashmap \fCh\fP and free the hashmap instance\&. .PP Key and value destructor functions are called for each entry in the hashmap\&. .SS "void wget_hashmap_clear (wget_hashmap_t * h)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap to be cleared .RE .PP Remove all entries from hashmap \fCh\fP\&. .PP Key and value destructor functions are called for each entry in the hashmap\&. .SS "int wget_hashmap_size (const wget_hashmap_t * h)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .RE .PP \fBReturns\fP .RS 4 Number of entries in hashmap \fCh\fP .RE .PP Return the number of entries in the hashmap \fCh\fP\&. .SS "int wget_hashmap_browse (const wget_hashmap_t * h, wget_hashmap_browse_t browse, void * ctx)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIbrowse\fP Function to be called for each element of \fCh\fP .br \fIctx\fP Context variable use as param to \fCbrowse\fP .RE .PP \fBReturns\fP .RS 4 Return value of the last call to \fCbrowse\fP .RE .PP Call function \fCbrowse\fP for each element of hashmap \fCh\fP or until \fCbrowse\fP returns a value not equal to zero\&. .PP \fCbrowse\fP is called with \fCctx\fP and the pointer to the current element\&. .PP The return value of the last call to \fCbrowse\fP is returned or 0 if either \fCh\fP or \fCbrowse\fP is NULL\&. .SS "void wget_hashmap_setcmpfunc (wget_hashmap_t * h, wget_hashmap_compare_t cmp)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIcmp\fP Comparison function used to find keys .RE .PP Set the comparison function\&. .SS "void wget_hashmap_sethashfunc (wget_hashmap_t * h, wget_hashmap_hash_t hash)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIhash\fP Hash function used to hash keys .RE .PP Set the key hash function\&. .PP The keys of all entries in the hashmap will be hashed again\&. .SS "void wget_hashmap_set_key_destructor (wget_hashmap_t * h, wget_hashmap_key_destructor_t destructor)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIdestructor\fP Destructor function for keys .RE .PP Set the key destructor function\&. .PP Default is free()\&. .SS "void wget_hashmap_set_value_destructor (wget_hashmap_t * h, wget_hashmap_value_destructor_t destructor)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIdestructor\fP Destructor function for values .RE .PP Set the value destructor function\&. .PP Default is free()\&. .SS "void wget_hashmap_setloadfactor (wget_hashmap_t * h, float factor)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIfactor\fP The load factor .RE .PP Set the load factor function\&. .PP The load factor is determines when to resize the internal memory\&. 0\&.75 means 'resize if 75% or more of all slots are used'\&. .PP The resize strategy is set by \fBwget_hashmap_set_growth_policy()\fP\&. .PP The resize (and rehashing) occurs earliest on the next insertion of a new key\&. .PP Default is 0\&.75\&. .SS "void wget_hashmap_set_growth_policy (wget_hashmap_t * h, int off)" .PP \fBParameters\fP .RS 4 \fIh\fP Hashmap .br \fIoff\fP Hashmap growth mode: positive values: increase size by \fCoff\fP entries on each resize negative values: increase size by multiplying \fC-off\fP, e\&.g\&. -2 doubles the size on each resize .RE .PP Set the growth policy for internal memory\&. .PP Default is -2\&. .SH "Author" .PP Generated automatically by Doxygen for wget2 from the source code\&.