Hash Table Operations

Macros
#define	htInsert(htbl, ktype, key, vtype, val, ...)
#define	htInsertC(htbl, ktype, key, vtype, val, ...)
#define	htFind(htbl, ktype, key, vtype, val_copy_out, ...)
#define	htExtract(htbl, ktype, key, vtype, val_copy_out)    _htExtractChecked(htbl, stCheckedArg(ktype, key), stCheckedPtrArg(vtype, val_copy_out))
#define	htRemove(htbl, ktype, key)    _htExtractChecked(htbl, stCheckedArg(ktype, key), stType(none), NULL)
#define	htHasKey(htbl, ktype, key)   _htHasKeyChecked(htbl, stCheckedArg(ktype, key))

Functions
void	htReindex (hashtable *htbl, uint32 minsz)
void	htRepack (hashtable *htbl)
void	htClone (hashtable *out, hashtable ref)

Detailed Description

Functions for modifying, inserting, searching, and removing elements

Macro Definition Documentation

htExtract

#define htExtract	(		htbl,
			ktype,
			key,
			vtype,
			val_copy_out
	)		_htExtractChecked(htbl, stCheckedArg(ktype, key), stCheckedPtrArg(vtype, val_copy_out))

bool htExtract(hashtable *htbl, ktype, key, vtype, *val_copy_out)

Removes a key-value pair from the hash table and optionally extracts the value

If val_copy_out is provided, the value is extracted (ownership transferred) rather than destroyed. The caller becomes responsible for destroying the extracted value. The key is always destroyed (unless HT_RefKeys was used).

Parameters

htbl	Pointer to the hash table
ktype	Type of the key
key	Key to remove
vtype	Type of the value, or 'none' to destroy it
val_copy_out	Pointer to receive the extracted value, or NULL to destroy it

Returns

true if the key was found and removed, false if not found Example:

string extracted = 0;
if (htExtract(&ht, string, _S"key", string, &extracted)) {
    // use extracted
    strDestroy(&extracted);
}

Definition at line 559 of file hashtable.h.

htFind

#define htFind	(		htbl,
			ktype,
			key,
			vtype,
			val_copy_out,
			...
	)

Value:

    _htFindChecked(htbl,                                   \
                   stCheckedArg(ktype, key),               \
                   stCheckedPtrArg(vtype, val_copy_out),   \
                   opt_flags(__VA_ARGS__))

htelem htFind(hashtable htbl, ktype, key, vtype, *val_copy_out, [flags])

Searches for a key in the hash table and optionally copies out the value

If val_copy_out is provided and not NULL, the value is copied into it. The caller is responsible for destroying the copied value with the appropriate destructor. If vtype is 'none', no value copy is performed and val_copy_out is ignored.

Parameters

htbl	The hash table to search
ktype	Type of the key (must match table type)
key	Key to search for
vtype	Type of the value, or 'none' to skip copying the value
val_copy_out	Pointer to receive a copy of the value, or NULL
...	(flags) Optional: HT_Borrow for borrowed reference on objects

Returns

Element handle (htelem) if found, or 0 if not found. The return value can be used directly in boolean context Example:

int32 val;
if (htFind(ht, string, _S"key", int32, &val)) {
    // found, use val
}
// -- OR --
htelem elem = htFind(ht, string, _S"key", none, NULL);
if (elem) {
    val = hteVal(ht, int32, elem);
}

Definition at line 517 of file hashtable.h.

htHasKey

#define htHasKey	(		htbl,
			ktype,
			key
	)		_htHasKeyChecked(htbl, stCheckedArg(ktype, key))

bool htHasKey(hashtable htbl, ktype, key)

Checks if a key exists in the hash table without retrieving its value

This is more efficient than htFind when you only need to check for existence.

Parameters

htbl	The hash table to search
ktype	Type of the key
key	Key to check for

Returns

true if the key exists, false otherwise Example:

if (htHasKey(ht, string, _S"key")) {
    // key exists
}

