wget2: Hashmap functions

| wget2 2.0.0

- Main Page
- Modules
- Data Structures
- Files

Functions
Hashmap functions

## Functions
wget_hashmap_iterator * | wget_hashmap_iterator_alloc (wget_hashmap *h)
void | wget_hashmap_iterator_free (wget_hashmap_iterator **iter)
void * | wget_hashmap_iterator_next (wget_hashmap_iterator *iter, void **value)
wget_hashmap * | wget_hashmap_create (int max, wget_hashmap_hash_fn *hash, wget_hashmap_compare_fn *cmp)
int | wget_hashmap_put (wget_hashmap *h, const void *key, const void *value)
int | wget_hashmap_contains (const wget_hashmap *h, const void *key)
int | wget_hashmap_get (const wget_hashmap *h, const void *key, void **value)
int | wget_hashmap_remove (wget_hashmap *h, const void *key)
int | wget_hashmap_remove_nofree (wget_hashmap *h, const void *key)
void | wget_hashmap_free (wget_hashmap **h)
void | wget_hashmap_clear (wget_hashmap *h)
int | wget_hashmap_size (const wget_hashmap *h)
int | wget_hashmap_browse (const wget_hashmap *h, wget_hashmap_browse_fn *browse, void *ctx)
void | wget_hashmap_setcmpfunc (wget_hashmap *h, wget_hashmap_compare_fn *cmp)
int | wget_hashmap_sethashfunc (wget_hashmap *h, wget_hashmap_hash_fn *hash)
void | wget_hashmap_set_key_destructor (wget_hashmap *h, wget_hashmap_key_destructor *destructor)
void | wget_hashmap_set_value_destructor (wget_hashmap *h, wget_hashmap_value_destructor *destructor)
void | wget_hashmap_set_load_factor (wget_hashmap *h, float factor)
void | wget_hashmap_set_resize_factor (wget_hashmap *h, float factor)
typedef struct wget_hashmap_st | wget_hashmap
| Type of the hashmap.
typedef int | wget_hashmap_compare_fn(const void *key1, const void *key2)
| Type of the hashmap compare function.
typedef unsigned int | wget_hashmap_hash_fn(const void *key)
| Type of the hashmap hash function.
typedef int | wget_hashmap_browse_fn(void *ctx, const void *key, void *value)
| Type of the hashmap browse callback function.
typedef void | wget_hashmap_key_destructor(void *key)
| Type of the hashmap key destructor function.
typedef void | wget_hashmap_value_destructor(void *value)
| Type of the hashmap value destructor function.

## Detailed Description

Hashmaps are key/value stores that perform at O(1) for insertion, searching and removing.

## Function Documentation

## ◆ wget_hashmap_iterator_alloc()

wget_hashmap_iterator* wget_hashmap_iterator_alloc | ( | wget_hashmap * | h | ) |

Parameters

  [in] | h | Hashmap

Returns
  New iterator instance for `h`

Creates a hashmap iterator for `h`.

## ◆ wget_hashmap_iterator_free()

void wget_hashmap_iterator_free | ( | wget_hashmap_iterator ** | iter | ) |

Parameters

  [in] | iter | Hashmap iterator

Free the given iterator `iter`.

## ◆ wget_hashmap_iterator_next()

void* wget_hashmap_iterator_next | ( | wget_hashmap_iterator * | iter,
|  | void ** | value
| ) |  |

Parameters

  [in] | iter | Hashmap iterator
  [out] | value | Pointer to the value belonging to the returned key

Returns
  Pointer to the key or NULL if no more elements left

Returns the next key / value in the hashmap. If all key/value pairs have been iterated over the function returns NULL and `value` is untouched.

When iterating over a hashmap, the order of returned key/value pairs is not defined.

## ◆ wget_hashmap_create()

wget_hashmap* wget_hashmap_create | ( | int | max,
|  | wget_hashmap_hash_fn * | hash,
|  | wget_hashmap_compare_fn * | cmp
| ) |  |

Parameters

  [in] | max | Initial number of pre-allocated entries
  [in] | hash | Hash function to build hashes from elements
  [in] | cmp | Comparison function used to find elements

Returns
  New hashmap instance

Create a new hashmap instance with initial size `max`. It should be free'd after use with wget_hashmap_free().

Before the first insertion of an element, `hash` and `cmp` must be set. So if you use NULL values here, you have to call wget_hashmap_setcmpfunc() and/or wget_hashmap_hashcmpfunc() with appropriate function pointers. No doing so will result in undefined behavior (likely you'll see a segmentation fault).

## ◆ wget_hashmap_put()

int wget_hashmap_put | ( | wget_hashmap * | h,
|  | const void * | key,
|  | const void * | value
| ) |  |

Parameters

  [in] | h | Hashmap to put data into
  [in] | key | Key to insert into `h`
  [in] | value | Value to insert into `h`

Returns
  0 if inserted a new entry, 1 if entry existed, WGET_E_MEMORY if internal allocation failed

Insert a key/value pair into hashmap `h`.

`key` and `value` are not cloned, the hashmap takes 'ownership' of both.

If `key` 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()).

