The qDecoder Project: C/C++ Library

- Main Page
- Data Structures
- Files

- File List
- Globals

# qHasharr.c File Reference

Array based Hash-table Data Structure API. More...

## Functions
size_t | qHasharrSize (int max)
| Get how much memory is needed for N entries.
int | qHasharrInit (Q_HASHARR *tbl, size_t memsize)
| Initialize array-hash table.
bool | qHasharrClear (Q_HASHARR *tbl)
| Reset array-hash table.
bool | qHasharrPut (Q_HASHARR *tbl, const char *key, const void *value, int size)
| Put object into hash table.
bool | qHasharrPutStr (Q_HASHARR *tbl, const char *key, const char *value)
| Put string into hash table.
bool | qHasharrPutInt (Q_HASHARR *tbl, const char *key, int value)
| Put integer into hash table.
void * | qHasharrGet (Q_HASHARR *tbl, const char *key, int *size)
| Get object from hash table.
char * | qHasharrGetStr (Q_HASHARR *tbl, const char *key)
| Get string from hash table.
int | qHasharrGetInt (Q_HASHARR *tbl, const char *key)
| Get integer from hash table.
const char * | qHasharrGetFirstKey (Q_HASHARR *tbl, int *idx)
| Get first key name.
const char * | qHasharrGetNextKey (Q_HASHARR *tbl, int *idx)
| Get next key name.
bool | qHasharrRemove (Q_HASHARR *tbl, const char *key)
| Remove key from hash table.
bool | qHasharrPrint (Q_HASHARR *tbl, FILE *out)
| Print hash table for debugging purpose.
bool | qHasharrStatus (Q_HASHARR *tbl, int *used, int *max)
| Get hash table internal status.

## Detailed Description

Array based Hash-table Data Structure API.

Note:
  In this array hash-table, we use some technics to effectively use memory. To verify key we use two way, if the key is smaller than (_Q_HASHARR_MAX_KEYSIZE - 1), we compare key itself. But if the key is bigger than (_Q_HASHARR_MAX_KEYSIZE - 1), we compare md5 of key and key length. If the key length and md5 of key are same we consider it's same key. So we don't need to store full key string. Actually it's not necessary to keep original key string, but we keep this because of two reasons. 1) if the length of the key is smaller than 16, it will be little bit quicker to compare key. 2) debugging reason.

Basically this hash-table based on array defines small size slot then it can links several slot for one data. This mechanism can save some wastes of memory. You can adjust default slot size to modify _Q_HASHARR_DEF_VALUESIZE.

       int maxkeys = 1000;

       // calculate how many memory do we need
       size_t memsize = qHasharrSize(maxkeys * 2); // generally allocate double size of max to decrease hash collision

       // allocate memory
       Q_HASHARR *hasharr = (Q_HASHARR *)malloc(memsize);

       // initialize hash-table
       if(qHasharrInit(hasharr, memsize) == 0) return -1;

       // put some sample data
       if(qHasharrPut(hasharr, "sample1", "binary", 6) == false) return -1; // hash-table full
       if(qHasharrPutStr(hasharr, "sample2", "string") == false) return -1; // hash-table full
       if(qHasharrPutInt(hasharr, "sample3", 3) == false) return -1; // hash-table full

       // fetch data
       int size;
       char *sample_bin = qHasharrGet(hasharr, "sample1", &size);
       char *sample_str = qHasharrGetStr(hasharr, "sample2");
       int  sample_int  = qHasharrGetInt(hasharr, "sample3");

Another simple way to initialize hash-table.

       // define data memory as much as you needed.
       char datamem[10 * 1024];

       // just set the Q_HASHARR points to data memory.
       Q_HASHARR *hasharr = (Q_HASHARR *)datamem;

       // initialize hash-table.
       if(qHasharrInit(hasharr, sizeof(datamem)) == 0) return -1;

       (...your codes here...)

       // no need to free unless you use malloc()

You can create hash table on shared memory like below.

       int maxkeys = 1000;
       int memsize = qHasharrSize(maxkeys * 2);

       // create shared memory
       int shmid = qShmInit(g_conf.szEgisdavdPidfile, 's', memsize, true);
       if(shmid < 0) return -1; // creation failed
       Q_HASHARR *hasharr = (Q_HASHARR *)qShmGet(shmid);

       // initialize hash-table
       if(qHasharrInit(hasharr, memsize) == 0) return -1;

       (...your codes here...)

       // destroy shared memory
       qShmFree(shmid);

## Function Documentation

size_t qHasharrSize | ( | int | max | ) |

Get how much memory is needed for N entries.

Parameters:

  | max | a number of maximum internal slots

Returns:
  memory size needed

