## hct - Hash Cell Table

### Module Description

The hct module implements a hash table that stores cell wide data.

### Module Words

#### Hash table structure

hct% ( -- n )
  Get the required space for a hash table variable

#### Hash table creation, initialisation and destruction

hct-init ( u hct -- )
  Initialise the hash table with an initial size u
hct-(free) ( hct -- )
  Free the nodes from the hash table
hct-create ( u "<spaces>name" -- ; -- hct )
  Create a named hash table with an initial size u in the dictionary
hct-new ( u -- hct )
  Create a hash table with an initial size u on the heap
hct-free ( hct -- )
  Free the hash table from the heap

#### Module words

hct+hash ( c-addr1 u1 -- u2 )
  Calculate the hash value of a key

#### Member words

hct-empty? ( hct -- flag )
  Check if the table is empty
hct-length@ ( hct -- u )
  Get the number of nodes in the table
hct-load@ ( hct -- u )
  Get the load factor [*100%]
hct-load! ( u hct -- )
  Set the load factor [*100%]
hct-size! ( u hct -- )
  Resize the hash table to size u

#### Hash table words

hct-insert ( x c-addr u hct -- )
  Insert cell data x with the key c-addr u in the table
hct-delete ( c-addr u hct -- false | x true )
  Delete the key c-addr u from the table, return the cell data related to the key
hct-get ( c-addr u hct -- false | x true )
  Get the cell data x related to the key c-addr u from the table
hct-has? ( c-addr u hct -- flag )
  Check if the key c-addr u is present in the table

#### Special words

hct-count ( x hct -- u )
  Count the number of occurrences of the cell data x in the table
hct-execute ( i*x xt hct -- j*x )
  Execute xt for every key and cell data in table

#### Inspection

hct-dump ( hct -- )
  Dump the hash table

### Examples

    include ffl/hct.fs
    include ffl/hci.fs

    \ Example: store mountain heights in a hash table

    \ Create the hash table in the dictionary with an initial size of 10

    10 hct-create height-table

    \ Add the mountains (in meters)

    8300 s" mount everest" height-table hct-insert
    4819 s" mont blanc"    height-table hct-insert
    5642 s" mount elbrus"  height-table hct-insert

    \ Get a mountain height

    s" mount everest" height-table hct-get [IF]
      .( Mount everest: ) . cr
    [ELSE]
      .( Unknown mountain) cr
    [THEN]

    s" vaalserberg" height-table hct-get [IF]
      .( Vaalserberg: ) . cr
    [ELSE]
      .( Unknown mountain) cr
    [THEN]

    \ Word for printing the mountain height

    : height-emit ( n c-addr u -- = height key )
      type ."  -> " . cr
    ;

    \ Print all mountain heights

    ' height-emit height-table hct-execute            \ Execute the word height-emit for all entries in the hash table

    \ Example hash table iterator

    \ Create the hash table iterator in the dictionary

    height-table hci-create height-iter               \ Create an iterator named height-iter on the height-table hash table

    \ Moving the iterator

    height-iter hci-first                         \ Move the iterator to the first record
    [IF]                                          \ If record exists Then ..
      height-iter hci-key type                    \   Type the key ..
      .(  => )
      .                                           \   .. and the value
      cr
    [THEN]

    8300 height-iter hci-move                     \ Move the iterator to the mountain with a height of 8300
    [IF]                                          \ If mountain exists Then ..
      height-iter hci-key type                    \   Type the name ..
      .(  => )
      height-iter hci-get drop .                  \   .. and the height
      cr
    [ELSE]
      .( No mountain found with a height of 8300) cr
    [THEN]

generated 03-Jun-2010 by ofcfrth-0.10.0