---
product: Chilkat
product_version: 11.7.0
language: wc
language_label: Unicode C
class: Hashtable
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/wc_CkHashtableWRef.html
---
# Chilkat Hashtable — Unicode C — v11.7.0

> Chilkat 11.7.0 · language=wc · class=Hashtable
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/Hashtable.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/guide.md`.

## Purpose

**Store, look up, remove, enumerate, import, and serialize key/value pairs.**

`Chilkat.Hashtable` provides a simple key/value collection for storing string and integer values by key. It can add or replace entries, look up values, test whether keys exist, remove entries, count items, enumerate keys, import URL query parameters, serialize values back to a query string, and save or load the table in XML format.

**String and integer values**

Store values as strings or integers using straightforward add, replace, and lookup methods.

**Fast key lookup**

Check whether a key exists and retrieve its value without manually scanning a list or parsing text.

**Add, replace, and remove**

Maintain a mutable collection by adding new entries, replacing existing values, removing individual keys, or clearing the table.

**Enumerate keys**

Retrieve the set of keys when application logic needs to loop through the stored entries.

**Query string helpers**

Import URL query parameters into the table and serialize the table back to a query-string representation.

**XML persistence**

Save the hashtable to XML or reload it from XML when values need to be persisted or transferred in a simple structured format.

**Common pattern:** Use `Hashtable` when application code needs a small mutable key/value table, especially for lookup tables, parsed query parameters, or simple string/integer settings. Add values with `AddStr` or `AddInt`, retrieve them with `LookupStr` or `LookupInt`, and use XML or query-string methods when the table needs to be saved, loaded, or converted.

For an extended overview, see [Hashtable Class Overview](https://www.chilkatsoft.com/hashtable_class_overview.asp).

## Object creation, unlocking and error handling

**Create/Dispose**

```c
HCkHashtableW instance = CkHashtableW_Create();
// ...
CkHashtableW_Dispose(instance);
```

`HCkHashtableW CkHashtableW_Create(void);`

Creates an instance of the HCkHashtableW object and returns a handle ("void \*" pointer). The handle is passed in the 1st argument for the functions listed on this page.

`void CkHashtableW_Dispose(HCkHashtableW handle);`

Objects created by calling CkHashtableW_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkHashtableW_Dispose.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Unicode C.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `void CkHashtableW_getDebugLogFilePath(HCkHashtableW cHandle, HCkString retval); void CkHashtableW_putDebugLogFilePath(HCkHashtableW cHandle, const wchar_t *newVal); const wchar_t *CkHashtableW_debugLogFilePath(HCkHashtableW cHandle);` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `void CkHashtableW_getLastErrorHtml(HCkHashtableW cHandle, HCkString retval); const wchar_t *CkHashtableW_lastErrorHtml(HCkHashtableW cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkHashtableW_getLastErrorText(HCkHashtableW cHandle, HCkString retval); const wchar_t *CkHashtableW_lastErrorText(HCkHashtableW cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkHashtableW_getLastErrorXml(HCkHashtableW cHandle, HCkString retval); const wchar_t *CkHashtableW_lastErrorXml(HCkHashtableW cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkHashtableW_getLastMethodSuccess(HCkHashtableW cHandle); void CkHashtableW_putLastMethodSuccess(HCkHashtableW cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `VerboseLogging` | `BOOL CkHashtableW_getVerboseLogging(HCkHashtableW cHandle); void CkHashtableW_putVerboseLogging(HCkHashtableW cHandle, BOOL newVal);` | read/write | If set to `TRUE`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `void CkHashtableW_getVersion(HCkHashtableW cHandle, HCkString retval); const wchar_t *CkHashtableW_version(HCkHashtableW cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `Count` | property, read-only | `int CkHashtableW_getCount(HCkHashtableW cHandle);` |
| `AddFromXmlSb` | method | `BOOL CkHashtableW_AddFromXmlSb(HCkHashtableW cHandle, HCkStringBuilderW sbXml);` |
| `AddInt` | method | `BOOL CkHashtableW_AddInt(HCkHashtableW cHandle, const wchar_t *key, int value);` |
| `AddQueryParams` | method | `BOOL CkHashtableW_AddQueryParams(HCkHashtableW cHandle, const wchar_t *queryParams);` |
| `AddStr` | method | `BOOL CkHashtableW_AddStr(HCkHashtableW cHandle, const wchar_t *key, const wchar_t *value);` |
| `Clear` | method | `void CkHashtableW_Clear(HCkHashtableW cHandle);` |
| `ClearWithNewCapacity` | method | `BOOL CkHashtableW_ClearWithNewCapacity(HCkHashtableW cHandle, int capacity);` |
| `Contains` | method | `BOOL CkHashtableW_Contains(HCkHashtableW cHandle, const wchar_t *key);` |
| `ContainsIntKey` | method | `BOOL CkHashtableW_ContainsIntKey(HCkHashtableW cHandle, int key);` |
| `GetKeys` | method | `BOOL CkHashtableW_GetKeys(HCkHashtableW cHandle, HCkStringTableW strTable);` |
| `LookupInt` | method | `int CkHashtableW_LookupInt(HCkHashtableW cHandle, const wchar_t *key);` |
| `LookupStr` | method | `BOOL CkHashtableW_LookupStr(HCkHashtableW cHandle, const wchar_t *key, const wchar_t *outStr); const wchar_t *CkHashtableW_lookupStr(HCkHashtableW cHandle, const wchar_t *key);` |
| `Remove` | method | `BOOL CkHashtableW_Remove(HCkHashtableW cHandle, const wchar_t *key);` |
| `ToQueryString` | method | `BOOL CkHashtableW_ToQueryString(HCkHashtableW cHandle, const wchar_t *outStr); const wchar_t *CkHashtableW_toQueryString(HCkHashtableW cHandle);` |
| `ToXmlSb` | method | `BOOL CkHashtableW_ToXmlSb(HCkHashtableW cHandle, HCkStringBuilderW sbXml);` |

## Properties

### Hashtable.Count

`Chilkat 11.7.0 · wc · Hashtable · Count · property · read-only · since 9.5.0.97`

```c
int CkHashtableW_getCount(HCkHashtableW cHandle);
```

The number of entries currently stored in the hashtable.

Each key contributes one entry regardless of whether its value is a string or an integer. Adding a new key increases `Count`; replacing the value of an existing key does not. Removing an entry decreases it, and `Clear` resets it to `0`.

## Methods

### Hashtable.AddFromXmlSb

`Chilkat 11.7.0 · wc · Hashtable · AddFromXmlSb · method · since 9.5.0.64`

```c
BOOL CkHashtableW_AddFromXmlSb(HCkHashtableW cHandle, HCkStringBuilderW sbXml);
```

Reads hashtable XML previously produced by `ToXmlSb` from the `StringBuilder` passed in `sbXml` and adds the entries to this table.

The operation merges with the existing table: keys not present in the XML remain, and an imported entry replaces the current value for the same key. Call `Clear` first when the XML should completely replace the current contents.

Returns `TRUE` when the XML is parsed and imported successfully; otherwise returns `FALSE`.

Returns TRUE for success, FALSE for failure.

### Hashtable.AddInt

`Chilkat 11.7.0 · wc · Hashtable · AddInt · method · since 9.5.0.51`

```c
BOOL CkHashtableW_AddInt(HCkHashtableW cHandle, const wchar_t *key, int value);
```

Adds an entry whose string key is `key` and whose value is the integer `value`. If the key already exists, its previous value is replaced.

Returns `TRUE` when the entry is added or replaced. Returns `FALSE` if the operation cannot be completed, such as because memory could not be allocated.

**One entry per key:** Adding the same key again replaces the existing value; it does not create a second entry. Replacing a value does not increase `Count`. Use `LookupInt` to retrieve an integer value.

Returns TRUE for success, FALSE for failure.

### Hashtable.AddQueryParams

`Chilkat 11.7.0 · wc · Hashtable · AddQueryParams · method · since 9.5.0.62`

```c
BOOL CkHashtableW_AddQueryParams(HCkHashtableW cHandle, const wchar_t *queryParams);
```

Parses URL query parameters from `queryParams` and adds them to the hashtable as string entries. Pass the query component in the following form:

```
field1=value1&field2=value2&field3=value3
```

Each value is expected to be URL encoded and is URL decoded before being stored. If an imported key already exists, its previous value is replaced. Returns `TRUE` on success and `FALSE` if the query parameters cannot be imported.

**Repeated parameter names:** A hashtable stores one value per key. It cannot preserve a query string containing several independent values with the same field name. Use a list-oriented parser when repeated names must remain distinct.

Returns TRUE for success, FALSE for failure.

### Hashtable.AddStr

`Chilkat 11.7.0 · wc · Hashtable · AddStr · method · since 9.5.0.51`

```c
BOOL CkHashtableW_AddStr(HCkHashtableW cHandle, const wchar_t *key, const wchar_t *value);
```

Adds an entry whose string key is `key` and whose value is the string `value`. If the key already exists, its previous value is replaced.

Returns `TRUE` when the entry is added or replaced. Returns `FALSE` if the operation cannot be completed, such as because memory could not be allocated.

**One entry per key:** Adding the same key again replaces the existing value; it does not create a second entry. Replacing a value does not increase `Count`. Use `LookupStr` to retrieve a string value.

Returns TRUE for success, FALSE for failure.

### Hashtable.Clear

`Chilkat 11.7.0 · wc · Hashtable · Clear · method · since 9.5.0.51`

```c
void CkHashtableW_Clear(HCkHashtableW cHandle);
```

Removes every entry from the hashtable. After this call, `Count` is `0`.

The current hash-table capacity is retained. To clear the entries and also select a different bucket capacity, call `ClearWithNewCapacity`.

### Hashtable.ClearWithNewCapacity

`Chilkat 11.7.0 · wc · Hashtable · ClearWithNewCapacity · method · since 9.5.0.51`

```c
BOOL CkHashtableW_ClearWithNewCapacity(HCkHashtableW cHandle, int capacity);
```

Removes every entry and reinitializes the hashtable with `capacity` buckets. The initial default capacity of a new `Hashtable` object is `521`.

Returns `TRUE` on success and `FALSE` if the table cannot be reinitialized.

| Term | Meaning |
| :--- | :--- |
| `Count` | The number of stored entries. |
| Capacity | The number of hash buckets, not a maximum entry count. |

**Performance note:** More buckets can reduce collisions for a large table, but use more memory. Choosing roughly twice the expected number of entries and using a prime number are tuning guidelines, not correctness requirements.

Returns TRUE for success, FALSE for failure.

### Hashtable.Contains

`Chilkat 11.7.0 · wc · Hashtable · Contains · method · since 9.5.0.51`

```c
BOOL CkHashtableW_Contains(HCkHashtableW cHandle, const wchar_t *key);
```

Returns `TRUE` if the hashtable contains the string key `key`; otherwise returns `FALSE`. The result tests key existence regardless of the value stored for that key.

**Useful before lookup:** Call `Contains` when a lookup result could be ambiguous. For example, `LookupInt` returns `0` both for a missing key and for an entry whose value is actually zero.

### Hashtable.ContainsIntKey

`Chilkat 11.7.0 · wc · Hashtable · ContainsIntKey · method · since 9.5.0.64`

```c
BOOL CkHashtableW_ContainsIntKey(HCkHashtableW cHandle, int key);
```

Returns `TRUE` if the hashtable contains the integer key `key`; otherwise returns `FALSE`.

**Key type:** This method accepts an integer key. It is distinct from `Contains`, which tests for a string key, and from `AddInt`, whose key is a string and whose value is an integer.

### Hashtable.GetKeys

`Chilkat 11.7.0 · wc · Hashtable · GetKeys · method · since 9.5.0.62`

```c
BOOL CkHashtableW_GetKeys(HCkHashtableW cHandle, HCkStringTableW strTable);
```

Appends all hashtable key strings to the `StringTable` passed in `strTable`. Existing strings already contained in `strTable` are not cleared.

Returns `TRUE` on success and `FALSE` on failure.

**Enumeration order:** Hashtable keys may be returned in any order. Do not depend on insertion order or sorted order. Clear the destination `StringTable` first when it should contain only the current hashtable keys.

Returns TRUE for success, FALSE for failure.

### Hashtable.LookupInt

`Chilkat 11.7.0 · wc · Hashtable · LookupInt · method · since 9.5.0.51`

```c
int CkHashtableW_LookupInt(HCkHashtableW cHandle, const wchar_t *key);
```

Returns the integer value associated with the string key `key`. This method is intended for entries stored with `AddInt`.

If the key does not exist, the return value is `0`.

**Missing key versus zero:** Because `0` is also a valid stored value, call `Contains` first when the application must distinguish a missing key from an entry containing zero.

### Hashtable.LookupStr

`Chilkat 11.7.0 · wc · Hashtable · LookupStr · method · since 9.5.0.51`

```c
BOOL CkHashtableW_LookupStr(HCkHashtableW cHandle, const wchar_t *key, const wchar_t *outStr);
const wchar_t *CkHashtableW_lookupStr(HCkHashtableW cHandle, const wchar_t *key);
```

Returns the string value associated with the string key `key`. This method is intended for entries stored as strings, including entries added by `AddStr` or `AddQueryParams`.

**Check lookup success:** The representation of a failed string-returning call varies by programming language and may be `null`, `Nothing`, or an empty string. An empty string may also be a legitimate value. Use `Contains` or `LastMethodSuccess` when the distinction matters.

Returns TRUE for success, FALSE for failure.

### Hashtable.Remove

`Chilkat 11.7.0 · wc · Hashtable · Remove · method · since 9.5.0.51`

```c
BOOL CkHashtableW_Remove(HCkHashtableW cHandle, const wchar_t *key);
```

Removes the entry whose string key is `key`.

- Returns `TRUE` if the key existed and the entry was removed.
- Returns `FALSE` if the key was not present.

A `FALSE` result caused by an absent key is a normal lookup outcome, not an indication that the hashtable was damaged. Removing an existing entry decreases `Count` by one.

### Hashtable.ToQueryString

`Chilkat 11.7.0 · wc · Hashtable · ToQueryString · method · since 9.5.0.92`

```c
BOOL CkHashtableW_ToQueryString(HCkHashtableW cHandle, const wchar_t *outStr);
const wchar_t *CkHashtableW_toQueryString(HCkHashtableW cHandle);
```

Serializes the hashtable as a URL query string in the following form:

```
key1=value1&key2=value2&key3=value3
```

Each value is URL encoded. The returned string does not include a leading `?`.

**Important limitations:** Key order is not defined, and a hashtable contains only one value per key. Therefore the output is not suitable when parameter order is significant or repeated field names must be preserved. In language bindings where string-return failure is ambiguous, check `LastMethodSuccess`.

Returns TRUE for success, FALSE for failure.

### Hashtable.ToXmlSb

`Chilkat 11.7.0 · wc · Hashtable · ToXmlSb · method · since 9.5.0.64`

```c
BOOL CkHashtableW_ToXmlSb(HCkHashtableW cHandle, HCkStringBuilderW sbXml);
```

Serializes the current hashtable to Chilkat's hashtable XML format and appends the XML to the `StringBuilder` passed in `sbXml`. Existing content in the `StringBuilder` is preserved.

Returns `TRUE` on success and `FALSE` on failure. The generated XML can be loaded by `AddFromXmlSb`.

```
&lt;hashtable&gt;
  &lt;e&gt;&lt;k&gt;key&lt;/k&gt;&lt;v&gt;value&lt;/v&gt;&lt;/e&gt;
&lt;/hashtable&gt;
```

**Ordering:** Because hashtable enumeration order is not defined, do not rely on entries appearing in insertion order or use the serialized text as a canonical, byte-for-byte representation.

Returns TRUE for success, FALSE for failure.

## Related classes

[`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/StringBuilder.md), [`StringTable`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/StringTable.md)

