<?php $isip_window_title = "ISIP Homepage"; ?>
<?php include("/data/isip/www/templates/documentation/header/header.html"); ?>

<!--#set var="isip_page_title" value="BiColorHash" -->
<?php include("/data/isip/www/templates/documentation/body/index_class.html"); ?>
<?php include("/data/isip/www/templates/documentation/body/bar.html"); ?>


<a name="name">
<b>name: <a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h"> BiColorHash &lt;TObject&gt; </a></b>

<br><br>

<a name="synopsis">
<b>synopsis:</b>
<br><br>

<blockquote>
<pre>
g++ [flags ...] file ...

#include &lt;BiColorHash.h&gt;;

Integral::COLOR get(const BiGraphVertex&lt;TObject&gt;* key);
boolean set(const BiGraphVertex&lt;TObject&gt;* key, Integral::COLOR value);
boolean insert(const BiGraphVertex&lt;TObject&gt;* key, Integral::COLOR value);
boolean remove(const BiGraphVertex&lt;TObject&gt;* key);
</pre>
</blockquote>

<a name="quick_start">
<b>quick start:</b>

<blockquote>
<pre>
// declare the graph arc object
//
BiColorHash&lt;Char&gt; hash;
BiGraphVertex&lt;Char&gt; vertex;

// insert a vertex into the hash table and associate a color with it
//
hash.insert(&vertex, Integral::WHITE);

if (hash.get(&vertex) != Integral::WHITE) {
  return Error::handle(name(), L"insert/get", Error::TEST,
                              __FILE__, __LINE__);    
}

// change the color associated with the vertex
//
hash.set(&vertex, Integral::BLUE);

if (hash.get(&vertex) != Integral::BLUE) {
  return Error::handle(name(), L"insert/set", Error::TEST,
                              __FILE__, __LINE__);    
}

// remove the vertex from the graph
//
hash.remove(&vertex);

// the hash table should be empty
//
if (!hash.isEmpty()) {
  return Error::handle(name(), L"isEmpty", Error::TEST,
         	 __FILE__, __LINE__);
}
</pre>
</blockquote>

<b>description:</b>
<br><br>

BiColorHash is a wrapper class whose main function is to create a one-to-one
mapping between a graph vertex pointer and the corresponding color of the
vertex. The main reason for doing this is to mark a node in order to
indicate that the vertex has been previously visited. Marking vertices
is essential when you are dealing with search and sort algorithms related
to graphs. However, we don't want all vertices to have to use color,
since this will waste some previous memory space. So we provide this
as an auxiliary class that can be used by those graphs that need it.

<br><br>

For a good reference on the color problem and its use in graphs,
see:

<ul>
  K. H. Rosen,
  <i>Discrete Mathematics and its Applications (Fourth Edition)</i>,
  McGraw-Hill, Columbus, Ohio, USA, 1999.
</ul>

An interesting on-line resource is located at:

<ul>
  C. Caldwell, "Graph Theory Tutorials,"
  <a href="http://www.utm.edu/departments/math/graph/" target="_top">
  http://www.utm.edu/departments/math/graph/</a>,
  Department of Mathematics and Statistics,
  University of Tennessee, Martin, Tennessee, USA, December 2000.
</ul>

as well as:

<ul>
  M. Beard, "The Four Color Theorem,"
  <a href="http://www.wvmccd.cc.ca.us/mc/Depts/Math/beard2" target="_top">
  http://www.wvmccd.cc.ca.us/mc/Depts/Math/beard2</a>,
  Department of Mathematics,
  Mission College, Santa Clara, California, USA, December 2000.
</ul>

BiColorHash is one of several classes that contribute to our graph
manipulation capabilities in the IFCs. See

<a href="../BiGraph/index.html">BiGraph</a>

for more details.

<br><br>

<b>dependencies:</b>
<br><br>

<ul>
  <li> <a href="../Node/index.html"> Node</a>       
  <li> <a href="../BiGraph/index.html"> BiGraph</a>
</ul>

<b>public constants:</b>
<br><br>

<ul>
  <li> define the class name:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&constant=CLASS_NAME">static const String CLASS_NAME = L"BiColorHash";</a></pre>
       
  <li> define inner class names: these are typically hidden from the user.
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&constant=GV_KEY_CLASS_NAME">static const String GV_KEY_CLASS_NAME = L"GVKey";</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&constant=GV_COLOR_CLASS_NAME">static const String GV_COLOR_CLASS_NAME = L"GVColor";</a></pre>
</ul>

<b>error codes:</b>
<br><br>

<ul>
  <li> none.
</ul>
       
<b>protected data:</b>
<br><br>

