Loading...
Searching...
No Matches
Hash Tables
Apache Portability Runtime library
Collaboration diagram for Hash Tables:

## Macros

#define | APR_HASH_KEY_STRING (-1)

## Typedefs

typedef struct apr_hash_t | apr_hash_t
typedef struct apr_hash_index_t | apr_hash_index_t
typedef unsigned int(* | apr_hashfunc_t) (const char *key, apr_ssize_t *klen)
typedef int() | apr_hash_do_callback_fn_t(void *rec, const void *key, apr_ssize_t klen, const void *value)

## Functions

unsigned int | apr_hashfunc_default (const char *key, apr_ssize_t *klen)
apr_hash_t * | apr_hash_make (apr_pool_t *pool)
apr_hash_t * | apr_hash_make_custom (apr_pool_t *pool, apr_hashfunc_t hash_func)
apr_hash_t * | apr_hash_copy (apr_pool_t *pool, const apr_hash_t *h)
void | apr_hash_set (apr_hash_t *ht, const void *key, apr_ssize_t klen, const void *val)
void * | apr_hash_get (apr_hash_t *ht, const void *key, apr_ssize_t klen)
apr_hash_index_t * | apr_hash_first (apr_pool_t *p, apr_hash_t *ht)
apr_hash_index_t * | apr_hash_next (apr_hash_index_t *hi)
void | apr_hash_this (apr_hash_index_t *hi, const void **key, apr_ssize_t *klen, void **val)
const void * | apr_hash_this_key (apr_hash_index_t *hi)
apr_ssize_t | apr_hash_this_key_len (apr_hash_index_t *hi)
void * | apr_hash_this_val (apr_hash_index_t *hi)
unsigned int | apr_hash_count (apr_hash_t *ht)
void | apr_hash_clear (apr_hash_t *ht)
apr_hash_t * | apr_hash_overlay (apr_pool_t *p, const apr_hash_t *overlay, const apr_hash_t *base)
apr_hash_t * | apr_hash_merge (apr_pool_t *p, const apr_hash_t *h1, const apr_hash_t *h2, void *(*merger)(apr_pool_t *p, const void *key, apr_ssize_t klen, const void *h1_val, const void *h2_val, const void *data), const void *data)
int | apr_hash_do (apr_hash_do_callback_fn_t *comp, void *rec, const apr_hash_t *ht)
apr_pool_t * | apr_hash_pool_get (const apr_hash_t *thehash)

## Detailed Description

## Macro Definition Documentation

## APR_HASH_KEY_STRING

#define APR_HASH_KEY_STRING (-1)

When passing a key to apr_hash_set or apr_hash_get, this value can be passed to indicate a string-valued key, and have apr_hash compute the length automatically.

Remarks
  apr_hash will use strlen(key) for the length. The NUL terminator is not included in the hash value (why throw a constant in?). Since the hash table merely references the provided key (rather than copying it), apr_hash_this() will return the NUL-term'd key.

## Typedef Documentation

## apr_hash_do_callback_fn_t

typedef int() apr_hash_do_callback_fn_t(void *rec, const void *key, apr_ssize_t klen, const void *value)

Declaration prototype for the iterator callback function of apr_hash_do().

Parameters

  rec | The data passed as the first argument to apr_hash_[v]do()
  key | The key from this iteration of the hash table
  klen | The key length from this iteration of the hash table
  value | The value from this iteration of the hash table

Remarks
  Iteration continues while this callback function returns non-zero. To export the callback function for apr_hash_do() it must be declared in the _NONSTD convention.

## apr_hash_index_t

typedef struct apr_hash_index_t apr_hash_index_t

Abstract type for scanning hash tables.

## apr_hash_t

typedef struct apr_hash_t apr_hash_t

Abstract type for hash tables.

## apr_hashfunc_t

typedef unsigned int(* apr_hashfunc_t) (const char *key, apr_ssize_t *klen)

Callback functions for calculating hash values.

