{HashTable-of tk:Type, te:Type, key-hash-proc:any = value-hash, key-equality-proc:any = equal? } (class)
public serializable HashTable-of {inherits {Association-of tk, te}}
Package: CURL.LANGUAGE.CONTAINERS
Direct Known Subclasses: HttpHeaders, JsonObject

Parameterized class for hash tables.

tk: is the data type of the keys in the hash table.
te: is the data type of the elements in the hash table.
key-hash-proc: is a procedure that returns the hash value of a key. This procedure takes one parameter, which has the same data type as the keys in the hash table (tk), and returns an int. key-hash-proc and key-equality-proc must have mutually consistent semantics. If a call to key-equality-proc for two keys returns true, calls to key-hash-proc for each of the two keys must produce the same hash value. The default value for key-hash-proc is value-hash.
key-equality-proc: A procedure that determines whether two keys are equal. This procedure takes two parameters, which have the same data type as the keys in the hash table (tk), and returns a bool. If the two keys are equal, this procedure should return true. Otherwise, it should return false. key-hash-proc and key-equality-proc must have mutually consistent semantics. If a call to key-equality-proc for two keys returns true, calls to key-hash-proc for each of the two keys must produce the same hash value. The default value for key-equality-proc is equal?.

Description

There are a number of collection types built into Curl, including:



A hash table is an unordered collection of elements. Each element has an associated key. You use the key to access an element. The keys and the elements can have any data type. For instance, this means that you can have String keys.

Notes

A partial hierarchy of the collection classes in Curl follows:

Aggregate-of
∟ Association-of
∟ HashTable-of
∟ Sequence-of
∟ Array-of
∟ Array-2-of
∟ Set-of
FastArray-of

For more information about collections in Curl, see Curl Developer's Guide: Collections.

Notes

If you include more than one entry with the same key value, the last entry is stored in the hash table.

Notes

If the contents of a collection change while you are iterating over that collection, the results are undefined.

Constructors
clone-from:Initialize a HashTable-of.
constructor public {HashTable-of.clone-from
    from:{HashTable-of tk, te, key-hash-proc = key-hash-proc, key-equality-proc = key-equality-proc }
}
default:Initialize a HashTable-of.
constructor public {HashTable-of.default efficient-size:int = 4, ...:any}
object-deserialize:
constructor public {HashTable-of.object-deserialize in:SerializeInputStream}
Properties
efficient-size:Gets or sets the efficient-size of self.
accessor public HashTable-of.efficient-size:int
setter public HashTable-of.efficient-size:int
size:Returns the number of elements in the collection.
accessor public HashTable-of.size:int
Properties inherited from Association-of: empty?, key-type
Properties inherited from Aggregate-of: element-type
Methods
clear:Removes all elements.
public {HashTable-of.clear}:void
clone:Returns a clone of the hash table.
public {HashTable-of.clone
}:{HashTable-of tk, te, key-hash-proc=key-hash-proc, key-equality-proc=key-equality-proc }
filter-clone:Returns a clone of the collection, with elements filtered out (using the elements themselves in the filter operation).
public {HashTable-of.filter-clone
    p:{proc-type {te}:bool}
}:{HashTable-of tk, te}
filter-keys-clone:Returns a clone of the collection, with elements filtered out (using the keys in the filter operation).
public {HashTable-of.filter-keys-clone
    p:{proc-type {tk}:bool}
}:{HashTable-of tk, te}
get-if-exists:Returns the element indexed by key, along with a boolean that signifies whether the indicated element was found.
public {HashTable-of.get-if-exists key:tk}:(value:te, found?:bool)
get-key-if-exists:Returns a specific key, along with a boolean that signifies whether the indicated key was found.
public {HashTable-of.get-key-if-exists key:tk}:(key:tk, found?:bool)
grow:Increases the structures that internally represent the hash table.
public {HashTable-of.grow}:void
key-exists?:Check if a key exists.
public {HashTable-of.key-exists? key:tk}:bool
keys-to-Iterator:Returns an Iterator-of containing each key in the collection.
public {HashTable-of.keys-to-Iterator}:{Iterator-of tk}
object-serialize:Called by the serialization code when a class instance is to be written.
public {HashTable-of.object-serialize out:SerializeOutputStream}:void
rehash:Rehashes self.
public {HashTable-of.rehash}:void
remove:Removes an element.
public {HashTable-of.remove
    key:tk,
    length:int = 1,
    error-if-missing?:bool = true
}:void
set:Sets the value of an element.
public {HashTable-of.set key:tk, element:te}:void
to-Iterator:Returns an Iterator-of that produces each element of self.
public {HashTable-of.to-Iterator}:{Iterator-of te}
Methods inherited from Association-of: filter, filter-keys, get, get-key
Methods inherited from Object: object-describe, object-describe-for-debugging