To realize a hashset (just keys without values), `value` may be NULL.

Neither `h` nor `key` must be NULL, else the return value will always be 0.

## ◆ wget_hashmap_contains()

int wget_hashmap_contains | ( | const wget_hashmap * | h,
|  | const void * | key
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | key | Key to search for

Returns
  1 if `key` has been found, 0 if not found

Check if `key` exists in `h`.

## ◆ wget_hashmap_get()

int wget_hashmap_get | ( | const wget_hashmap * | h,
|  | const void * | key,
|  | void ** | value
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | key | Key to search for
  [out] | value | Value to be returned

Returns
  1 if `key` has been found, 0 if not found

Get the value for a given key.

Neither `h` nor `key` must be NULL.

## ◆ wget_hashmap_remove()

int wget_hashmap_remove | ( | wget_hashmap * | h,
|  | const void * | key
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | key | Key to be removed

Returns
  1 if `key` has been removed, 0 if not found

Remove `key` from hashmap `h`.

If `key` is found, the key and value destructor functions are called when removing the entry from the hashmap.

## ◆ wget_hashmap_remove_nofree()

int wget_hashmap_remove_nofree | ( | wget_hashmap * | h,
|  | const void * | key
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | key | Key to be removed

Returns
  1 if `key` has been removed, 0 if not found

Remove `key` from hashmap `h`.

Key and value destructor functions are not called when removing the entry from the hashmap.

## ◆ wget_hashmap_free()

void wget_hashmap_free | ( | wget_hashmap ** | h | ) |

Parameters

  [in] | h | Hashmap to be free'd

Remove all entries from hashmap `h` and free the hashmap instance.

Key and value destructor functions are called for each entry in the hashmap.

## ◆ wget_hashmap_clear()

void wget_hashmap_clear | ( | wget_hashmap * | h | ) |

Parameters

  [in] | h | Hashmap to be cleared

Remove all entries from hashmap `h`.

Key and value destructor functions are called for each entry in the hashmap.

## ◆ wget_hashmap_size()

int wget_hashmap_size | ( | const wget_hashmap * | h | ) |

Parameters

  [in] | h | Hashmap

Returns
  Number of entries in hashmap `h`

Return the number of entries in the hashmap `h`.

## ◆ wget_hashmap_browse()

int wget_hashmap_browse | ( | const wget_hashmap * | h,
|  | wget_hashmap_browse_fn * | browse,
|  | void * | ctx
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | browse | Function to be called for each element of `h`
  [in] | ctx | Context variable use as param to `browse`

Returns
  Return value of the last call to `browse`

Call function `browse` for each element of hashmap `h` or until `browse` returns a value not equal to zero.

`browse` is called with `ctx` and the pointer to the current element.

The return value of the last call to `browse` is returned or 0 if either `h` or `browse` is NULL.

## ◆ wget_hashmap_setcmpfunc()

void wget_hashmap_setcmpfunc | ( | wget_hashmap * | h,
|  | wget_hashmap_compare_fn * | cmp
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | cmp | Comparison function used to find keys

Set the comparison function.

## ◆ wget_hashmap_sethashfunc()

int wget_hashmap_sethashfunc | ( | wget_hashmap * | h,
|  | wget_hashmap_hash_fn * | hash
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | hash | Hash function used to hash keys

Returns
  WGET_E_SUCCESS if set successfully, else WGET_E_MEMORY or WGET_E_INVALID

Set the key hash function.

The keys of all entries in the hashmap will be hashed again. This includes a memory allocation, so there is a possibility of failure.

## ◆ wget_hashmap_set_key_destructor()

void wget_hashmap_set_key_destructor | ( | wget_hashmap * | h,
|  | wget_hashmap_key_destructor * | destructor
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | destructor | Destructor function for keys

Set the key destructor function.

Default is free().

## ◆ wget_hashmap_set_value_destructor()

void wget_hashmap_set_value_destructor | ( | wget_hashmap * | h,
|  | wget_hashmap_value_destructor * | destructor
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | destructor | Destructor function for values

Set the value destructor function.

Default is free().

## ◆ wget_hashmap_set_load_factor()

void wget_hashmap_set_load_factor | ( | wget_hashmap * | h,
|  | float | factor
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | factor | The load factor

Set the load factor function.

The load factor is determines when to resize the internal memory. 0.75 means "resize if 75% or more of all slots are used".

The resize strategy is set by wget_hashmap_set_growth_policy().

The resize (and rehashing) occurs earliest on the next insertion of a new key.

Default is 0.75.

## ◆ wget_hashmap_set_resize_factor()

void wget_hashmap_set_resize_factor | ( | wget_hashmap * | h,
|  | float | factor
| ) |  |

Parameters

  [in] | h | Hashmap
  [in] | factor | Hashmap growth factor

Set the factor for resizing the hashmap when it's load factor is reached.

The new size is 'factor * oldsize'. If the new size is less or equal 0, the involved put function will do nothing and the internal state of the hashmap will not change.

Default is 2.