{Association-of tk:Type, te:Type} (class)
public abstract Association-of {inherits {Aggregate-of te}}
Package: CURL.LANGUAGE.CONTAINERS
Direct Known Subclasses: RecordData, Repository, Directory, BucketHashTable-of, Sequence-of, HashTable-of

Abstract parameterized class for collections that associate a key with an element.

tk: is the data type of the keys in the collection.
te: is the data type of the elements in the collection.

Description

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



Association-of provides the interface for the collection classes that associate a key with an element. Hash tables (HashTable-of) are the only such collections that are built into Curl.

You cannot instantiate Association-of because it is an abstract class. To create a key/element collection object, instantiate HashTable-of.

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.

Properties
efficient-size:Gets or sets the efficient-size of self.
accessor public inline Association-of.efficient-size:int
setter public inline Association-of.efficient-size:int
empty?:Checks if the collection is empty.
accessor public Association-of.empty?:bool
key-type:Returns the data type of the keys.
accessor public final inline Association-of.key-type:Type
size:Returns the number of elements in the collection.
accessor public abstract Association-of.size:int
Properties inherited from Aggregate-of: element-type
Methods
clear:Deletes all elements.
public {Association-of.clear}:void
clone:Returns a clone of the collection.
public abstract {Association-of.clone}:{Association-of tk, te}
filter:Filters elements, using the elements themselves in the filter operation.
public {Association-of.filter p:{proc-type {te}:bool}}:void
filter-clone:Returns a clone of the collection, with elements filtered out (using the elements themselves in the filter operation).
public {Association-of.filter-clone
    p:{proc-type {te}:bool}
}:{Association-of tk, te}
filter-keys:Filters elements, using the keys in the filter operation.
public {Association-of.filter-keys p:{proc-type {tk}:bool}}:void
filter-keys-clone:Returns a clone of the collection, with elements filtered out (using the keys in the filter operation).
public {Association-of.filter-keys-clone
    p:{proc-type {tk}:bool}
}:{Association-of tk, te}
get:Returns a specific element.
public {Association-of.get key:tk}:te
get-if-exists:Returns the element indexed by key, along with a boolean that signifies whether the indicated element was found.
public abstract {Association-of.get-if-exists
    key:tk
}:(value:te, found?:bool)
get-key:Returns a specific key.
public {Association-of.get-key key:tk}:tk
get-key-if-exists:Returns a specific key, along with a boolean that signifies whether the indicated key was found.
public {Association-of.get-key-if-exists key:tk}:(key:tk, found?:bool)
key-exists?:Check if a key exists.
public {Association-of.key-exists? key:tk}:bool
keys-to-Iterator:Returns an Iterator-of containing each key in the collection.
public abstract {Association-of.keys-to-Iterator}:{Iterator-of tk}
remove:Removes an element.
public abstract {Association-of.remove
    key:tk,
    length:int = 1,
    error-if-missing?:bool = true
}:void
set:Sets the value of an element.
public abstract {Association-of.set key:tk, element:te}:void
Methods inherited from Aggregate-of: to-Iterator
Methods inherited from Object: object-describe, object-describe-for-debugging, object-serialize

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

Gets or sets the efficient-size of self.

Description

A collection's efficient-size is the size to which it can grow and still function efficiently. This is defined on an implementation-basis, but will generally reflect the size of underlying data structures. Growth beyond their allocated sizes will require allocating new underlying data structures and copying data from the old structures; this is what is considered inefficient.
requested-size: The requested-size is evaluated by the system, given the type of the collection as well as the types contained therein, and may be modified. The resulting efficient-size, as obtained from the getter, will be equal to or greater than the requested-size.

Notes

The default implementation defined in Association-of is for the setter to be ignored and the getter to return max-int.

empty? (accessor)
accessor public Association-of.empty?:bool

Checks if the collection is empty.

Returns

A bool value. Returns true if self has no elements. Otherwise, returns false.

Example

The following example shows a hash table with no elements.


