Hash tables

Detailed Description

OCILIB uses hash tables internally for index/name columns mapping.

OCILIB makes public its hash table’s implementation public for general purpose uses.

OCI_HashTable objects manage string keys / values that can be :

• integers
• strings
• pointers

This hash table implementation :

• handle collisions
• allows multiple values per key

Internal conception

• The hash table is composed of an array of slots.
• Each slot can hold a linked list of entries (one per key)
• Each entry can hold a linked list of values

Note

• The internal hash function computes the index in the array where the entry has to be inserted/looked up.

Collisions are handled by chaining method.

#include "ocilib.h"

/* requires script demo/products.sql */

void err_handler(OCI_Error *err)
{
    printf("%s\n", OCI_ErrorGetString(err));
}

int main(void)
{
    int i, n;
    OCI_Connection *cn;
    OCI_Statement  *st;
    OCI_Resultset  *rs;
    OCI_HashTable  *ht;
    OCI_HashEntry  *he;
    OCI_HashValue  *hv;

    if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
    {
        return EXIT_FAILURE;
    }

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);
    ht = OCI_HashCreate(256, OCI_HASH_INTEGER);

    /* fill the hash table with data from DB */

    OCI_ExecuteStmt(st, "select code, name from products");

    rs = OCI_GetResultset(st);
    while (OCI_FetchNext(rs))
    {
        OCI_HashAddInt(ht, OCI_GetString2(rs, "name"), OCI_GetInt2(rs, "code"));
    }

    printf("%d row(s) fetched\n", OCI_GetRowCount(rs));

    /* lookup an entry */

    printf("code for '%s' is : %d\n", "product 1", OCI_HashGetInt(ht, "product 1"));

    /* browse the hash table */

    n = OCI_HashGetSize(ht);

    for (i = 0; i < n; i++)
    {
        he = OCI_HashGetEntry(ht, i);

        while (he)
        {
            printf(">key: '%s'\n", he->key);

            hv = he->values;

            while (hv)
            {
                printf("..... value : '%i'\n", hv->value.num);
                hv = hv->next;
            }

            he = he->next;
        }
    }

    /* destroy table */

    OCI_HashFree(ht);
    OCI_StatementFree(st);
    OCI_ConnectionFree(cn);
    OCI_Cleanup();

    return EXIT_SUCCESS;
}

Functions
OCI_EXPORT OCI_HashTable *OCI_API	OCI_HashCreate (unsigned int size, unsigned int type)
	Create a hash table. More...
OCI_EXPORT boolean OCI_API	OCI_HashFree (OCI_HashTable *table)
	Destroy a hash table. More...
OCI_EXPORT unsigned int OCI_API	OCI_HashGetSize (OCI_HashTable *table)
	Return the size of the hash table. More...
OCI_EXPORT unsigned int OCI_API	OCI_HashGetType (OCI_HashTable *table)
	Return the type of the hash table. More...
OCI_EXPORT boolean OCI_API	OCI_HashAddString (OCI_HashTable *table, const otext *key, const otext *value)
	Add a pair string key / string value to the hash table. More...
OCI_EXPORT const otext *OCI_API	OCI_HashGetString (OCI_HashTable *table, const otext *key)
	Return the string value associated to the given key. More...
OCI_EXPORT boolean OCI_API	OCI_HashAddInt (OCI_HashTable *table, const otext *key, int value)
	Adds a pair string key / integer value to the hash table. More...
OCI_EXPORT int OCI_API	OCI_HashGetInt (OCI_HashTable *table, const otext *key)
	Return the integer value associated to the given key. More...
OCI_EXPORT boolean OCI_API	OCI_HashAddPointer (OCI_HashTable *table, const otext *key, void *value)
	Adds a pair string key / pointer value to the hash table. More...
OCI_EXPORT void *OCI_API	OCI_HashGetPointer (OCI_HashTable *table, const otext *key)
	Return a pointer associated with the given key. More...
OCI_EXPORT OCI_HashEntry *OCI_API	OCI_HashLookup (OCI_HashTable *table, const otext *key, boolean create)
	Lookup for an entry matching the key in the table. More...
OCI_EXPORT OCI_HashValue *OCI_API	OCI_HashGetValue (OCI_HashTable *table, const otext *key)
	Return the first hash slot that matches the key. More...
OCI_EXPORT OCI_HashEntry *OCI_API	OCI_HashGetEntry (OCI_HashTable *table, unsigned int index)
	Return the entry slot of the hash table internal list at the given position. More...

Function Documentation

OCI_HashCreate()

OCI_EXPORT OCI_HashTable* OCI_API OCI_HashCreate	(	unsigned int	size,
		unsigned int	type
	)

