Configuration & Lifecycle

Macros
#define	HT_Grow(flag)   (((uint32)HT_GROW_##flag) << 24)
#define	htInit(out, keytype, valtype, initsz, ...)    _htInit(out, stFullType(keytype), stFullType(valtype), initsz, opt_flags(__VA_ARGS__))

Enumerations
enum	HASHTABLE_FLAGS_ENUM {   HT_CaseInsensitive = 0x0001 , HT_RefKeys = 0x0002 , HT_Ref = 0x0004 , HT_InsertOpt = 0x0008 ,   HT_Compact = 0x0010 , HTINT_Metadata = 0x1000 , HTINT_Quadratic = 0x2000 , HTINT_Pow2 = 0x4000 ,   HTINT_Extended = 0x8000 }
	Hash table configuration flags. More...
enum	HASHTABLE_FUNC_FLAGS_ENUM { HT_Ignore = 0x00010000 , HT_Borrow = 0x00020000 , HTINT_Consume = 0x10000000 }
	Function-specific flags. More...

Functions
void	htDestroy (hashtable *htbl)
void	htClear (hashtable *htbl)

Detailed Description

Configuration flags, growth settings, and table lifecycle management (init/destroy/clear)

Macro Definition Documentation

HT_Grow

#define HT_Grow

(

flag

)

(((uint32)HT_GROW_##flag) << 24)

HT_Grow(flag)

Converts a growth flag to the format used in the flags parameter

Growth behavior is controlled by two factors: when to grow (threshold) and by how much (rate). These can be combined, or use the convenient presets for common scenarios.

Available flags:

Preset Combinations (Recommended):

Flag	Threshold	Growth Rate	Use Case
MaxSpeed	50% full	4x (300%)	Maximum performance, uses more memory
MinSize	90% full	1.5x (50%)	Minimum memory usage, slower performance

Growth Thresholds (when to expand):

Flag	Threshold	Notes
At50	50% full	Better performance, uses more memory
At75	75% full	Balanced default
At90	90% full	Memory efficient, worse performance

Growth Rates (how much to expand):

Flag	Multiplier	Notes
By50	1.5x	Slow growth, memory efficient
By100	2x	Balanced default (double size)
By200	3x	Fast growth
By300	4x	Fastest growth, uses more memory

Thresholds and rates can be combined by using bitwise OR, though the presets cover most use cases.

Parameters

flag	Growth configuration (e.g., MaxSpeed, MinSize, At75, By100)

Returns

Formatted flags value for use with htInit() Example:

// Use preset for maximum speed
htInit(&ht, string, int32, 16, HT_Grow(MaxSpeed));
 
// Or combine custom threshold and rate
htInit(&ht, string, int32, 16, HT_Grow(At75) | HT_Grow(By200));

Definition at line 321 of file hashtable.h.

htInit

#define htInit	(		out,
			keytype,
			valtype,
			initsz,
			...
	)		_htInit(out, stFullType(keytype), stFullType(valtype), initsz, opt_flags(__VA_ARGS__))

void htInit(hashtable *out, keytype, valtype, uint32 initsz, [flags])

Initializes a new hash table with the specified key and value types

Parameters

out	Pointer to hashtable handle to receive the new table
keytype	Runtime type for keys (e.g., string, int32, etc.)
valtype	Runtime type for values, or 'none' for a hash set
initsz	Initial capacity (will be rounded up, 0 for default)
...	(flags) Optional combination of HT_* flags Example: hashtable ht; htInit(&ht, string, int32, 16, HT_Grow(MaxSpeed)); // ... use table ... htDestroy(&ht);

Definition at line 344 of file hashtable.h.

Enumeration Type Documentation

HASHTABLE_FLAGS_ENUM

enum HASHTABLE_FLAGS_ENUM

Hash table configuration flags.

Enumerator
HT_CaseInsensitive	Case-insensitive key matching - only valid for string keys.
HT_RefKeys	Use borrowed references for keys instead of copying them Keys will not be destroyed when the hash table is freed Only use this if keys are guaranteed to outlive the hash table
HT_Ref	Use borrowed references for values instead of copying them Values will not be destroyed when the hash table is freed Only use this if values are guaranteed to outlive the hash table
HT_InsertOpt	Optimize for high-frequency inserts by allocating full chunks at once By default the storage array grows by quarter-chunks to avoid wasting too much memory. High traffic hash tables can set this flag to always allocate full chunks for better insert performance.
HT_Compact	Ultra-compact mode with minimal memory footprint Does not preallocate any storage memory. Inserts will be slow! This is useful for tables that should be as small as possible and are used for read-mostly lookups.

Definition at line 205 of file hashtable.h.

HASHTABLE_FUNC_FLAGS_ENUM

enum HASHTABLE_FUNC_FLAGS_ENUM

Function-specific flags.

Enumerator
HT_Ignore	Do not insert if a matching key already exists - returns existing element instead Note Valid for htInsert()
HT_Borrow	If copying out an object-type variable, copy a borrowed reference rather than acquiring a reference or making a deep copy Note Valid for htFind()

Definition at line 260 of file hashtable.h.

Function Documentation

htClear()

void htClear

(

hashtable *

htbl

)

Removes all entries from the hash table but keeps the structure allocated

All keys and values are properly destroyed (unless HT_Ref/HT_RefKeys was used) The table can be reused after clearing

Parameters

htbl	Pointer to the hash table to clear

htDestroy()

void htDestroy

(

hashtable *

htbl

)

Destroys a hash table and frees all associated memory

All keys and values are properly destroyed (unless HT_Ref/HT_RefKeys was used) Sets *htbl to NULL after destruction Safe to call with NULL or a pointer to NULL

Parameters

htbl	Pointer to the hash table to destroy