Example
|| Declare and initialize an empty hash table.
{let my-table:{HashTable-of int, String} =
    {new {HashTable-of int, String}}}

|| Check if the hash table is empty and display an
|| appropriate message.
{if my-table.empty? then
    {text The hash table is empty!}
 else
    {text The hash table has elements!}
}


The following example shows a hash table with elements.


Example
|| Declare and initialize a hash table with
|| int keys and String elements.
{let my-table:{HashTable-of int, String} =
    {new {HashTable-of int, String},
        1, "apple"
    }
}

|| Check if the hash table is empty and display an
|| appropriate message.
{if my-table.empty? then
    {text The hash table is empty!}
 else
    {text The hash table has elements!}
}

key-type (accessor)
accessor public final inline Association-of.key-type:Type

Returns the data type of the keys.

Returns

A valid data type.

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 the data type of key in price.
    price.key-type
}

size (accessor)
accessor public abstract Association-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 {Association-of.clear}:void

Deletes all elements.

Description

This method removes elements one at a time, by iterating over the collection. If you subclass Association-of, it might be possible to override this method with a more efficient implementation. For example, if a collection has a writable size property, it might be more efficient to reset the size rather than to iterate over the 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 abstract {Association-of.clone}:{Association-of tk, te}

Returns a clone of the collection.

Returns

An instance of a subclass of Aggregate-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 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 set-1 (the original set).
    let set-1:{Set-of String} =
        {new {Set-of String}, "apple", "banana", "cherry"}

    || Initialize set-2 with a clone of the contents of
    || set-1.
    let set-2:{Set-of String} = {set-1.clone}

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

Notes

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

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 (method)
public {Association-of.filter p:{proc-type {te}:bool}}:void

Filters elements, 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

This method does not return a value.

Description

Removes the elements of the collection for which a call to p returns false.

Example

The following example filters elements from a hash table.


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"
        }

    || Filter elements that begin with the
    || letter 'd'.
    {my-table.filter
        {proc {str:String}:bool
            {return str[0] != 'd'}
        }
    }

    || Use a VBox to display the contents of my-table.
    || Add each element to the VBox and then display it.
    let message:VBox = {VBox}
    {for each-element:String in my-table do
        {message.add each-element}
    }
    message

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

filter-clone (method)
public {Association-of.filter-clone
    p:{proc-type {te}:bool}
}:{Association-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 (method)
public {Association-of.filter-keys p:{proc-type {tk}:bool}}:void

Filters elements, 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.

Description

Removes the elements of self for which a call to p with the associated key returns false.

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
        }

    || Filter elements whose keys begin with 'a'.
    {quantity.filter-keys
        {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 quantity do
        {message.add each-element}
    }
    message

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

filter-keys-clone (method)
public {Association-of.filter-keys-clone
    p:{proc-type {tk}:bool}
}:{Association-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 (method)
public {Association-of.get key:tk}:te

Returns a specific element.

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

Returns

The element that you want to get. The return value has the same data type as the elements in self.

Throws

Should throw KeyNotFoundException if no such element exists.

Description

Returns the element in self that corresponds to key.

Also see get-if-exists.

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 for the presence of "banana" and "cherry",
    || showing how [] syntax can be used to call "get"
    || methods.
    {text The price of bananas is {price.get "banana"},
        the price of cherries is {value price["cherry"]}.}

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

get-if-exists (method)
public abstract {Association-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 (method)
public {Association-of.get-key key:tk}:tk

Returns a specific key.

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

Returns

The key. The return value has the same data type as the keys in self.

Description

If the parameter key is a key in self, return the key, otherwise it throws a KeyNotFoundException. This method is useful for interning purposes.

Also see get-key-if-exists.

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 method to get the original keys.
The hash table contains prices for...
  {price.get-key "apple"}
  {price.get-key "banana"}
  {price.get-key "cherry"}

get-key-if-exists (method)
public {Association-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.

key-exists? (method)
public {Association-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 abstract {Association-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.

remove (method)
public abstract {Association-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 abstract {Association-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.