SolarCapture C Bindings User Guide  SF-115721-CD
Draft 2A
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
hash_table.h File Reference

A hash table with open addressing and double hashing. More...

Functions

int sc_hash_table_alloc (struct sc_hash_table **table_out, unsigned key_size, unsigned val_size, unsigned capacity)
 Allocate an sc_hash_table. More...
 
void sc_hash_table_free (struct sc_hash_table *table)
 Free an sc_hash_table. More...
 
int sc_hash_table_grow (struct sc_hash_table *table, size_t max_size)
 Increase the capacity of a hash table. More...
 
int sc_hash_table_get (struct sc_hash_table *table, const void *key, bool insert_if_not_found, void **val_out)
 Lookup or insert an entry in a hash table. More...
 
int sc_hash_table_del (struct sc_hash_table *table, const void *key)
 Remove an entry from an sc_hash_table by key. More...
 
int sc_hash_table_del_val (struct sc_hash_table *table, const void *val)
 Remove an entry from an sc_hash_table by value. More...
 
void sc_hash_table_clear (struct sc_hash_table *table)
 Clear all entries from an sc_hash_table. More...
 
const void * sc_hash_table_val_to_key (struct sc_hash_table *table, const void *val)
 Return the key associated with a given value. More...
 
unsigned sc_hash_table_key_size (struct sc_hash_table *table)
 Get the size in bytes of a hash table's keys. More...
 
unsigned sc_hash_table_val_size (struct sc_hash_table *table)
 Get the size in bytes of each value buffer. More...
 
unsigned sc_hash_table_num_entries (struct sc_hash_table *table)
 Get the number of entries in an sc_hash_table. More...
 
int sc_hash_table_get_next_entry (struct sc_hash_table *table, void **key_out, void **val_out, unsigned *iterator)
 Iterate over key-value pairs in an sc_hash_table. More...
 

Detailed Description

A hash table with open addressing and double hashing.

Function Documentation

int sc_hash_table_alloc ( struct sc_hash_table **  table_out,
unsigned  key_size,
unsigned  val_size,
unsigned  capacity 
)

Allocate an sc_hash_table.

Parameters
table_outThe allocated sc_hash_table is returned here
key_sizeThe size in bytes of keys
val_sizeThe size in bytes of values
capacityThe desired number of entries in the hash table.
Returns
0 on success, or a negative error code.

Note the underlying table is sized so that there is a high probability you be able to insert capacity entries, but this cannot be guaranteed.

void sc_hash_table_clear ( struct sc_hash_table table)

Clear all entries from an sc_hash_table.

Parameters
tableA hash table
int sc_hash_table_del ( struct sc_hash_table table,
const void *  key 
)

Remove an entry from an sc_hash_table by key.

Parameters
tableA hash table
keyThe key to remove
Returns
  • 0 on success
  • -ENOENT if key was not found
int sc_hash_table_del_val ( struct sc_hash_table table,
const void *  val 
)

Remove an entry from an sc_hash_table by value.

Parameters
tableA hash table
valPointer to the value of an entry in the hash table

val must be a valid pointer to an existing value stored in the hash table. ie. It must have been returned by sc_hash_table_get() or sc_hash_table_get_next_entry().

Returns
  • 0 if the key was successfully removed
  • -ENOENT if the value was not in the table
void sc_hash_table_free ( struct sc_hash_table table)

Free an sc_hash_table.

Parameters
tableA hash table
int sc_hash_table_get ( struct sc_hash_table table,
const void *  key,
bool  insert_if_not_found,
void **  val_out 
)

Lookup or insert an entry in a hash table.

If the entry matching key is found then a pointer to the corresponding value is returned in val_out. Otherwise if insert_if_not_found is true, then a new entry is inserted.

Parameters
tableA hash table
keyThe key to look for in the table
insert_if_not_foundIf true then an entry is inserted if not found
val_outPointer to value buffer returned here
Returns
  • 0 if the matching entry was found
  • 1 if insert_if_not_found was true and a new entry was added
  • -ENOENT if an entry was not found and insert_if_not_found was false
  • -ENOSPC if an entry was not found and it was not possible to insert a new entry
int sc_hash_table_get_next_entry ( struct sc_hash_table table,
void **  key_out,
void **  val_out,
unsigned *  iterator 
)

Iterate over key-value pairs in an sc_hash_table.

Parameters
tableA hash table
key_outPointer to the next key returned here
val_outPointer to the next value returned here
iteratorState used by the implementation to iterate over entries

iterator must point to storage allocated by the caller and initialised to zero before the first call.

NOTE: This function is relatively inefficient for hash tables with a low fill level because it scans entries linearly.

Returns
  • 0 on successfully finding the entry
  • -ENOENT when no further entries remain
int sc_hash_table_grow ( struct sc_hash_table table,
size_t  max_size 
)

Increase the capacity of a hash table.

After this call all key and value pointers will be stale.

Parameters
tableA hash table
max_sizeMaximum size of storage in bytes, or 0 for unlimited
Returns
  • 0 On success
  • -ENOSPC if it is not possible to grow the table further
unsigned sc_hash_table_key_size ( struct sc_hash_table table)

Get the size in bytes of a hash table's keys.

Parameters
tableA hash table
Returns
The size in bytes of the hash table's keys.
unsigned sc_hash_table_num_entries ( struct sc_hash_table table)

Get the number of entries in an sc_hash_table.

Parameters
tableA hash table
Returns
The number of entries in the hash table.
unsigned sc_hash_table_val_size ( struct sc_hash_table table)

Get the size in bytes of each value buffer.

Parameters
tableA hash table
Returns
The size in bytes of each value buffer.
const void* sc_hash_table_val_to_key ( struct sc_hash_table table,
const void *  val 
)

Return the key associated with a given value.

Parameters
tableA hash table
valPointer to the value of an entries in the hash table

val must be a valid pointer to an existing value stored in the hash table. ie. It must have been returned by sc_hash_table_get() or sc_hash_table_get_next_entry().

Returns
A pointer the key in the hash table

NOTE: This function cannot check the value pointer was valid.