@c =================================================================== @c
@c    serrano/prgm/project/bigloo/manuals/hash.texi                    @c
@c    ------------------------------------------------------------     @c
@c    Author      :  Manuel Serrano                                    @c
@c    Creation    :  Sat Feb 23 07:41:58 2002                          @c
@c    Last change :                                                    @c
@c    Copyright   :  2002 Manuel Serrano                               @c
@c    ------------------------------------------------------------     @c
@c    Hash tables                                                      @c
@c =================================================================== @c

@c ------------------------------------------------------------------- @c
@c    The hash tables                                                  @c
@c ------------------------------------------------------------------- @c
@node Hash Tables, System Programming, Bit Manipulation, Standard Library
@section Hash Tables

@menu
* New Hash Tables::                 
* Deprecated Hash Tables::                 
@end menu

@c -- Hash tables ---------------------------------------------------- @c
@node New Hash Tables, Deprecated Hash Tables, , Hash Tables
@comment  node-name,  next,  previous,  up
@subsection Hash tables
@cindex hash tables

Bigloo offers hash tables. Here are described functions which define
and use them.

@deffn {bigloo procedure} make-hashtable [bucket-len] [max-bucket-len]
Defines an hash table for which the number of buckets is @var{bucket-len}.
The variable @var{max-bucket-len} specify when the table should be
resized. If provided, these two values have to be exact integers greater or
equal to 1. Normally you could ignore @var{bucket-len} and @var{max-bucket-len}
arguments and call @code{make-hashtable} with no argument at all.
@end deffn

