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