What the Class Is Used For

Use Chilkat.Hashtable when an application needs a lightweight in-memory mapping from keys to values. It is useful for storing parameters, options, temporary lookup values, URL query fields, and other small collections of string or integer data.

Store String Values Add or replace string entries with AddStr and read them with LookupStr.

Store Integer Values Add or replace integer entries with AddInt and read them with LookupInt.

Work with Query Strings Import URL query parameters with AddQueryParams and export them with ToQueryString.

Serialize to XML Save entries to XML with ToXmlSb and restore them with AddFromXmlSb.

Typical Workflow

Create a Hashtable object.
Add values with AddStr, AddInt, or AddQueryParams.
Check whether a key exists with Contains or ContainsIntKey.
Retrieve values with LookupStr or LookupInt.
Remove entries with Remove, or clear the entire table with Clear.
Use GetKeys to append all key strings to a StringTable when enumeration is needed.
Serialize the table with ToQueryString or ToXmlSb if the contents need to be exported.
Check LastErrorText if a method fails or behaves unexpectedly.

Core Concepts

Concept	Meaning	Important Members
Key/Value Storage	Each entry is stored by key and can contain either a string or integer value.	AddStr, AddInt, LookupStr, LookupInt
Replacement	Adding a value for an existing key replaces the old value.	AddStr, AddInt
Membership Test	Checks whether a key exists before lookup or removal.	Contains, ContainsIntKey
Query Parameters	URL query fields can be loaded into the table and later serialized back to a query string.	AddQueryParams, ToQueryString
XML Serialization	Hashtable contents can be exported to XML and later restored.	ToXmlSb, AddFromXmlSb
Capacity	The number of buckets used internally by the hash table.	ClearWithNewCapacity

Properties

Property	Purpose	Guidance
Count	Number of items currently contained in the hash table.	Use to check whether the table is empty or to understand how many entries are stored.
LastErrorText	Diagnostic information for the last method or property access.	Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Adding and Replacing Values

Method	Value Type	Behavior
AddStr	String	Adds or replaces an entry with the given key and string value. Returns false only if an out-of-memory condition occurs.
AddInt	Integer	Adds or replaces an entry with the given key and integer value. Returns false only if an out-of-memory condition occurs.
AddQueryParams	URL query string fields	Adds fields from a query string such as field1=value1&field2=value2. Values are assumed to be URL encoded and are automatically URL decoded before insertion.
AddFromXmlSb	XML created by ToXmlSb	Adds entries from previously serialized hashtable XML.

Replacement behavior: AddStr and AddInt add a new entry when the key is not present, or replace the existing entry when the key already exists.

Looking Up and Testing Values

Method	Purpose	Important Details
Contains	Checks whether a string key exists.	Returns true if the key exists, otherwise false.
ContainsIntKey	Checks whether an integer key exists.	Returns true if the key exists, otherwise false.
LookupStr	Returns the string value for a key.	Use after adding string values with AddStr or importing query parameters.
LookupInt	Returns the integer value for a key.	If the key is not found, the return value is 0. Use Contains first if 0 could also be a valid stored value.
GetKeys	Appends all key strings to a StringTable.	Use when the complete set of keys needs to be enumerated.

Removing and Clearing Entries

Method	Purpose	Important Details
Remove	Removes the entry with the specified key.	Returns true if the key existed and was removed. Returns false if the key did not already exist.
Clear	Removes all elements from the hashtable.	Use to empty the table while keeping normal capacity behavior.
ClearWithNewCapacity	Removes all elements and resizes the hashtable to a specified capacity.	Use when the expected number of future items is known and the bucket count should be adjusted.

Capacity note: The capacity is the number of buckets in the hash table. In a hash collision, a single bucket can store multiple entries that must be searched sequentially.

Capacity Guidance

Topic	Guidance
Initial default capacity	The initial default capacity is 521.
Expected item count	A practical rule of thumb is to set capacity to about twice the expected number of items.
Prime capacities	It is preferable for the capacity to be a prime number.
When to resize	Use ClearWithNewCapacity when clearing the table and preparing it for a different expected number of entries.

Query String Support