Constructor Details
clone-from (constructor)
public {HashTable-of.clone-from
    from:{HashTable-of tk, te, key-hash-proc = key-hash-proc, key-equality-proc = key-equality-proc }
}

Initialize a HashTable-of.

from: The initial contents of self are copied from from.

default (constructor)
public {HashTable-of.default efficient-size:int = 4, ...:any}

Initialize a HashTable-of.

efficient-size: An estimated size for the hash table, used to tune the hash table for greater efficiency. Note that the system will choose an appropriate value which will be greater than or equal to the value specified. This may be retrieved by the efficient-size getter.
...: The rest arguments specify the keys and elements that you want to initially place in the hash table. Specify the keys and elements in pairs, with the key preceding the element. Use a comma to separate all keys and elements.

Description

Initialize a new HashTable-of object. If rest arguments are provided, include them as initial values in the hash table.

object-deserialize (constructor)
public {HashTable-of.object-deserialize in:SerializeInputStream}
This item is unsupported and reserved for internal use.

Property Details
efficient-size (accessor)
accessor public HashTable-of.efficient-size:int
setter public HashTable-of.efficient-size:int

Gets or sets the efficient-size of self.

Description

This is an implementation of the efficient-size semantics as defined in Association-of.efficient-size.

size (accessor)
accessor public HashTable-of.size:int

Returns the number of elements in the collection.

Returns

An int indicating the number of elements in self.

Example


Example
{value
    || Declare and initialize a hash table with
    || String keys and int elements.
    let price:{HashTable-of String, int} =
        {new {HashTable-of String, int},
             "apple", 56,
             "banana", 87,
             "cherry", 34
        }

    || Display a message indicating the size of
    || the hash table.
    {text There are {value price.size} elements in
        the hash table.}
}

Notes

This is an abstract method of Association-of; it is implemented in subclasses of Association-of.

Method Details
clear (method)
public {HashTable-of.clear}:void

Removes all elements.

Example


Example
{value
    || Declare and initialize a hash table with
    || int keys and String elements.
    let my-table:{HashTable-of int, String} =
        {new {HashTable-of int, String},
             162094, "tom",
             439853, "dick",
             098627, "harry"
        }

    || Clear the hash table.
    {my-table.clear}

    || Check if the hash table is empty.
    {text The assertion that the hash table is empty is...
        {value my-table.empty?}}
}

clone (method)
public {HashTable-of.clone
}:{HashTable-of tk, te, key-hash-proc=key-hash-proc, key-equality-proc=key-equality-proc }

Returns a clone of the hash table.

Returns

An instance of HashTable-of. The object has the same data type and data as self.

Description

A clone is a new object with the same data type as self. The clone is a shallow copy of self; this means that it contains unique references to the original elements of self. Hence, if you replace or remove an element in the original collection, you are not affecting the element in the clone collection.

Example


Example
|| Declare and initialize a hash table with
|| String keys and int elements.
{let table-1:{HashTable-of int, String} =
    {new {HashTable-of int, String},
         162094, "tom",
         439853, "dick",
         098627, "harry"
    }
}

|| Declare table-2 (a target hash table) and initialize it with
|| a copy of the contents of table-1.
{let table-2:{HashTable-of int, String} = {table-1.clone}}

|| Use a VBox to display the contents of table-2.
|| For each key in table-2 add an HBox to the VBox.
|| The HBox contains the relevant key and element.
|| Then display the VBox.
{let message:VBox = {VBox}}
{for key i:int in table-2 do
    {message.add {HBox i, " ", {table-2.get i}}}
}
{value message}

Notes