#include <ocilib.h>

Create a hash table.

Parameters

size	- size of the hash table
type	- type of the hash table

Note

Parameter can be one of the following values :

• OCI_HASH_STRING : string values
• OCI_HASH_INTEGER : integer values
• OCI_HASH_POINTER : pointer values

Returns

Hash handle on success or NULL on failure

OCI_HashFree()

OCI_EXPORT boolean OCI_API OCI_HashFree

(

OCI_HashTable *

table

)

#include <ocilib.h>

Destroy a hash table.

Parameters

table

- Table handle

Returns

TRUE on success otherwise FALSE

OCI_HashGetSize()

OCI_EXPORT unsigned int OCI_API OCI_HashGetSize

(

OCI_HashTable *

table

)

#include <ocilib.h>

Return the size of the hash table.

Parameters

table

- Table handle

OCI_HashGetType()

OCI_EXPORT unsigned int OCI_API OCI_HashGetType

(

OCI_HashTable *

table

)

#include <ocilib.h>

Return the type of the hash table.

Parameters

table

- Table handle

Note

the return value can be one of the following values :

• OCI_HASH_STRING : string values
• OCI_HASH_INTEGER : integer values
• OCI_HASH_POINTER : pointer values

Returns

Hash table data type or OCI_UNKNOWN the input handle is NULL

OCI_HashAddString()

OCI_EXPORT boolean OCI_API OCI_HashAddString	(	OCI_HashTable *	table,
		const otext *	key,
		const otext *	value
	)

#include <ocilib.h>

Add a pair string key / string value to the hash table.

Parameters

table	- Table handle
key	- String key
value	- string value

Returns

TRUE on success otherwise FALSE

OCI_HashGetString()

OCI_EXPORT const otext* OCI_API OCI_HashGetString	(	OCI_HashTable *	table,
		const otext *	key
	)

#include <ocilib.h>

Return the string value associated to the given key.

Parameters

table	- Table handle
key	- String key

Returns

Stored string associated with the key otherwise NULL

OCI_HashAddInt()

OCI_EXPORT boolean OCI_API OCI_HashAddInt	(	OCI_HashTable *	table,
		const otext *	key,
		int	value
	)

#include <ocilib.h>

Adds a pair string key / integer value to the hash table.

Parameters

table	- Table handle
key	- String key
value	- Integer value

Returns

TRUE on success otherwise FALSE

OCI_HashGetInt()

OCI_EXPORT int OCI_API OCI_HashGetInt	(	OCI_HashTable *	table,
		const otext *	key
	)

#include <ocilib.h>

Return the integer value associated to the given key.

Parameters

table	- Table handle
key	- String key

Returns

Stored integer associated with the key otherwise 0

OCI_HashAddPointer()

OCI_EXPORT boolean OCI_API OCI_HashAddPointer	(	OCI_HashTable *	table,
		const otext *	key,
		void *	value
	)

#include <ocilib.h>

Adds a pair string key / pointer value to the hash table.

Parameters

table	- Table handle
key	- String key
value	- Pointer value

Returns

TRUE on success otherwise FALSE

OCI_HashGetPointer()

OCI_EXPORT void* OCI_API OCI_HashGetPointer	(	OCI_HashTable *	table,
		const otext *	key
	)

#include <ocilib.h>

Return a pointer associated with the given key.

Parameters

table	- Table handle
key	- String key

Returns

Stored pointer associated with the key otherwise NULL

OCI_HashLookup()

OCI_EXPORT OCI_HashEntry* OCI_API OCI_HashLookup	(	OCI_HashTable *	table,
		const otext *	key,
		boolean	create
	)

#include <ocilib.h>

Lookup for an entry matching the key in the table.

Parameters

table	- Table handle
key	- String key
create	- Do create the entry if not exists

Returns

Entry handle if key found/added otherwise NULL

OCI_HashGetValue()

OCI_EXPORT OCI_HashValue* OCI_API OCI_HashGetValue	(	OCI_HashTable *	table,
		const otext *	key
	)

#include <ocilib.h>

Return the first hash slot that matches the key.

Parameters

table	- Table handle
key	- String key

Returns

Slot handle if key found otherwise NULL

OCI_HashGetEntry()

OCI_EXPORT OCI_HashEntry* OCI_API OCI_HashGetEntry	(	OCI_HashTable *	table,
		unsigned int	index
	)

#include <ocilib.h>

Return the entry slot of the hash table internal list at the given position.

Parameters

table	- Table handle
index	- index

Warning

Index start at at

Returns

Slot handle otherwise NULL