Method	Direction	Behavior
AddQueryParams	Query string to hashtable	Parses query parameters in the form field1=value1&field2=value2 and adds the decoded values to the hashtable.
ToQueryString	Hashtable to query string	Serializes the hashtable as key1=value1&key2=value2, URL encoding each value.

URL encoding behavior: AddQueryParams automatically URL decodes values before inserting them. ToQueryString URL encodes values when serializing the table.

XML Serialization

Method	Purpose	Use When
ToXmlSb	Serializes the hashtable to XML and appends it to a StringBuilder.	Use when table contents should be saved or transferred as XML.
AddFromXmlSb	Adds entries from XML previously created by ToXmlSb.	Use to restore or merge serialized hashtable contents.

Method Summary by Category

Category	Methods / Properties	Purpose
Add values	AddStr, AddInt, AddQueryParams, AddFromXmlSb	Add or replace entries using string values, integer values, query parameters, or serialized XML.
Look up values	LookupStr, LookupInt, Contains, ContainsIntKey	Check whether keys exist and retrieve stored values.
Enumerate keys	GetKeys	Append all key strings to a StringTable.
Remove or clear	Remove, Clear, ClearWithNewCapacity	Remove a single entry, clear all entries, or clear and resize the hashtable.
Serialize	ToQueryString, ToXmlSb	Export table contents as a URL query string or XML.
Inspect	Count	Get the number of items currently stored.
Diagnostics	LastErrorText	Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
Integer lookup returns 0	LookupInt, Contains	LookupInt returns 0 if the key does not exist. Use Contains first when 0 is also a valid stored value.
Query parameter values look encoded or decoded unexpectedly	AddQueryParams, ToQueryString	Remember that imported query parameter values are URL decoded, and serialized query string values are URL encoded.
Key removal returns false	Remove	The key did not already exist in the hashtable.
Performance concerns with many entries	ClearWithNewCapacity	Consider clearing and resizing with a capacity about twice the expected item count, preferably using a prime number.
Need to inspect all keys	GetKeys	Append keys to a StringTable and iterate them there.
Need operation details after failure	LastErrorText	Check diagnostic text after failed or unexpected add, lookup, serialization, XML import, removal, or resize operations.

Common Pitfalls

Pitfall	Better Approach
Assuming AddStr or AddInt fails when the key already exists.	These methods add or replace. Existing values are replaced for the same key.
Using LookupInt without checking whether the key exists.	Use Contains first if 0 could be a real stored value.
Expecting AddQueryParams to preserve URL encoding.	Values are URL decoded before insertion.
Expecting ToQueryString to output raw values.	Values are URL encoded when serialized to a query string.
Clearing the table without resizing when the expected number of items changes greatly.	Use ClearWithNewCapacity when a different bucket capacity is desired.
Ignoring diagnostics after unexpected behavior.	Check LastErrorText for details.

Best Practices

Recommendation	Reason
Use Contains before lookup when absence matters.	This is especially important for integer values because LookupInt returns 0 when the key is missing.
Use AddQueryParams for URL query strings.	It automatically parses fields and URL decodes values before insertion.
Use ToQueryString when preparing URL-encoded output.	It serializes entries in query-string form and URL encodes each value.
Use ToXmlSb and AddFromXmlSb for persistence or transfer.	XML serialization allows the table contents to be saved and later restored or merged.
Use ClearWithNewCapacity when expected size changes.	Choosing an appropriate bucket count can reduce collision-related lookup work.
Use GetKeys for enumeration.	It provides the complete set of key strings through a StringTable.
Check LastErrorText after failures.	It provides useful diagnostic detail for failed or unexpected hashtable operations.

Summary

Chilkat.Hashtable is a lightweight key/value collection for storing string and integer values. It supports adding and replacing entries, checking key existence, looking up values, removing entries, clearing and resizing the table, enumerating keys, importing and exporting URL query strings, and serializing to or restoring from XML.

The most important practical guidance is to remember that add operations replace existing keys, LookupInt returns 0 when a key is missing, query parameter import automatically URL decodes values, query string export URL encodes values, and ClearWithNewCapacity can be used when the expected number of entries changes significantly.

Chilkat.Hashtable Class Overview