updated docs - double_hash_hash_table

hashing/double_hash_hash_table.cpp

@@ -2,18 +2,13 @@
  * @file double_hash_hash_table.cpp
  * @author [achance6](https://github.com/achance6)
  * @author [Krishna Vedala](https://github.com/kvedala)
- * @brief
+ * @brief Storage mechanism using double-hashed keys.
+ * @note The implementation can be optimized by using OOP style.
  */
 #include <iostream>
 #include <memory>
-#include <string>
 #include <vector>
 
-using std::cin;
-using std::cout;
-using std::endl;
-using std::string;
-
 namespace {  // keep the code local to this file by assigning them to an unnamed
              // namespace
 
@@ -31,25 +26,42 @@ int tomb = -1;
 int size;
 bool rehashing;
 
-// Node that holds key
+/** Node object that holds key */
 struct Entry {
-    explicit Entry(int key = notPresent) : key(key) {}
-    int key;
+    explicit Entry(int key = notPresent) : key(key) {}  ///< constructor
+    int key;                                            ///< key value
 };
 
-// Hash a key
+/**
+ * @brief Hash a key. Uses the STL library's `std::hash()` function.
+ *
+ * @param key value to hash
+ * @return hash value of the key
+ */
 size_t hashFxn(int key) {
     std::hash<int> hash;
     return hash(key);
 }
 
-// Used for second hash function
+/**
+ * @brief Used for second hash function
+ *
+ * @param key key value to hash
+ * @return  hash value of the key
+ */
 size_t otherHashFxn(int key) {
     std::hash<int> hash;
     return 1 + (7 - (hash(key) % 7));
 }
 
-// Performs double hashing to resolve collisions
+/**
+ * @brief Performs double hashing to resolve collisions
+ *
+ * @param key key value to apply double-hash on
+ * @param searching `true` to check for conflicts
+ * @return Index of key when found
+ * @return new hash if no conflicts present
+ */
 int doubleHash(int key, bool searching) {
     int hash = static_cast<int>(hashFxn(key));
     int i = 0;
@@ -63,36 +75,42 @@ int doubleHash(int key, bool searching) {
                 return notPresent;
             }
             if (searchingProber(entry, key)) {
-                cout << "Found key!" << endl;
+                std::cout << "Found key!" << std::endl;
                 return index;
             }
-            cout << "Found tombstone or equal hash, checking next" << endl;
+            std::cout << "Found tombstone or equal hash, checking next"
+                      << std::endl;
             i++;
         } else {
             if (putProber(entry, key)) {
                 if (!rehashing) {
-                    cout << "Spot found!" << endl;
+                    std::cout << "Spot found!" << std::endl;
                 }
                 return index;
             }
             if (!rehashing) {
-                cout << "Spot taken, looking at next (next index:"
-                     << " "
-                     << static_cast<int>(hash + (i * otherHashFxn(key))) %
-                            totalSize
-                     << ")" << endl;
+                std::cout << "Spot taken, looking at next (next index:"
+                          << " "
+                          << static_cast<int>(hash + (i * otherHashFxn(key))) %
+                                 totalSize
+                          << ")" << std::endl;
             }
             i++;
         }
         if (i == totalSize * 100) {
-            cout << "DoubleHash probe failed" << endl;
+            std::cout << "DoubleHash probe failed" << std::endl;
             return notPresent;
         }
     } while (entry.key != notPresent);
     return notPresent;
 }
 
-// Finds empty spot
+/** Finds empty spot in a vector
+ * @param entry vector to search in
+ * @param key key to search for
+ * @returns `true` if key is not present or is a `toumb`
+ * @returns `false` is already occupied
+ */
 bool putProber(Entry entry, int key) {
     if (entry.key == notPresent || entry.key == tomb) {
         return true;
@@ -100,7 +118,12 @@ bool putProber(Entry entry, int key) {
     return false;
 }
 
-// Looks for a matching key
+/** Looks for a matching key
+ * @param entry vector to search in
+ * @param key key value to search
+ * @returns `true` if found
+ * @returns `false` if not found
+ */
 bool searchingProber(Entry entry, int key) {
     if (entry.key == key) {
         return true;
@@ -108,23 +131,27 @@ bool searchingProber(Entry entry, int key) {
     return false;
 }
 
-// Displays the table
+/** Displays the table
+ * @returns None
+ */
 void display() {
     for (int i = 0; i < totalSize; i++) {
         if (table[i].key == notPresent) {
-            cout << " Empty ";
+            std::cout << " Empty ";
         } else if (table[i].key == tomb) {
-            cout << " Tomb ";
+            std::cout << " Tomb ";
         } else {
-            cout << " ";
-            cout << table[i].key;
-            cout << " ";
+            std::cout << " ";
+            std::cout << table[i].key;
+            std::cout << " ";
         }
     }
-    cout << endl;
+    std::cout << std::endl;
 }
 
-// Rehashes the table into a bigger table
+/** Rehashes the table into a bigger table
+ * @returns None
+ */
 void rehash() {
     // Necessary so wall of add info isn't printed all at once
     rehashing = true;
@@ -143,10 +170,12 @@ void rehash() {
     // oldTable.reset();
 
     rehashing = false;
-    cout << "Table was rehashed, new size is: " << totalSize << endl;
+    std::cout << "Table was rehashed, new size is: " << totalSize << std::endl;
 }
 
-// Checks for load factor here
+/** Checks for load factor here
+ * @param key key value to add to the table
+ */
 void add(int key) {
     // auto* entry = new Entry();
     // entry->key = key;
@@ -158,86 +187,94 @@ void add(int key) {
     }
 }
 
-// Removes key. Leaves tombstone upon removal.
+/** Removes key. Leaves tombstone upon removal.
+ * @param key key value to remove
+ */
 void remove(int key) {
     int index = doubleHash(key, true);
     if (index == notPresent) {
-        cout << "key not found" << endl;
+        std::cout << "key not found" << std::endl;
     }
     table[index].key = tomb;
-    cout << "Removal successful, leaving tombstone" << endl;
+    std::cout << "Removal successful, leaving tombstone" << std::endl;
     size--;
 }
 
-// Information about the adding process
+/** Information about the adding process
+ * @param key key value to add to table
+ */
 void addInfo(int key) {
-    cout << "Initial table: ";
+    std::cout << "Initial table: ";
     display();
-    cout << endl;
-    cout << "hash of " << key << " is " << hashFxn(key) << " % " << totalSize
-         << " == " << hashFxn(key) % totalSize;
-    cout << endl;
+    std::cout << std::endl;
+    std::cout << "hash of " << key << " is " << hashFxn(key) << " % "
+              << totalSize << " == " << hashFxn(key) % totalSize;
+    std::cout << std::endl;
     add(key);
-    cout << "New table: ";
+    std::cout << "New table: ";
     display();
 }
 
-// Information about removal process
+/** Information about removal process
+ * @param key key value to remove from table
+ */
 void removalInfo(int key) {
-    cout << "Initial table: ";
+    std::cout << "Initial table: ";
     display();
-    cout << endl;
-    cout << "hash of " << key << " is " << hashFxn(key) << " % " << totalSize
-         << " == " << hashFxn(key) % totalSize;
-    cout << endl;
+    std::cout << std::endl;
+    std::cout << "hash of " << key << " is " << hashFxn(key) << " % "
+              << totalSize << " == " << hashFxn(key) % totalSize;
+    std::cout << std::endl;
     remove(key);
-    cout << "New table: ";
+    std::cout << "New table: ";
     display();
 }
 }  // namespace
 
-// I/O
+/** Main program
+ * @returns None
+ */
 int main() {
     int cmd = 0, hash = 0, key = 0;
-    cout << "Enter the initial size of Hash Table. = ";
-    cin >> totalSize;
+    std::cout << "Enter the initial size of Hash Table. = ";
+    std::cin >> totalSize;
     table = std::vector<Entry>(totalSize);
     bool loop = true;
     while (loop) {
         system("pause");
-        cout << endl;
-        cout << "PLEASE CHOOSE -" << endl;
-        cout << "1. Add key. (Numeric only)" << endl;
-        cout << "2. Remove key." << endl;
-        cout << "3. Find key." << endl;
-        cout << "4. Generate Hash. (Numeric only)" << endl;
-        cout << "5. Display Hash table." << endl;
-        cout << "6. Exit." << endl;
-        cin >> cmd;
+        std::cout << std::endl;
+        std::cout << "PLEASE CHOOSE -" << std::endl;
+        std::cout << "1. Add key. (Numeric only)" << std::endl;
+        std::cout << "2. Remove key." << std::endl;
+        std::cout << "3. Find key." << std::endl;
+        std::cout << "4. Generate Hash. (Numeric only)" << std::endl;
+        std::cout << "5. Display Hash table." << std::endl;
+        std::cout << "6. Exit." << std::endl;
+        std::cin >> cmd;
         switch (cmd) {
             case 1:
-                cout << "Enter key to add = ";
-                cin >> key;
+                std::cout << "Enter key to add = ";
+                std::cin >> key;
                 addInfo(key);
                 break;
             case 2:
-                cout << "Enter key to remove = ";
-                cin >> key;
+                std::cout << "Enter key to remove = ";
+                std::cin >> key;
                 removalInfo(key);
                 break;
             case 3: {
-                cout << "Enter key to search = ";
-                cin >> key;
+                std::cout << "Enter key to search = ";
+                std::cin >> key;
                 Entry entry = table[doubleHash(key, true)];
                 if (entry.key == notPresent) {
-                    cout << "Key not present";
+                    std::cout << "Key not present";
                 }
                 break;
             }
             case 4:
-                cout << "Enter element to generate hash = ";
-                cin >> key;
-                cout << "Hash of " << key << " is = " << hashFxn(key);
+                std::cout << "Enter element to generate hash = ";
+                std::cin >> key;
+                std::cout << "Hash of " << key << " is = " << hashFxn(key);
                 break;
             case 5:
                 display();
@@ -247,7 +284,7 @@ int main() {
                 break;
                 // delete[] table;
         }
-        cout << endl;
+        std::cout << std::endl;
     }
     return 0;
 }