XPCE Reference Manual: Section 1.74

1.74 class hash_table

The PCE class hash_table implements a fast associative table. Hash-tables are commonly used to map symbols on values. For example, PCE itself uses the hash_table @classes to map class names onto class objects.

PCE hash_tables are implemented as closed hash_tables. The number of buckets in enlarged automatically as the number of symbols in the table grows.

Note that hash_tables implement the standard set operations hash_table->for_all, hash_table->for_some, hash_table<-find_key and hash_table<-find_value.

See also class chain_table (mapping a key onto multiple values), class sheet and class table (multi-column indexed table).

See also: - class sheet
- class table

1.74.1 Instance variables

hash_table-buckets: alien:int

Number of buckets in the table. Automatically doubled if the table is filled over 2/3-th.

NOTE: The number of buckets is a power of 2. Hash-table literature claims prime numbers to provide a better distribution. Timing on the SUN-SPARC station suggests this does ot compensate for the difference between a division and a masking operation.

hash_table-refer: {none,name,value,both}

Hash_tables are used internally by PCE in algorithms where the table should not give a reference count to the objects in it. Internal use only.

hash_table <- size: int

Number of symbols in the table.

See also: hash_table->empty

hash_table-symbols: alien:Symbol

Alien pointer to the symbols.

1.74.2 Send methods

hash_table ->append: key=any, value=any

Append a new association to the table. The first argument is the key; the second is the associated value. If the key was already in the table, associated value is changed.

hash_table ->buckets: int

Set the number of buckets in the table. This method might be useful for two purposes:

When the number of elements in known in advance, setting the number of buckets avoids rehashing.
The number of buckets is not minimised if members are deleted or the table is cleared. The hash_table->buckets method may be used to make the table smaller.
The next legal value (large enough and a power of 2) is used.

hash_table ->clear:

Delete all entries from the table. After hash_table->clear, hash_table<-size equals 0. The number of buckets is not changed.

hash_table ->delete: key=any

Delete association with given key. If there is no such association, hash_table->delete fails.

hash_table ->empty:

Test if hash_table<-size equals 0.

See also: hash_table-size

hash_table ->for_all: action=code, safe=[bool]

Run code on all elements of the table. If code fails for some symbol, this method immediately exists with failure. Arguments:

@arg1: Key of the symbol

@arg2: Value of the symbol

Note that the order in which the symbols are presented to the code is not specified.

See also: - chain->for_all
- hash_table->for_some

hash_table ->for_some: action=code, safe=[bool]

Run code on all elements of the table. The return status of code is ignored.

@arg1: Key of the symbol

@arg2: Value of the symbol

Note that the order in which the symbols are presented to the code is not specified.

See also: hash_table->for_all

hash_table ->initialise: buckets=[int]

Create a hash_table. The argument is the number of buckets. Note that this will be automatically increased if necessary. Normally it is not specified.

Defaults: 8

hash_table ->unlink:

Clears the table and deallocates the alien symbol array.

1.74.3 Get methods

hash_table <-buckets: -> buckets=int

Value of the alien variable -buckets, indicating the current number of buckets in the table. A power of 2.

hash_table <-find_key: test=code -> key=any

Run code on all elements of the table until it succeeds. Then return the key of the symbol for which code succeeded. Arguments:

@arg1: Key of the symbol

@arg2: Value of the symbol

Fails if there is no symbol for which code succeeds. Note that the order in which the symbols are presented to the keys is not specified. See also hash_table<-find_value.