--- product: Chilkat product_version: 11.7.0 language: pascal language_label: Lazarus Pascal class: Hashtable license: free deprecated: false reference_html: https://www.chilkatsoft.com/refdoc/pascal_HashtableRef.html --- # Chilkat Hashtable — Lazarus Pascal — v11.7.0 > Chilkat 11.7.0 · language=pascal · class=Hashtable > Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0//classes/Hashtable.md`. > Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/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 / Free** ```pascal uses Chilkat.Hashtable; var obj: THashtable; begin obj := THashtable.Create; try if not obj.IsValid then raise Exception.Create('Failed to create a THashtable instance.'); // ... use obj ... finally obj.Free; end; end; ``` `constructor Create;` Allocates the underlying CkHashtable object and returns a new THashtable instance. Simply adding **Chilkat.Hashtable** to the unit's `uses` clause is enough to locate and bind to the Chilkat shared library (DLL / .so / .dylib) at runtime — no separate load step is required. Check `obj.IsValid` after calling `Create`; it is `False` if the underlying library could not be found/loaded or the object could not be allocated (for example, when unlicensed). `destructor Destroy; override;` Every THashtable created by calling `Create` should eventually be released by calling `.Free` (inherited from `TObject`). The destructor automatically disposes the underlying CkHashtable handle. A native (unmanaged) memory leak occurs if the object is never freed. 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 Lazarus Pascal. ## 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` | `property DebugLogFilePath: string read GetDebugLogFilePath write SetDebugLogFilePath;` | 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` | `property LastErrorHtml: string read GetLastErrorHtml;` | read-only | Provides HTML-formatted information about the last called method or property. | | `LastErrorText` | `property LastErrorText: string read GetLastErrorText;` | read-only | Provides plain text information about the last called method or property. | | `LastErrorXml` | `property LastErrorXml: string read GetLastErrorXml;` | read-only | Provides XML-formatted information about the last called method or property. | | `LastMethodSuccess` | `property LastMethodSuccess: Boolean read GetLastMethodSuccess write SetLastMethodSuccess;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. | | `VerboseLogging` | `property VerboseLogging: Boolean read GetVerboseLogging write SetVerboseLogging;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. | | `Version` | `property Version: string read GetVersion;` | read-only | Version of the component/library, such as "10.1.0" | ## Member index | Member | Kind | Signature | |---|---|---| | `Count` | property, read-only | `property Count: Integer read GetCount;` | | `AddFromXmlSb` | method | `// sbXml is a TStringBuilder object. function AddFromXmlSb(sbXml: TChilkatBase): Boolean;` | | `AddInt` | method | `function AddInt(const key: string;     value: Integer): Boolean;` | | `AddQueryParams` | method | `function AddQueryParams(const queryParams: string): Boolean;` | | `AddStr` | method | `function AddStr(const key: string;     const value: string): Boolean;` | | `Clear` | method | `procedure Clear;` | | `ClearWithNewCapacity` | method | `function ClearWithNewCapacity(capacity: Integer): Boolean;` | | `Contains` | method | `function Contains(const key: string): Boolean;` | | `ContainsIntKey` | method | `function ContainsIntKey(key: Integer): Boolean;` | | `GetKeys` | method | `// strTable is a TStringTable object. function GetKeys(strTable: TChilkatBase): Boolean;` | | `LookupInt` | method | `function LookupInt(const key: string): Integer;` | | `LookupStr` | method | `function LookupStr(const key: string): string;` | | `Remove` | method | `function Remove(const key: string): Boolean;` | | `ToQueryString` | method | `function ToQueryString: string;` | | `ToXmlSb` | method | `// sbXml is a TStringBuilder object. function ToXmlSb(sbXml: TChilkatBase): Boolean;` | ## Properties ### Hashtable.Count `Chilkat 11.7.0 · pascal · Hashtable · Count · property · read-only · since 9.5.0.97` ```pascal property Count: Integer read GetCount; ``` 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 · pascal · Hashtable · AddFromXmlSb · method · since 9.5.0.64` ```pascal // sbXml is a TStringBuilder object. function AddFromXmlSb(sbXml: TChilkatBase): Boolean; ``` 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 · pascal · Hashtable · AddInt · method · since 9.5.0.51` ```pascal function AddInt(const key: string;     value: Integer): Boolean; ``` 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 · pascal · Hashtable · AddQueryParams · method · since 9.5.0.62` ```pascal function AddQueryParams(const queryParams: string): Boolean; ``` 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 · pascal · Hashtable · AddStr · method · since 9.5.0.51` ```pascal function AddStr(const key: string;     const value: string): Boolean; ``` 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 · pascal · Hashtable · Clear · method · since 9.5.0.51` ```pascal procedure Clear; ``` 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 · pascal · Hashtable · ClearWithNewCapacity · method · since 9.5.0.51` ```pascal function ClearWithNewCapacity(capacity: Integer): Boolean; ``` 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 · pascal · Hashtable · Contains · method · since 9.5.0.51` ```pascal function Contains(const key: string): Boolean; ``` 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 · pascal · Hashtable · ContainsIntKey · method · since 9.5.0.64` ```pascal function ContainsIntKey(key: Integer): Boolean; ``` 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 · pascal · Hashtable · GetKeys · method · since 9.5.0.62` ```pascal // strTable is a TStringTable object. function GetKeys(strTable: TChilkatBase): Boolean; ``` 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 · pascal · Hashtable · LookupInt · method · since 9.5.0.51` ```pascal function LookupInt(const key: string): Integer; ``` 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 · pascal · Hashtable · LookupStr · method · since 9.5.0.51` ```pascal function LookupStr(const key: string): string; ``` 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 · pascal · Hashtable · Remove · method · since 9.5.0.51` ```pascal function Remove(const key: string): Boolean; ``` 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 · pascal · Hashtable · ToQueryString · method · since 9.5.0.92` ```pascal function ToQueryString: string; ``` 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 · pascal · Hashtable · ToXmlSb · method · since 9.5.0.64` ```pascal // sbXml is a TStringBuilder object. function ToXmlSb(sbXml: TChilkatBase): Boolean; ``` 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`. ``` <hashtable> <e><k>key</k><v>value</v></e> </hashtable> ``` **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/pascal/classes/StringBuilder.md), [`StringTable`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/StringTable.md)