Definition at line 604 of file hashtable.h.

htInsert

#define htInsert	(		htbl,
			ktype,
			key,
			vtype,
			val,
			...
	)

Value:

    _htInsertChecked(htbl,                          \
                     stCheckedArg(ktype, key),      \
                     stCheckedArg(vtype, val),      \
                     opt_flags(__VA_ARGS__))

htelem htInsert(hashtable *htbl, ktype, key, vtype, val, [flags])

Inserts or updates a key-value pair in the hash table

The key and value are copied according to their type semantics. For strings and objects, references are properly managed. If the key already exists, the old value is destroyed and replaced with the new value (unless HT_Ignore is used).

Parameters

htbl	Pointer to the hash table handle
ktype	Type of the key (must match table type)
key	Key value to insert
vtype	Type of the value (must match table type)
val	Value to insert or update
...	(flags) Optional: HT_Ignore to skip if key exists

Returns

Element handle (htelem) that can be used to access the key/value. Returns existing element if key already exists (unless HT_Ignore is set) Example:

htelem elem = htInsert(&ht, string, _S"key", int32, 42);
int32 *valptr = hteValPtr(ht, int32, elem);

Definition at line 443 of file hashtable.h.

htInsertC

#define htInsertC	(		htbl,
			ktype,
			key,
			vtype,
			val,
			...
	)

Value:

    _htInsertCheckedC(htbl,                          \
                      stCheckedArg(ktype, key),      \
                      stCheckedPtrArg(vtype, val),   \
                      opt_flags(__VA_ARGS__) | HTINT_Consume)

htelem htInsertC(hashtable *htbl, ktype, key, vtype, *val, [flags])

Inserts a key-value pair, consuming/stealing the value to avoid copying

This is an optimized version of htInsert that takes ownership of the value instead of copying it. The value variable will be destroyed/cleared after this call even on failure. The key is still copied normally. This is useful for expensive-to-copy values like long strings or when transferring ownership.

Parameters

htbl	Pointer to the hash table handle
ktype	Type of the key (must match table type)
key	Key value to insert
vtype	Type of the value (must match table type)
val	Pointer to value to consume
...	(flags) Optional flags

Returns

Element handle for the inserted entry Example:

string longstr = 0;
strDup(&longstr, _S"very long string...");
htInsertC(&ht, string, _S"key", string, &longstr);  // longstr is now NULL

Definition at line 470 of file hashtable.h.

htRemove

#define htRemove	(		htbl,
			ktype,
			key
	)		_htExtractChecked(htbl, stCheckedArg(ktype, key), stType(none), NULL)

bool htRemove(hashtable *htbl, ktype, key)

Removes a key-value pair from the hash table, destroying both key and value

This is a convenience wrapper around htExtract that always destroys the value.

Parameters

htbl	Pointer to the hash table
ktype	Type of the key
key	Key to remove

Returns

true if the key was found and removed, false if not found Example:

htRemove(&ht, string, _S"key");

Definition at line 575 of file hashtable.h.

Function Documentation

htClone()

void htClone	(	hashtable *	out,
		hashtable	ref
	)

Creates a deep copy of the hash table

All keys and values are properly copied according to their type semantics The output must be destroyed with htDestroy() when no longer needed

Parameters

out	Pointer to receive the cloned hash table
ref	Source hash table to clone

htReindex()

void htReindex	(	hashtable *	htbl,
		uint32	minsz
	)

Rebuilds the hash table's index with a new minimum size

This can be used to grow or shrink the table manually All elements are preserved - only the internal index is rebuilt

Parameters

htbl	Pointer to the hash table
minsz	Minimum size for the rebuilt index

htRepack()

void htRepack

(

hashtable *

htbl

)

Rebuilds the hash table to eliminate deleted entries and fragmentation

This creates a compact copy of the table with no wasted space Useful after many deletions to reclaim memory

Parameters

htbl	Pointer to the hash table to repack