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

\def\htable{hash\_table\TEMPL{T} }
\def\ihtable{indexed\_hash\_table\TEMPL{T} }

\markright{\BF{indexed\_hash\_table}}
\begin{lidia_man}

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

\NAME
	\BF{indexed\_hash\_table\TEMPL{T}} \DOTFILL hash table with sequential
	access capability

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

\ABSTRACT
	The class \BF{\ihtable} represents a hash table consisting of elements
	which are of some data type \BF{T} in exactly the same way as the class
	\BF{\htable}.  However, this class also allows for access to the 
	elements in the table by index, i.e., a regular sequential table.

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

\DESCRIPTION
	An instance of a \BF{\ihtable} consists of a \BF{\htable} together 
	with a list of pointers to elements in the \BF{\htable}.  The
	initialization of the table and definition of the key function 
	work the same as in the class \BF{\htable}.
	
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\CONS

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

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

\INIT

	Let \MATH{IHT} be of type \BF{\ihtable}.  The initialization function
	and key setting function are exactly the same as those of the class
	\BF{\htable}.

\fcode{void }{IHT.initialize}{const lidia\_size\_t table\_size}{}
\fcode{void }{IHT.set\_key\_function }{bigint (*get\_key) (const T \& G)}{}

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

\ASGN

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

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

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

\ACCS

	Let \MATH{IHT} be of type \BF{\ihtable}.  The following functions
	are exactly the same as those of the class \BF{\htable}.

\cfcode{lidia\_size\_t }{IHT.no\_of\_buckets}{}{}
\cfcode{lidia\_size\_t }{IHT.no\_of\_elements}{}{}
\fcode{void }{IHT.remove}{const T \& G}{}
\fcode{void }{IHT.empty}{}{}
\cfcode{const T \&}{IHT.last\_entry}{}{}
\fcode{void }{IHT.hash}{const T \& G}{}
\fcode{T *}{IHT.search}{const T \& G}{}

	The following functions are specific to the class \BF{\ihtable}, and
	are related to the sequential access capability.

\cfcode{const T \& }{operator[]}{lidia\_size\_t i}{
	returns a constant reference to element \MATH{i} in the hash table
	(zero denotes the first element).  If \MATH{i} is greater than or
	equal to the number of elements in the table or less than \MATH{0},
	the \BF{error\_handler} will be evoked.}
\cfcode{const T \& }{IHT.member}{lidia\_size\_t i}{
	returns a constant reference to element \MATH{i} in the hash table
	(zero denotes the first element).  If \MATH{i} is greater than or
	equal to the number of elements in the table or less than \MATH{0},
	the \BF{error\_handler} will be evoked.}
\fcode{void }{IHT.remove\_from}{const lidia\_size\_t i}{
	deletes element \MATH{i} from the hash table.  If \MATH{i} is greater
	than or equal to the number of elements in the table or less than
	\MATH{0}, the \BF{error\_handler} will be evoked.}

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

\IO

        Let \MATH{IHT} be of type \BF{\ihtable}.
        The \BF{istream}  operator  \TT{>>}  and  the \BF{ostream}  operator
        \TT{<<} are overloaded.  Input works in the same way as \BF{\htable}.
	Output is done either sequentially, each element in the table printed
	sequentially one element per line, or in the same way as the class
	\BF{\htable}.  The following function may be used to set the
	output style for a particular instance of \BF{\ihtable}.

\fcode{void }{IHT.output\_style}{const int style}{
	sets the output style for \MATH{IHT}.  If \MATH{style \EQ 0}, 
	sequential output will be used.  If \MATH{style \EQ 1}, output will
	be done in the same style as \BF{\htable}.  The default is
	sequential output.}

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

\SEEALSO
	\htable

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

%\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 and the elements both start with
	zero (like C)
	\end{itemize}

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

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

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

main()
{
  indexed_hash_table < int > IHT;
  int i,x,*y;

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

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

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

  cout << "\nsequential access:\n";
  for (i=0; i<3; ++i)
    cout << "element " << i << " = " << IHT[i] << "\n";


  cout << "\nContents of IHT:\n";
  cout << IHT << "\n";

  IHT.output_style(1);
  cout << "\nAs regular hash table:\n";
  cout << IHT << "\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.

sequential access:
element 0 = 5
element 1 = 12345
element 2 = -999

Contents of IHT:
0: 5
1: 12345
2: -999
3: 207


As regular hash table:
[5] : 5 : 207
[11] : -999
[23] : 12345
\end{verbatim}
	
	For further examples please refer to \\
	\TT{LiDIA/src/templates/hash\_table/indexed\_hash\_table\_appl.c}.

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

\AUTHOR
	Michael J. Jacobson, Jr.

\end{lidia_man}
