%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  hash_table.tex       LiDIA documentation
%%
%%  This file contains the documentation of the hash table class
%%
%%  Copyright   (c)   1996   by  LiDIA-Group 
%%
%%  Author:  Michael J. Jacobson, Jr.
%%

\def\htable{hash\_table\TEMPL{T} }

\markright{\BF{hash\_table}}
\begin{lidia_man}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NAME
	\BF{hash\_table\TEMPL{T} } \DOTFILL parameterized hash table class

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ABSTRACT
	The class \BF{\htable} represents a hash table consisting of elements
	which are of some data type \BF{T}.  This base type is allowed to be
	either a built-in type or a class, and its only requirements are that
	the assignment operator \TT{=}, equality operator \TT{==},
	and input/output operators \TT{>>} and
	\TT{<<} are defined.  A function returning a key value for an instance
	of type \BF{T} must be defined by the user.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DESCRIPTION
	An instance of \BF{\htable} consists of an array of \MATH{n} linked
	lists whose elements each contain a pointer to an instance of type
	\BF{T}.  The collision resolution scheme is bucketing, i.e.,
	elements which hash to the same location are simply appended to the
	appropriate linked list (bucket).

	Before inserting elements into the hash table, it must be initialized
	with the member function \BF{initialize}.  The number of buckets in
	the table, \MATH{n},  will be set to the smallest prime number greater 
	than or equal to the parameter passed to \BF{initialize}.

	The elements are ordered according to some key function which is
	defined by the user.  This key function must have a prototype like
	\begin{center}
        \TT{bigint  get\_key (const T \& G)}.
	\end{center}
	The value returned by
	this function is reduced modulo \MATH{n} to give a valid hash value
	between \MATH{0} and \MATH{n-1}, where \MATH{n} is the number of
	buckets.  The key function must be set with the member function
	\BF{set\_key\_function}, and should not be changed after elements
	have been inserted into the table.  Note that equality of elements
	is determined using the \TT{==} operator corresponding to type
	\BF{T}, and that it is not necessary for equality of key values to 
	imply equality of elements.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\CONS

\fcode{ct }{\htable}{}{}
\fcode{dt }{\MATH{\SIM}\htable}{}{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\INIT

	Let \MATH{HT} be of type \BF{\htable}.  A \BF{\htable} must be
	initialized before use.

\fcode{void }{HT.initialize}{const lidia\_size\_t table\_size}{
	initializes a \BF{\htable} with \MATH{n} buckets, where \MATH{n} is
	the smallest prime number \MATH{\GEQ table\_size}.  Any subsequent
	calls to this function will cause the elements in \MATH{HT} to be 
	deleted, and the number of buckets to be reset.}
\fcode{void }{HT.set\_key\_function }{bigint (*get\_key) (const T \& G)}{
	sets the key function.  The parameter must be a pointer to a function
	which accepts one parameter of type \BF{T} and returns a \BF{bigint}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ASGN

	Let \MATH{HT} be of type \BF{\htable}.  The operator \TT{=} is
	overloaded.  For efficiency, the following function is also
	implemented:

\fcode{void }{HT.assign}{const \htable \& HT2}{
	\MATH{HT} is assigned a copy of \MATH{HT2}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ACCS

	Let \MATH{HT} be of type \BF{\htable}.


\cfcode{lidia\_size\_t }{HT.no\_of\_elements}{}{
	returns the number of elements currently contained in \MATH{HT}.}
\cfcode{lidia\_size\_t }{HT.no\_of\_buckets}{}{
	returns the number of buckets of \MATH{HT}.}
\fcode{void }{HT.remove}{const T \& G}{
	if \MATH{G} is in the table, it is removed.}
\fcode{void }{HT.empty}{}{
	deallocates all elements in \MATH{HT}.  The number of buckets 
	remains the same; to change this, reinitialize using \BF{initialize}.}
\cfcode{const T \&}{HT.last\_entry}{}{
	returns a constant reference to the last item added to the table.  If
	the table is empty, the \BF{error\_handler} will be evoked.}
\fcode{void }{HT.hash}{const T \& G}{
	adds the item \MATH{G} to the hash table.}
\fcode{T *}{HT.search}{const T \& G}{
	returns a pointer to the first occurrence of an element in \MATH{HT}
	that is equal to \MATH{G} according to the \TT{==} operator 
	corresponding to type \BF{T}.  If no such element exists, the NULL
	pointer is returned.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\IO

        Let \MATH{HT} be of type \BF{\htable}.
        The \BF{istream}  operator  \TT{>>}  and  the \BF{ostream}  operator
        \TT{<<} are overloaded.  The input of a \htable consists of \MATH{n}, a
	\BF{lidia\_size\_t} representing the number of buckets, \MATH{m},
	a second \BF{lidia\_size\_t} (on a separate line) representing
	the number of elements in the table, and exactly \MATH{m} values of 
	type \BF{T}, one per line.  The output consists of each non-empty
	bucket being displayed element by element, one bucket per line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
	indexed\_hash\_table\TEMPL{T}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%\BUGS

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NOTES
	\begin{itemize}
	\item   The base type \MATH{T} must have at least the following
	capabilities:
	  \begin{itemize}
	    \item the assignment--operator \TT{=},
	    \item the equality--operator \TT{==},
	    \item the input--operator \TT{>>}, and
	    \item the output--operator \TT{<<}.
	  \end{itemize}
	\item The enumeration of the buckets in a hash\_table starts with zero
	(like C)
	\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\EXAMPLES
\begin{verbatim}
#include <LiDIA/hash_table.h>

bigint
ikey(const int & G) { return bigint(G); }

main()
{
  hash_table < int > HT;
  int i,x,*y;

  HT.initialize(100);
  HT.set_key_function(&ikey);

  cout << "#buckets = " << HT.no_of_buckets() << "\n";
  cout << "current size = " << HT.no_of_elements() << "\n\n";

  for (i=0; i<4; ++i) {
    cout << "Enter an integer: ";
    cin >> x;
    HT.hash(x);
  }
  
  cout << "\ncurrent size = " << HT.no_of_elements() << "\n";
  x = HT.last_entry();
  cout << "last entry = " << x << "\n";
  y = HT.search(x);
  if (y)
    cout << "search succeeded!  Last entry is in the table.\n";
  else
    cout << "search failed!  Please report this bug!\n";
  cout << "Contents of HT:\n";
  cout << HT << "\n";
}
\end{verbatim}

example:

\begin{verbatim}
#buckets = 101
current size = 0

Enter an integer: 5
Enter an integer: 12345
Enter an integer: -999
Enter an integer: 207

current size = 4
last entry = 207
search succeeded!  Last entry is in the table.
Contents of HT:
[5] : 5 : 207
[11] : -999
[23] : 12345
\end{verbatim}
	
	For further examples please refer to \\
	\TT{LiDIA/src/templates/hash\_table/hash\_table\_appl.c}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR
	Michael J. Jacobson, Jr.

\end{lidia_man}
