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

<!--#set var="isip_page_title" value="ColorHash" -->
<?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/ColorHash/ColorHash.h"> ColorHash &lt;TObject&gt; </a></b>

<br><br>

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

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

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

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

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

<blockquote>
<pre>
// declare the graph arc object
//
ColorHash&lt;Char&gt; hash;
GraphVertex&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>

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

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

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

for more details.

<br><br>

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

<ul>
  <li> <a href="../Node/index.html"> Node</a>       
  <li> <a href="../DiGraph/index.html"> DiGraph</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/ColorHash/ColorHash.h&constant=CLASS_NAME">static const String CLASS_NAME = L"ColorHash";</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/ColorHash/ColorHash.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/ColorHash/ColorHash.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 ColorHash template:
       
       <pre>typedef ColorHash&lt;TObject&gt; CHASH;</pre>

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

  <li> debugging parameters:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.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 ColorHashDiagnose.h in order to avoid
       issues with the preprocessing of the diagnose code
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.h&method=name">static const String& name();</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHashDiagnose.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/ColorHash/ColorHash.h&method=setDebug">static boolean setDebug(Integral::DEBUG level);</a></pre>       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.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/ColorHash/ColorHash.h&method=destructor">~ColorHash();</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.h&method=default+constructor">ColorHash();</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.h&method=copy+constructor">ColorHash(const CHASH& arg);</a></pre>
       
  <li> assign methods:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.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/ColorHash/ColorHash.h&method=operator%3D">ColorHash& operator=(const ColorHash& arg);</a></pre>

  <li> equality methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.h&method=eq">boolean eq(const ColorHash& 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/ColorHash/ColorHash.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/ColorHash/ColorHash.h&method=getNumItems">long getNumItems() const;</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.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/ColorHash/ColorHash.h&method=get&instance=0">Integral::COLOR get(const GraphVertex&lt;TObject&gt;* key);</a></pre>       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.h&method=get&instance=1">const Integral::COLOR get(const GraphVertex&lt;TObject&gt;* key) const ;</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.h&method=set">boolean set(const GraphVertex&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/ColorHash/ColorHash.h&method=insert">boolean insert(const GraphVertex&lt;TObject&gt;* key, Integral::COLOR value);</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.h&method=remove">boolean remove(const GraphVertex&lt;TObject&gt;* key);</a></pre>

  <li> hash table insert and remove methods

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.h&method=containsKey">boolean containsKey(const GraphVertex<TObject>* key) const;</a></pre>
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/dstr/ColorHash/ColorHash.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 ColorHash:
       
       <pre>
// declare a hash table
//
ColorHash&lt;Char&gt hash;
  
// create some data
//
GraphVertex&lt;Char&gt vert_01;
GraphVertex&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 ColorHash class is a support class for the
       <a href="../DiGraph/index.html">Graph</a> classes.

       <br><br>

  <li> This class has two inner classes -- GVKey and GVColor. The
       GVKey class is a class to hold a GraphVertex pointer and allow hashing
       from that pointer. The GVColor 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 ColorHash uses the
       basic GraphVertex* and Integral::COLOR datatypes.
</ul>

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