Parameters

  key | The key.
  klen | The length of the key, or APR_HASH_KEY_STRING to use the string length. If APR_HASH_KEY_STRING then returns the actual key length.

## Function Documentation

## apr_hash_clear()

void apr_hash_clear | ( | apr_hash_t * | ht | ) |

Clear any key/value pairs in the hash table.

Parameters

  ht | The hash table

## apr_hash_copy()

apr_hash_t * apr_hash_copy | ( | apr_pool_t * | pool,
|  | const apr_hash_t * | h
| ) |  |

Make a copy of a hash table

Parameters

  pool | The pool from which to allocate the new hash table
  h | The hash table to clone

Returns
  The hash table just created

Remarks
  Makes a shallow copy

## apr_hash_count()

unsigned int apr_hash_count | ( | apr_hash_t * | ht | ) |

Get the number of key/value pairs in the hash table.

Parameters

  ht | The hash table

Returns
  The number of key/value pairs in the hash table.

## apr_hash_do()

int apr_hash_do | ( | apr_hash_do_callback_fn_t * | comp,
|  | void * | rec,
|  | const apr_hash_t * | ht
| ) |  |

Iterate over a hash table running the provided function once for every element in the hash table. The `comp` function will be invoked for every element in the hash table.

Parameters

  comp | The function to run
  rec | The data to pass as the first argument to the function
  ht | The hash table to iterate over

Returns
  FALSE if one of the comp() iterations returned zero; TRUE if all iterations returned non-zero

See also
  apr_hash_do_callback_fn_t

## apr_hash_first()

apr_hash_index_t * apr_hash_first | ( | apr_pool_t * | p,
|  | apr_hash_t * | ht
| ) |  |

Start iterating over the entries in a hash table.

Parameters

  p | The pool to allocate the apr_hash_index_t iterator. If this pool is NULL, then an internal, non-thread-safe iterator is used.
  ht | The hash table

Returns
  The iteration state

Remarks
  There is no restriction on adding or deleting hash entries during an iteration (although the results may be unpredictable unless all you do is delete the current entry) and multiple iterations can be in progress at the same time.

Example:

int sum_values(apr_pool_t *p, apr_hash_t *ht)
{
apr_hash_index_t *hi;
void *val;
int sum = 0;
for (hi = apr_hash_first(p, ht); hi; hi = apr_hash_next(hi)) {
apr_hash_this(hi, NULL, NULL, &val);
sum += *(int *)val;
}
return sum;
}
apr_hash_index_t
struct apr_hash_index_t apr_hash_index_t
Definition apr_hash.h:57
apr_hash_first
apr_hash_index_t * apr_hash_first(apr_pool_t *p, apr_hash_t *ht)
apr_hash_next
apr_hash_index_t * apr_hash_next(apr_hash_index_t *hi)
apr_hash_t
struct apr_hash_t apr_hash_t
Definition apr_hash.h:52
apr_hash_this
void apr_hash_this(apr_hash_index_t *hi, const void **key, apr_ssize_t *klen, void **val)
apr_pool_t
struct apr_pool_t apr_pool_t
Definition apr_pools.h:60

## apr_hash_get()

void * apr_hash_get | ( | apr_hash_t * | ht,
|  | const void * | key,
|  | apr_ssize_t | klen
| ) |  |

Look up the value associated with a key in a hash table.

Parameters

  ht | The hash table
  key | Pointer to the key
  klen | Length of the key. Can be APR_HASH_KEY_STRING to use the string length.

Returns
  Returns NULL if the key is not present.

## apr_hash_make()

apr_hash_t * apr_hash_make | ( | apr_pool_t * | pool | ) |

Create a hash table.

Parameters

  pool | The pool to allocate the hash table out of

Returns
  The hash table just created

## apr_hash_make_custom()

apr_hash_t * apr_hash_make_custom | ( | apr_pool_t * | pool,
|  | apr_hashfunc_t | hash_func
| ) |  |