For a detailed description of cloning, see the section on cloning in Curl Developer's Guide: Collections: Hash Tables.

filter-clone (method)
public {HashTable-of.filter-clone
    p:{proc-type {te}:bool}
}:{HashTable-of tk, te}

Returns a clone of the collection, with elements filtered out (using the elements themselves in the filter operation).

p: is a procedure that filters the elements. This method calls p for each element in self. The procedure must take one argument that has the same data type as the elements of self. The procedure must return one value; a bool indicating if this method filters the element. If p returns false, this method filters (removes) the element from self. If p returns true, the element remains in self.

Returns

An instance of a subclass of Association-of. The object has the same data type as self. It contains a clone of the collection, with some elements filtered out.

Description

This method returns a clone of self. In the clone, elements for which a call to the procedure p returns false are removed. A clone is a new object with the same data type as self. The clone contains shallow copies of the elements in self. This means that if you assign a new object to an element in either collection, the corresponding element in the other collection still refers to the original object. However, if you alter the object in an element, both collections refer to the updated object.

Example

The following example creates a clone of a hash table, with all elements that begin with the letter d filtered out.


Example
{value
    || Declare and initialize a hash table with
    || int keys and String elements.
    let my-table-1:{HashTable-of int, String} =
        {new {HashTable-of int, String},
             162094, "tom",
             439853, "dick",
             098627, "harry"
        }

    || Create a clone my-table-2 that contains the elements
    || of my-table-1 with strings that begin with the letter
    || 'd' filtered out.
    let my-table-2:{HashTable-of int, String} =
        {my-table-1.filter-clone
            {proc {str:String}:bool
                {return str[0] != 'd'}
            }
        }

    || Use a VBox to display the contents of my-table-2.
    || Iterate over the contents of my-table-2, adding
    || them to the VBox.  Then display the VBox.
    let message:VBox = {VBox}
    {for each-element:String in my-table-2 do
        {message.add each-element}
    }
    message

    || Note that the order of the elements in a hash
    || table is arbitrary.
}

Notes

For a detailed description of cloning, see the section on cloning for the collection that you are using in Curl Developer's Guide: Collections.

filter-keys-clone (method)
public {HashTable-of.filter-keys-clone
    p:{proc-type {tk}:bool}
}:{HashTable-of tk, te}

Returns a clone of the collection, with elements filtered out (using the keys in the filter operation).

p: is a procedure that filters the elements. This method calls p for each key in self. The procedure must take one argument that has the same data type as the keys of self. The procedure must return one value; a bool indicating if this method filters the associated element. If p returns false, this method filters (removes) the element from self. If p returns true, the element remains in self.

Returns

An instance of a subclass of Association-of. The object has the same data type as self.

Description

This method returns a clone of self. In the clone, elements of self for which a call to p with the associated key returns false are removed. A clone is a new object with the same data type as self. The clone contains shallow copies of the elements in self. This means that if you assign a new object to an element in either collection, the corresponding element in the other collection still refers to the original object. However, if you alter the object in an element, both collections refer to the updated object.

Example


Example
{value
    || Declare and initialize a hash table with
    || String keys and int elements.
    let quantity:{HashTable-of String, int} =
        {new {HashTable-of String, int},
             "apple", 3,
             "banana", 0,
             "cherry", 8
        }

    || Create a clone that contains the elements of the
    || original with keys that begin with the letter
    || 'a' filtered out.
    let new-quantity:{HashTable-of String, int} =
        {quantity.filter-keys-clone
            {proc {str:String}:bool
                {return str[0] != 'a'}
            }
        }

    || Use a VBox to display the contents of quantity.
    || For each key in quantity, add the key to the VBox.
    || Then display the VBox.
    let message:VBox = {VBox}
    {for key each-element:String in new-quantity do
        {message.add each-element}
    }
    message

    || Note that the order of the elements in a hash
    || table is arbitrary.
}

Notes

For a detailed description of cloning, see the section on cloning for the collection that you are using in Curl Developer's Guide: Collections.

get-if-exists (method)
public {HashTable-of.get-if-exists key:tk}:(value:te, found?:bool)

Returns the element indexed by key, along with a boolean that signifies whether the indicated element was found.

key: is the value of the key for the element that you want to retrieve.

Returns