<ul>
  <li> define a typedef for the BiColorHash template:
       
       <pre>typedef BiColorHash&lt;TObject&gt; CHASH;</pre>

  <li> define the internal hash table instance:
       
       <pre>HashTable&lt;BiGVKey&lt;TObject&gt;, BiGVColor&gt;* hash_d;</pre>

  <li> debugging parameters:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&static=debug_level_d">static Integral::DEBUG debug_level_d;</a></pre>
</ul>

<b>required public methods:</b>
<br><br>

<ul>
  <li> static methods: diagnose method is moved outside the class
       header file and defined in the BiColorHashDiagnose.h in order to avoid
       issues with the preprocessing of the diagnose code
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=name">static const String& name();</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHashDiagnose.h&method=diagnose">static boolean diagnose(Integral::DEBUG debug_level);</a></pre>
       
  <li> debug methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=setDebug">static boolean setDebug(Integral::DEBUG level);</a></pre>       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=debug">boolean debug(const unichar* message);</a></pre>

  <li> destructor/constructor(s):
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=destructor">~BiColorHash();</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=default+constructor">BiColorHash();</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=copy+constructor">BiColorHash(const CHASH& arg);</a></pre>
       
  <li> assign methods:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=assign&instance=0">boolean assign(const CHASH& arg);</a></pre>

  <li> method: operator=
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=operator%3D">BiColorHash& operator=(const BiColorHash& arg);</a></pre>

  <li> equality methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=eq">boolean eq(const BiColorHash& arg) const;</a></pre>
       
  <li> i/o methods:

       <pre> i/o methods are not defined for this class.</pre>
       
  <li> memory management methods:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=clear">boolean clear(Integral::CMODE cmode = Integral::DEF_CMODE);</a></pre>
</ul>

<b>class-specific public methods:</b>
<br><br>

<ul>
  <li> hash table property methods
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=getNumItems">long getNumItems() const;</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=isEmpty">boolean isEmpty() const;</a></pre>

  <li> hash table get and set methods

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=get&instance=0">Integral::COLOR get(const BiGraphVertex&lt;TObject&gt;* key);</a></pre>       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=get&instance=1">const Integral::COLOR get(const BiGraphVertex&lt;TObject&gt;* key) const ;</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=set">boolean set(const BiGraphVertex&lt&TObject&gt;* key, Integral::COLOR value);</a></pre>              

  <li> hash table insert and remove methods

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=insert">boolean insert(const BiGraphVertex&lt;TObject&gt;* key, Integral::COLOR value);</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=remove">boolean remove(const BiGraphVertex&lt;TObject&gt;* key);</a></pre>

  <li> hash table insert and remove methods

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=containsKey">boolean containsKey(const BiGraphVertex<TObject>* key) const;</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/BiColorHash/BiColorHash.h&method=containsValue">boolean containsValue(const Integral::COLOR value) const;</a></pre>              
</ul>

<a name="private">
<b>private methods:</b>
<br><br>

<ul>
  <li> none.
</ul>

<b>examples:</b>
<br><br>

<ul>
  <li> This example shows how insert, remove, get and set values using a BiColorHash:
       
       <pre>
// declare a hash table
//
BiColorHash&lt;Char&gt hash;
  
// create some data
//
BiGraphVertex&lt;Char&gt vert_01;
BiGraphVertex&lt;Char&gt vert_02;

// insert vertices into the hash and associate colors with them
//
hash.insert(&vert_01, Integral::WHITE);
hash.insert(&vert_02, Integral::GREY);

if (hash.get(&vert_01) != Integral::WHITE) {
    return Error::handle(name(), L"insert/get", Error::TEST,
			 __FILE__, __LINE__);    
}
if (hash.get(&vert_02) != Integral::GREY) {
    return Error::handle(name(), L"insert/get", Error::TEST,
			 __FILE__, __LINE__);    
}

// remove the vertices from the graph
//
hash.remove(&vert_01);
hash.remove(&vert_02);

if (hash.containsKey(&vert_01)) {
    return Error::handle(name(), L"containsKey", Error::TEST,
			 __FILE__, __LINE__);
}
if (hash.containsValue(Integral::GREY)) {
    return Error::handle(name(), L"containsValue", Error::TEST,
			 __FILE__, __LINE__);
}</pre>       
</ul>

<b>notes:</b>
<br><br>

<ul>
  <li> The BiColorHash class is a support class for the
       <a href="../DiGraph/index.html">Graph</a> classes.

       <br><br>

  <li> This class has two inner classes -- BiGVKey and BiGVColor. The
       BiGVKey class is a class to hold a BiGraphVertex pointer and allow hashing
       from that pointer. The BiGVColor class holds an Integral::COLOR
       value. These classes need to be defined since a HashTable can only be
       made between objects, but the public interface of BiColorHash uses the
       basic BiGraphVertex* and Integral::COLOR datatypes.
</ul>

<!--#include virtual="/hse/ies/templates/documentation/footer/footer.html" -->
