Package com.chilkatsoft.chilkat2

Class Hashtable

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Hashtable
All Implemented Interfaces:
AutoCloseable
public class Hashtable extends ChilkatObject
<section class="hashtable-summary">

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.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Hashtable

      public Hashtable()
      Creates a new Hashtable object.

  • Method Details

    • getCount

      public int 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.

      Returns:
      the value of the Count property (read-only)

    • addFromXmlSb

      public void addFromXmlSb​(StringBuilder 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.

      Parameters:
      sbXml - the sbXml argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addInt

      public void addInt​(String 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.

      Parameters:
      key - the key argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addQueryParams

      public void addQueryParams​(String 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.

      Parameters:
      queryParams - the queryParams argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addStr

      public void addStr​(String key, String 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.

      Parameters:
      key - the key argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clear

      public void 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.

    • clearWithNewCapacity

      public void clearWithNewCapacity​(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.

      Parameters:
      capacity - the capacity argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • contains

      public boolean contains​(String 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.

      Parameters:
      key - the key argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • containsIntKey

      public boolean containsIntKey​(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.

      Parameters:
      key - the key argument
      Returns:
      the result; this method never throws ChilkatException

    • getKeys

      public void getKeys​(StringTable 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.

      Parameters:
      strTable - the strTable argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • lookupInt

      public int lookupInt​(String 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.

      Parameters:
      key - the key argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • lookupStr

      public String lookupStr​(String 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.

      Parameters:
      key - the key argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • remove

      public boolean remove​(String 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.

      Parameters:
      key - the key argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • toQueryString

      public String toQueryString()
      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:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toXmlSb

      public void toXmlSb​(StringBuilder 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.

      Parameters:
      sbXml - the sbXml argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why