This method returns two values: If the second return value is false, the first return value is undefined.

get-key-if-exists (method)
public {HashTable-of.get-key-if-exists key:tk}:(key:tk, found?:bool)

Returns a specific key, along with a boolean that signifies whether the indicated key was found.

key: is the value of the key that you want to retrieve.

Returns

The key currently being used by the container that is equal to the supplied key. The return value has the same data type as the keys in self. Also returns a flag indicating whether the key was found.

Description

If the parameter key is a key in self, return the key, in which case the second return value is true. Otherwise, the value returned is undefined and the second return value is false.

This method is useful for interning purposes.

Example


Example
|| Declare and initialize a hash table with
|| String keys and int elements.
{let price:{HashTable-of String, int} =
    {new {HashTable-of String, int},
         "apple", 56,
         "banana", 87,
         "cherry", 34
    }
}

|| Use the get-key-if-exists method to check for the
|| presence of keys.
The hash table contains prices for...
  {price.get-key-if-exists "apple"}
  {price.get-key-if-exists "banana"}
  {price.get-key-if-exists "pear"}
  {price.get-key-if-exists "cherry"}
  {price.get-key-if-exists "orange"}

Notes

This method is implemented in Association-of. It is then overridden in some subclasses of Association-of.

grow (method)
public {HashTable-of.grow}:void

Increases the structures that internally represent the hash table.

Description

Increases the size of the internal tables to the next power of two. Rehashes self into the new tables.

key-exists? (method)
public {HashTable-of.key-exists? key:tk}:bool

Check if a key exists.

key: is the value of the key for which you want check. The value must have the same data type as the keys in self.

Returns

A bool value. This method returns true if the value is a key in self. Otherwise, it returns false.

Example


Example
{value
    || Declare and initialize a hash table with
    || String keys and int elements.
    let price:{HashTable-of String, int} =
        {new {HashTable-of String, int},
             "apple", 56,
             "banana", 87,
             "cherry", 34
        }

    || Check if there is an element with the
    || key "banana" in the collection "price".
    {if {price.key-exists? "banana"} then
        {text It is there!}
     else
        {text It is not there.}
    }
}

keys-to-Iterator (method)
public {HashTable-of.keys-to-Iterator}:{Iterator-of tk}

Returns an Iterator-of containing each key in the collection.

Returns

An Iterator-of with the same parameterized data type as the keys in self. In other words, if self is an {Association-of int, String}, this method returns an {Iterator-of int}.

Description

The order of the keys in the Iterator-of is arbitrary (because instances of Association-of are not necessarily ordered collections).

Example


Example
{value
    || Declare and initialize a hash table with
    || int keys and String elements.
    let my-table:{HashTable-of int, String} =
        {new {HashTable-of int, String},
             162094, "tom",
             439853, "dick",
             098627, "harry"
        }

    || Create an Iterator-of from the set.
    let my-iterator:{Iterator-of int} =
        {my-table.keys-to-Iterator}

    || Use a VBox to display the contents of my-iterator.
    || Iterate over the contents of my-iterator, adding
    || them to the VBox.  Then display the VBox.
    let message:VBox = {VBox}
    {for each-element:int in my-iterator do
        {message.add each-element}
    }
    message

    || Note that the order of the elements in a hash
    || table is arbitrary.
}

Notes

Alternatively, you can use a for container loop to achieve the same results. Where possible, you should use a for loop in case this iteration mechanism is overridden, producing unexpected results.

Notes

This is an abstract method of Association-of; it is implemented in subclasses of Association-of.

object-serialize (method)
public {HashTable-of.object-serialize out:SerializeOutputStream}:void

Called by the serialization code when a class instance is to be written.

out: The SerializeOutputStream that called this method.

Description

This method must do the following steps, in order:

  1. It must call SerializeOutputStream.write-class-version, normally with an argument of zero.
  2. It must call super.object-serialize for each serializable superclass.
  3. It must write its serialized state to out. This is normally done by calling SerializeOutputStream.write-one for each field.

Notes

This method should only be defined by serializable subclasses.

rehash (method)
public {HashTable-of.rehash}:void

Rehashes self.


remove (method)
public {HashTable-of.remove
    key:tk,
    length:int = 1,
    error-if-missing?:bool = true
}:void

