## hci - Hash Cell Table Iterator

### Module Description

The hci module implements an iterator on the hash cell table [hct].

### Module Words

#### Iterator structure

hci% ( -- n )
  Get the required space for a hash cell table iterator

#### Iterator creation, initialisation and destruction words

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

#### Member words

hci-get ( hci -- false | x true )
  Get the cell data x from the current record
hci-key ( hci -- c-addr u )
  Get the key from the current record
hci-set ( x hci -- )
  Set the cell data x in the current record

#### Iterator words

hci-first ( hci -- x true | false )
  Move the iterator to the first record, return the cell data of this record
hci-next ( hci -- x true | false )
  Move the iterator to the next record, return the cell data from this record
hci-move ( x hci -- flag )
  Move the iterator to the next record with the cell data x, return success
hci-first? ( hci -- flag )
  Check if the iterator is on the first record
hci-last? ( hci -- flag )
  Check if the iterator is on the last record

#### Inspection

hci-dump ( hci -- )
  Dump the iterator

### 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