cctools
itable.h File Reference

An integer-indexed hash table. More...

#include "int_sizes.h"

Go to the source code of this file.

Macros

#define ITABLE_ITERATE(table, key, value)
 Utility macro to simplify common case of iterating over an itable.
 

Functions

struct itable * itable_create (int buckets)
 Create a new integer table.
 
void itable_clear (struct itable *h, void(*delete_func)(void *))
 Remove all entries from an integer table.
 
void itable_delete (struct itable *h)
 Delete an integer table.
 
int itable_size (struct itable *h)
 Count the entries in an integer table.
 
int itable_insert (struct itable *h, UINT64_T key, const void *value)
 Insert a key and value.
 
void * itable_lookup (struct itable *h, UINT64_T key)
 Look up a value by key.
 
void * itable_remove (struct itable *h, UINT64_T key)
 Remove a value by key.
 
void * itable_pop (struct itable *h)
 Remove any one value.
 
void itable_firstkey (struct itable *h)
 Begin iteration over all keys.
 
int itable_nextkey (struct itable *h, UINT64_T *key, void **value)
 Continue iteration over all keys.
 

Detailed Description

An integer-indexed hash table.

This hash table module maps integers to arbitrary objects (void pointers). For example, to store a filename using the file descriptor as a key:

struct itable *t;
t = itable_create(0);

fd = open(pathname,O_RDONLY,0);

itable_insert(t,fd,pathname);
pathname = itable_remove(h,id);

To list all of the items in an itable, use itable_firstkey and itable_nextkey like this:

UINT64_T  key;
void *value;

itable_firstkey(h);
while(itable_nextkey(h,&key,&value)) {
        printf("table contains: %d\n",key);
}

Alternatively:

UINT64_T  key;
void *value;

ITABLE_ITERATE(h,key,value) {
        printf("table contains: %d\n",key);
}

Macro Definition Documentation

◆ ITABLE_ITERATE

#define ITABLE_ITERATE ( table,
key,
value )
Value:
itable_firstkey(table); while(itable_nextkey(table,&key,(void**)&value))
int itable_nextkey(struct itable *h, UINT64_T *key, void **value)
Continue iteration over all keys.
void itable_firstkey(struct itable *h)
Begin iteration over all keys.

Utility macro to simplify common case of iterating over an itable.

Use as follows:

UINT64_T key;
void *value;

ITABLE_ITERATE(table,key,value) {
        printf("table contains: %lld\n",key);
}

Function Documentation

◆ itable_create()

struct itable * itable_create ( int buckets)

Create a new integer table.

Parameters
bucketsThe number of buckets in the table. If zero, a default value will be used.
Returns
A pointer to a new integer table.

◆ itable_clear()

void itable_clear ( struct itable * h,
void(* delete_func )(void *) )

Remove all entries from an integer table.

Parameters
hThe integer table to delete.
delete_funcIf non-null, will be invoked on each object to delete it.

◆ itable_delete()

void itable_delete ( struct itable * h)

Delete an integer table.

Note that this function will not delete all of the objects contained within the integer table.

Parameters
hThe integer table to delete.

◆ itable_size()

int itable_size ( struct itable * h)

Count the entries in an integer table.

Returns
The number of entries in the table.
Parameters
hA pointer to an integer table.

◆ itable_insert()

int itable_insert ( struct itable * h,
UINT64_T key,
const void * value )

Insert a key and value.

This call will fail if the table already contains the same key. You must call itable_remove to remove it. Also note that you cannot insert a null value into the table.

Parameters
hA pointer to an integer table.
keyAn integer key
valueA pointer to store with the key.
Returns
One if the insert succeeded, failure otherwise

◆ itable_lookup()

void * itable_lookup ( struct itable * h,
UINT64_T key )

Look up a value by key.

Parameters
hA pointer to an integer table.
keyAn integer key to search for.
Returns
If found, the pointer associated with the key, otherwise null.

◆ itable_remove()

void * itable_remove ( struct itable * h,
UINT64_T key )

Remove a value by key.

Parameters
hA pointer to an integer table.
keyAn integer key to remove.
Returns
If found, the pointer associated with the key, otherwise null.

◆ itable_pop()

void * itable_pop ( struct itable * h)

Remove any one value.

Parameters
hA pointer to an integer table.
Returns
One object removed from the table.

◆ itable_firstkey()

void itable_firstkey ( struct itable * h)

Begin iteration over all keys.

This function begins a new iteration over an integer table, allowing you to visit every key and value in the table. Next, invoke itable_nextkey to retrieve each value in order.

Parameters
hA pointer to an integer table.

◆ itable_nextkey()

int itable_nextkey ( struct itable * h,
UINT64_T * key,
void ** value )

Continue iteration over all keys.

This function returns the next key and value in the iteration.

Parameters
hA pointer to an integer table.
keyA pointer to a key integer.
valueA pointer to a value pointer. (can be NULL)
Returns
Zero if there are no more elements to visit, one otherwise.