@deffn {bigloo procedure} hashtable? obj
Returns @code{#t} if @var{obj} is an hash table, constructed by
@code{make-hashtable}.
@end deffn

@deffn {bigloo procedure} hashtable-size table
Returns the number of entries contained in @var{table}.
@end deffn

@deffn {bigloo procedure} hashtable-get table key
Returns the entry whose key is @var{key} in @var{table}. If not entry
is found @code{#f} is returned.
@end deffn

@deffn {bigloo procedure} hashtable-put! table key obj
Puts @var{obj} in @var{table} under the key @var{key}. This function 
returns the object bound in the table. If there was an object 
@var{obj-old} already in the table with the same key as @var{obj}, 
this function returns @var{obj-old}; otherwise it returns @var{obj}.
@end deffn

@deffn {bigloo procedure} hashtable-remove! table key
Removes the object associated to @var{key} from @var{table}, 
returning @code{#t} if such object
was bound in table and @code{#f} otherwise.
@end deffn

@deffn {bigloo procedure} hashtable-update! table key update-fun init-value
If key is already in table, the new value is calculated by
@code{(update-fun current-value)}. Otherwise the @var{table} is extended
by an entry linking key and @code{init-value}.
@end deffn

@deffn {bigloo procedure} hashtable->vector table
@deffnx {bigloo procedure} hashtable->list table
Convert a hash table @var{table} to a vector or to a list.
@end deffn

@deffn {bigloo procedure} hashtable-for-each table fun
Applies @var{fun} to each of the keys and elements of @var{table} 
(no order is specified). In consequence, @var{fun} must be a procedure
of two arguments. The first one is a key and the second one, an
associated object.
@end deffn

Here is an example of hash table.

@smalllisp
(define *table* (make-hashtable))

(hashtable-put! *table* "toto" "tutu")
(hashtable-put! *table* "tata" "titi")
(hashtable-put! *table* "titi" 5)
(hashtable-put! *table* "tutu" 'tutu)
(hashtable-put! *table* 'foo 'foo)

(print (hashtable-get *table* "toto"))
   @print{} "tutu"
(print (hashtable-get *table* 'foo))
   @print{} 'foo
(print (hashtable-get *table* 'bar))
   @print{} #f

(hashtable-for-each *table* (lambda (key obj) (print (cons key obj))))
   @print{} ("toto" . "tutu")
      ("tata" . "titi")
      ("titi" . 5)
      ("tutu" . TUTU)
      (foo . foo)
@end smalllisp

@deffn {bigloo generic} object-hashnumber object
This generic function computes a hash number of the instance @var{object}.

Example:
@smalllisp
(define-method (object-hashnumber pt::point)
   (with-access::point pt (x y)
      (+fx (*fx x 10) y)))
@end smalllisp
@end deffn

@c -- Hash tables ---------------------------------------------------- @c
@node  Deprecated Hash Tables,  , New Hash Tables, Hash Tables
@comment  node-name,  next,  previous,  up
@subsection Deprecated Hash tables
@cindex hash tables

Bigloo offers hash tables. Here are described functions which define
and use them.

@deffn {bigloo procedure} make-hash-table ms nb gk eq [is]
Defines an hash table of maximum length @var{ms}. If
@var{is} is provided, it sets the initial table size. The
formal @var{nb} is a function which, if applied to a
@var{key}, has to return an integer bound in interval
[@var{0}..@var{ms}]. The formal @var{gk}
is a function which, if applied to an object, returns its
key. For example, the identity is a good candidate for integers,
strings, symbols, etc. The last formal @var{eq} is a
equivalence predicate which is used when searching for an entry in
the table.
@end deffn

@deffn {bigloo procedure} hash-table? obj
Returns @code{#t} if @var{obj} is an hash table.
@end deffn

@deffn {bigloo procedure} hash-table-nb-entry table
Returns the number of entries contained in @var{table}.
@end deffn

@deffn {bigloo procedure} get-hash key table
Returns the entry whose key is @var{key} in @var{table}. If not entry
is found @code{#f} is returned.
@end deffn

@deffn {bigloo procedure} put-hash! obj table
Puts @var{obj} in @var{table}. This function returns the object bound
in the table. If there was an object @var{obj-old} already in the
table with the same key as @var{obj}, this function returns @var{obj-old}; o
therwise it returns @var{obj}.
@end deffn

@deffn {bigloo procedure} rem-obj-hash! obj table
Removes @var{obj} from @var{table}, returning @code{#t} if such object
was bound in table and @code{#f} otherwise.
@end deffn

@deffn {bigloo procedure} rem-key-hash! key table
Removes an object associated with @var{key} in 
@var{table}, returning @code{#t} if such an object was bound 
in table and @code{#f} otherwise.
@end deffn

@deffn {bigloo procedure} for-each-hash fun table
Applies @var{fun} to each of the elements of @var{table} (no order 
is specified).
@end deffn

Some functions compute hash numbers from Scheme objects:

@deffn {bigloo procedure} string->0..255 string
@deffnx {bigloo procedure} string->0..2^x-1 string power
The formal @var{power} has to be a power of 2 between 1 and 16.
@end deffn

@deffn {bigloo procedure} int->0..255 int
@deffnx {bigloo procedure} int->0..2^x-1 int power
@deffnx {bigloo procedure} obj->0..255 obj
@deffnx {bigloo procedure} obj->0..2^x-1 obj power
@end deffn

Here is an example of hash table that contains pairs:

@smalllisp
(define *table* 
   (make-hash-table 1024
	            (lambda (o) (string->0..2^x-1 o 10))
		    (lambda (x) (car x))
		    string=?
		    64))

(let ((cell1 (cons "toto" "tutu"))
      (cell2 (cons "tata" "titi"))
      (cell3 (cons "titi" 5))
      (cell4 (cons "tutu" 'tutu)))
   (put-hash! cell1 *table*)
   (put-hash! cell2 *table*)
   (put-hash! cell3 *table*)
   (put-hash! cell4 *table*))

(print (cdr (get-hash "toto" *table*))) 
   @print{} "tutu"

(for-each-hash print *table*)
   @print{} ("toto" . "tutu")
      ("tata" . "titi")
      ("titi" . 5)
      ("tutu" . TUTU)
@end smalllisp

