Advanced Hashtable is a component that wraps the .NET Dictionary<string, object> class. It enables flexible key-value storage with support for multiple data types and nested hashtables, making it useful in dynamic and complex logic scenarios in which performance is critical.

Features

• Store and retrieve multiple data types: Text, Integer, Long Integer, Decimal, Boolean, DateTime, Binary Data, and Object.
• Support for nested hashtables.
• Optional key-to-index mapping for array-style access.
• Try-get pattern for safe value retrieval.
• Full control over hashtable entries, including cloning and clearing.

Initialization

• HT_Init: Initializes and returns an empty hashtable object.
• HT_InitKeyIndexMap: Initializes an internal key-index mapping to enable array-like operations. Must be called before using HT_ArraySet or HT_ArrayGet* actions.

Setting Values

• HT_Set: Sets or updates a value for a given key.
• HT_SetEntries: Replaces the hashtable’s content with a provided list of key-value pairs.
• HT_ArraySet: Sets a value at a specific index (integer), using the internal key-index map initialized by HT_InitKeyIndexMap.

Getting Values

These actions retrieve a value by key. If the key is not found in the collection, a default value (i.e. 0 for integers, "" for strings, etc) is returned instead.

• HT_GetText
• HT_GetInteger
• HT_GetLongInteger
• HT_GetDecimal
• HT_GetBoolean
• HT_GetDateTime
• HT_GetBinaryData
• HT_GetObject

Getting Values (safe try pattern)

These actions try to retrieve a value by key and return an output flag (KeyExists) to indicate that the value was successfully found and returned. This is more performant than using a combination of HT_Exists followed by HT_Get*.

• HT_TryGetText
• HT_TryGetInteger
• HT_TryGetLongInteger
• HT_TryGetDecimal
• HT_TryGetBoolean
• HT_TryGetDateTime
• HT_TryGetBinaryData
• HT_TryGetObject

Array Support

These actions allow interaction with hashtables as if they were arrays. Requires HT_ArrayCreate to be called first.

• Set
  • HT_ArraySet
• Get
  • HT_ArrayGetText
  • HT_ArrayGetInteger
  • HT_ArrayGetLongInteger
  • HT_ArrayGetDecimal
  • HT_ArrayGetBoolean
  • HT_ArrayGetDateTime
  • HT_ArrayGetBinaryData
  • HT_ArrayGetObject
• Return array capacity
  • HT_ArrayCount

Entry Inspection

• HT_Exists: Checks if a key exists.
• HT_ExistsValue: Checks if a value exists.
• HT_Count: Returns the number of entries in the hashtable.
• HT_Entries: Returns a list of all key-value pairs.
• HT_Keys: Returns a list of all keys.
• HT_Values: Returns a list of all values.

Maintenance

• HT_Remove: Removes a value by key.
• HT_Clear: Removes all entries from the hashtable.
• HT_Clone: Returns a deep copy of the hashtable, including any nested hashtables.

Remarks

• Nested hashtables are supported by passing one hashtable as a value into another using HT_Set.
• For safer access patterns, prefer HT_TryGet* over HT_Get* when keys may not be present.