Removes an element.

key: is the value of the key for the element that you want to remove. This value must have the same data type as the keys in self.
length: It is an error to supply this parameter.

length is an int indicating the number of successive elements that you want to remove from the collection. Because hash tables are not an ordered collection, this parameter has no meaning for this method. This parameter applies only to subclasses of Sequence-of, which implement ordered collections.

For this method, length is set to the default value of 1.
error-if-missing?: is a Boolean flag that indicates if this method generates an error when you try to remove an element that does not exist. If error-if-missing? is true, this method throws an error when you try to remove an element that does not exist. An error terminates execution of the program and displays an appropriate error message. By default, error-if-missing? is true. If error-if-missing? is false, this method does not generate an error. error-if-missing? is a keyword argument. To specify error-if-missing?, make sure to assign the desired value to the keyword in the method call (for example error-if-missing?=false).

Description

If {self.key-exists? key} is true, this method removes the appropriate key and element from self.

If {self.key-exists? key} is false and error-if-missing? is true, this method throws an error. However, if error-if-missing? is false, this method does nothing.

Example


Example
{value
    || Declare and initialize a hash table with
    || String keys and int elements.
    let price:{HashTable-of String, int} =
        {new {HashTable-of String, int},
             "apple", 56,
             "banana", 87,
             "cherry", 34
        }

    || Remove the element at key "banana".
    {price.remove "banana"}

    || Use a VBox to display the contents of price.
    || For each key in price, add a string to the VBox.
    || The string contains the relevant key and element.
    || Then display the VBox.
    let message:VBox = {VBox}
    {for key each-element:String in price do
        {message.add each-element & " " & {price.get each-element}}
    }
    message

    || Note that the order of the elements in a hash
    || table is arbitrary.
}

Notes

This is an abstract method of Association-of; it is implemented in subclasses of Association-of.

set (method)
public {HashTable-of.set key:tk, element:te}:void

Sets the value of an element.

key: is the value of the key for the element that you want to set. This value must have the same data type as the keys in self.
element: is the value of the element. This value must have the same data type as the elements in self.

Description

If key exists in self, this method changes the value of the associated element to element. If key does not exist in self, this method adds a new element (key, element) to self.

Example


Example
{value
    || Declare and initialize a hash table with
    || String keys and int elements.
    let price:{HashTable-of String, int} =
        {new {HashTable-of String, int},
             "apple", 56,
             "banana", 87,
             "cherry", 34
        }

    || Change the element at key "banana".
    {price.set "banana", 72}

    || Add an element for "pear".
    {price.set "pear", 62}

    || Use a VBox to display the contents of price.
    || For each key in price, add a string to the VBox.
    || The string contains the relevant key and element.
    || Then display the VBox.
    let message:VBox = {VBox}
    {for key each-element:String in price do
        {message.add each-element & " " & {price.get each-element}}
    }
    message

    || Note that the order of the elements in a hash
    || table is arbitrary.
}

Notes

This is an abstract method of Association-of; it is implemented in subclasses of Association-of.

to-Iterator (method)
public {HashTable-of.to-Iterator}:{Iterator-of te}

Returns an Iterator-of that produces each element of self.

Returns

An Iterator-of with the same parameterized data type as the elements in self. In other words, if self is a {HashTable-of int, String } , this method returns an {{Iterator-of String}}.

Example


Example
{value                || Declare and initialize a hash table with
    || String keys and int elements
    let h:{HashTable-of int, String} =
        {new {HashTable-of int, String},
             162094, "tom",
             439853, "dick",
             098627, "harry"
        }

    || Create an Iterator-of from the hash table.
    let my-iterator:{Iterator-of String} =
        {h.to-Iterator}

    || Use a VBox to display the contents of my-iterator.
    || Iterate over the contents of my-iterator, adding
    || them to the VBox.  Then display the VBox.
    let message:VBox = {VBox}
    {for each-element:String in my-iterator do
        {message.add each-element}
    }
    message
}

Notes

The order of the elements in the Iterator-of is arbitrary, because hash tables are unordered collections.

Notes

You can use a for container loop to achieve the same results. for is actually the preferred way to iterate over a container, because this iteration mechanism may be overridden, producing unexpected results.