name: ColorHash <TObject>

synopsis:

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

#include <ColorHash.h>;

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

quick start:

// declare the graph arc object
//
ColorHash<Char> hash;
GraphVertex<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:

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.

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

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

dependencies:

public constants:

define the class name:

static const String CLASS_NAME = L"ColorHash";

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 ColorHash template:
```
typedef ColorHash<TObject> CHASH;
```

define the internal hash table instance:

HashTable<GVKey<TObject>, GVColor>* 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 ColorHashDiagnose.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):

~ColorHash();

ColorHash();

ColorHash(const CHASH& arg);

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

method: operator=

ColorHash& operator=(const ColorHash& arg);

equality methods:
```
boolean eq(const ColorHash& 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 GraphVertex<TObject>* key);

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

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

hash table insert and remove methods

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

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

hash table insert and remove methods

boolean containsKey(const GraphVertex* 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 ColorHash:

// declare a hash table
//
ColorHash<Char> hash;
  
// create some data
//
GraphVertex<Char> vert_01;
GraphVertex<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 ColorHash class is a support class for the Graph classes.
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.