Note:
  This is useful when you decide how much memory(shared-memory) required for N object entries. Be sure, a single object can be stored in several slots. So you need to consider additional slots if some data is bigger than _Q_HASHARR_DEF_VALUESIZE. By default, _Q_HASHARR_DEF_VALUESIZE is 32. This means if the size of object is bigger than 32 bytes it will use another slot.

int qHasharrInit | ( | Q_HASHARR * | tbl,
|  | size_t | memsize |
| ) |  |  |

Initialize array-hash table.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | memsize | actual size of Q_HASHARR

Returns:
  maximum number of available slots if successful, otherwise returns 0

       // allocate memory
       size_t memsize = qHasharrSize(100);
       Q_HASHARR *hasharr = (Q_HASHARR *)malloc(memsize);

       // initialize hash-table
       if(qHasharrInit(hasharr, memsize) == 0) return -1;

bool qHasharrClear | ( | Q_HASHARR * | tbl | ) |

Reset array-hash table.

Parameters:

  | tbl | a pointer of Q_HASHARR

Returns:
  true if successful, otherwise returns false

Note:
  You do not need to call this, after qHasharrInit(). This is useful when you reset all of data in the hash table.

bool qHasharrPut | ( | Q_HASHARR * | tbl,
|  | const char * | key,
|  | const void * | value,
|  | int | size |
| ) |  |  |

Put object into hash table.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | key | key string
  | value | value object data
  | size | size of value

Returns:
  true if successful, otherwise returns false

bool qHasharrPutStr | ( | Q_HASHARR * | tbl,
|  | const char * | key,
|  | const char * | value |
| ) |  |  |

Put string into hash table.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | key | key string
  | value | value string

Returns:
  true if successful, otherwise returns false

bool qHasharrPutInt | ( | Q_HASHARR * | tbl,
|  | const char * | key,
|  | int | value |
| ) |  |  |

Put integer into hash table.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | key | key string
  | value | value integer

Returns:
  true if successful, otherwise returns false

void* qHasharrGet | ( | Q_HASHARR * | tbl,
|  | const char * | key,
|  | int * | size |
| ) |  |  |

Get object from hash table.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | key | key string
  | size | if not NULL, oject size will be stored

Returns:
  malloced object pointer if successful, otherwise(not found) returns NULL

Note:
  returned object must be freed after done using.

char* qHasharrGetStr | ( | Q_HASHARR * | tbl,
|  | const char * | key |
| ) |  |  |

Get string from hash table.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | key | key string

Returns:
  string pointer if successful, otherwise(not found) returns NULL

Note:
  returned object must be freed after done using.

int qHasharrGetInt | ( | Q_HASHARR * | tbl,
|  | const char * | key |
| ) |  |  |

Get integer from hash table.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | key | key string

Returns:
  value integer if successful, otherwise(not found) returns 0

const char* qHasharrGetFirstKey | ( | Q_HASHARR * | tbl,
|  | int * | idx |
| ) |  |  |

Get first key name.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | idx | index pointer

Returns:
  key name string if successful, otherwise returns NULL

Note:
  Do not free returned key string.

       char *key;
       int idx;
       for(key = qHasharrGetFirstKey(tbl, &idx); key != NULL; key = qHasharrGetNextKey(tbl, &idx) {
         char *value = qHasharrGetStr(tbl, key);
         if(value != NULL) free(value);
       }

const char* qHasharrGetNextKey | ( | Q_HASHARR * | tbl,
|  | int * | idx |
| ) |  |  |

Get next key name.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | idx | index pointer

Returns:
  key name string if successful, otherwise(end of table) returns NULL

Note:
  Do not free returned key string.

bool qHasharrRemove | ( | Q_HASHARR * | tbl,
|  | const char * | key |
| ) |  |  |

Remove key from hash table.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | key | key string

Returns:
  true if successful, otherwise(not found) returns false

bool qHasharrPrint | ( | Q_HASHARR * | tbl,
|  | FILE * | out |
| ) |  |  |

Print hash table for debugging purpose.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | out | output stream

Returns:
  true if successful, otherwise returns false

bool qHasharrStatus | ( | Q_HASHARR * | tbl,
|  | int * | used,
|  | int * | max |
| ) |  |  |

Get hash table internal status.

Parameters:

  | tbl | a pointer of Q_HASHARR
  | used | if not NULL, a number of used slots(not a number of key) will be stored
  | max | if not NULL, the maximum number of slots will be stored

Returns:
  true if successful, otherwise returns false

Note:
  It is different from dynamic hash-table. In array-hash table, a value object can be stored in several slots if the size of the object is bigger than the size of slot. So used and max slot number is not equal to actual stored and maximum storable objects number.

[Home] [About] [Examples] [Changes] [Download] [SVN Repository] [Install] [Reference]