Create a hash table with a custom hash function

Parameters

  pool | The pool to allocate the hash table out of
  hash_func | A custom hash function.

Returns
  The hash table just created

## apr_hash_merge()

apr_hash_t * apr_hash_merge | ( | apr_pool_t * | p,
|  | const apr_hash_t * | h1,
|  | const apr_hash_t * | h2,
|  | void *(*)(apr_pool_t *p, const void *key, apr_ssize_t klen, const void *h1_val, const void *h2_val, const void *data) | merger,
|  | const void * | data
| ) |  |

Merge two hash tables into one new hash table. If the same key is present in both tables, call the supplied merge function to produce a merged value for the key in the new table. Both hash tables must use the same hash function.

Parameters

  p | The pool to use for the new hash table
  h1 | The first of the tables to merge
  h2 | The second of the tables to merge
  merger | A callback function to merge values, or NULL to make values from h1 override values from h2 (same semantics as apr_hash_overlay())
  data | Client data to pass to the merger function

Returns
  A new hash table containing all of the data from the two passed in

## apr_hash_next()

apr_hash_index_t * apr_hash_next | ( | apr_hash_index_t * | hi | ) |

Continue iterating over the entries in a hash table.

Parameters

  hi | The iteration state

Returns
  a pointer to the updated iteration state. NULL if there are no more
  entries.

## apr_hash_overlay()

apr_hash_t * apr_hash_overlay | ( | apr_pool_t * | p,
|  | const apr_hash_t * | overlay,
|  | const apr_hash_t * | base
| ) |  |

Merge two hash tables into one new hash table. The values of the overlay hash override the values of the base if both have the same key. Both hash tables must use the same hash function.

Parameters

  p | The pool to use for the new hash table
  overlay | The table to add to the initial table
  base | The table that represents the initial values of the new table

Returns
  A new hash table containing all of the data from the two passed in

## apr_hash_pool_get()

apr_pool_t * apr_hash_pool_get | ( | const apr_hash_t * | thehash | ) |

Get a pointer to the pool which the hash table was created in

## apr_hash_set()

void apr_hash_set | ( | apr_hash_t * | ht,
|  | const void * | key,
|  | apr_ssize_t | klen,
|  | const void * | val
| ) |  |

Associate a value with a key in a hash table.

Parameters

  ht | The hash table
  key | Pointer to the key
  klen | Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
  val | Value to associate with the key

Remarks
  If the value is NULL the hash entry is deleted. The key is stored as is, and so must have a lifetime at least as long as the hash table's pool.

## apr_hash_this()

void apr_hash_this | ( | apr_hash_index_t * | hi,
|  | const void ** | key,
|  | apr_ssize_t * | klen,
|  | void ** | val
| ) |  |

Get the current entry's details from the iteration state.

Parameters

  hi | The iteration state
  key | Return pointer for the pointer to the key.
  klen | Return pointer for the key length.
  val | Return pointer for the associated value.

Remarks
  The return pointers should point to a variable that will be set to the corresponding data, or they may be NULL if the data isn't interesting.

## apr_hash_this_key()

const void * apr_hash_this_key | ( | apr_hash_index_t * | hi | ) |

Get the current entry's key from the iteration state.

Parameters

  hi | The iteration state

Returns
  The pointer to the key

## apr_hash_this_key_len()

apr_ssize_t apr_hash_this_key_len | ( | apr_hash_index_t * | hi | ) |

Get the current entry's key length from the iteration state.

Parameters

  hi | The iteration state

Returns
  The key length

## apr_hash_this_val()

void * apr_hash_this_val | ( | apr_hash_index_t * | hi | ) |

Get the current entry's value from the iteration state.

Parameters

  hi | The iteration state

Returns
  The pointer to the value

## apr_hashfunc_default()

unsigned int apr_hashfunc_default | ( | const char * | key,
|  | apr_ssize_t * | klen
| ) |  |

The default hash function.