name: BiColorHash <TObject>

synopsis:

g++ [flags ...] file ...

#include <BiColorHash.h>;

Integral::COLOR get(const BiGraphVertex<TObject>* key);
boolean set(const BiGraphVertex<TObject>* key, Integral::COLOR value);
boolean insert(const BiGraphVertex<TObject>* key, Integral::COLOR value);
boolean remove(const BiGraphVertex<TObject>* key);

quick start:

// declare the graph arc object
//
BiColorHash<Char> hash;
BiGraphVertex<Char> 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__);
}

description:

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.

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

Discrete Mathematics and its Applications (Fourth Edition)

An interesting on-line resource is located at:

C. Caldwell, "Graph Theory Tutorials,"

http://www.utm.edu/departments/math/graph/

as well as:

http://www.wvmccd.cc.ca.us/mc/Depts/Math/beard2

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

dependencies:

public constants:

define the class name:

static const String CLASS_NAME = L"BiColorHash";

define inner class names: these are typically hidden from the user.

static const String GV_KEY_CLASS_NAME = L"GVKey";

static const String GV_COLOR_CLASS_NAME = L"GVColor";

error codes:

none.

protected data:

define a typedef for the BiColorHash template:
```
typedef BiColorHash<TObject> CHASH;
```

define the internal hash table instance:

HashTable<BiGVKey<TObject>, BiGVColor>* hash_d;

debugging parameters:
```
static Integral::DEBUG debug_level_d;
```

required public methods:

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
```
static const String& name();
```
```
static boolean diagnose(Integral::DEBUG debug_level);
```

debug methods:

static boolean setDebug(Integral::DEBUG level);

boolean debug(const unichar* message);

destructor/constructor(s):

~BiColorHash();

BiColorHash();

BiColorHash(const CHASH& arg);

assign methods:
```
boolean assign(const CHASH& arg);
```

method: operator=

BiColorHash& operator=(const BiColorHash& arg);

equality methods:

boolean eq(const BiColorHash& arg) const;

i/o methods:

 i/o methods are not defined for this class.

memory management methods:

boolean clear(Integral::CMODE cmode = Integral::DEF_CMODE);

class-specific public methods:

hash table property methods

long getNumItems() const;

boolean isEmpty() const;

hash table get and set methods

Integral::COLOR get(const BiGraphVertex<TObject>* key);

const Integral::COLOR get(const BiGraphVertex<TObject>* key) const ;

boolean set(const BiGraphVertex<&TObject>* key, Integral::COLOR value);

hash table insert and remove methods

boolean insert(const BiGraphVertex<TObject>* key, Integral::COLOR value);

boolean remove(const BiGraphVertex<TObject>* key);

hash table insert and remove methods

boolean containsKey(const BiGraphVertex* key) const;

boolean containsValue(const Integral::COLOR value) const;

private methods:

none.

examples:

This example shows how insert, remove, get and set values using a BiColorHash:

// declare a hash table
//
BiColorHash<Char> hash;
  
// create some data
//
BiGraphVertex<Char> vert_01;
BiGraphVertex<Char> 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__);
}

notes:

The BiColorHash class is a support class for the Graph classes.
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.