From ded105c539029671e6500b6c10d4bd7e5462314a Mon Sep 17 00:00:00 2001
From: Mark Olesen <Mark.Olesen@esi-group.com>
Date: Sat, 29 Apr 2017 12:27:11 +0200
Subject: [PATCH] STYLE: HashTable documentation

- explicitly mention the value-initialized status for the operator().
  This means that the following code will properly use an initialized
  zero.

      HashTable<label> regionCount;

      if (...)
         regionCount("region1")++;

      ... and also this;

      if (regionCount("something") > 0)
      {
          ...
      }

  Note that the OpenFOAM HashTable uses operator[] to provide read and
  write access to *existing* entries and will provoke a FatalError if
  the entry does not exist.

  The operator() provides write access to *existing* entries or will
  create the new entry as required.
  The STL hashes use operator[] for this purpose.
---
 applications/test/HashSet/Test-hashSet.C      |  9 ++++++++-
 applications/test/pTraits/Test-pTraits.C      |  9 +++++++++
 .../containers/HashTables/HashSet/HashSet.H   |  4 ++--
 .../HashTables/HashTable/HashTable.C          |  4 ++--
 .../HashTables/HashTable/HashTable.H          | 20 ++++++++++++-------
 5 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/applications/test/HashSet/Test-hashSet.C b/applications/test/HashSet/Test-hashSet.C
index dcfa0aec7a..3eea9b4123 100644
--- a/applications/test/HashSet/Test-hashSet.C
+++ b/applications/test/HashSet/Test-hashSet.C
@@ -28,6 +28,7 @@ Description
 #include "hashedWordList.H"
 #include "HashSet.H"
 #include "Map.H"
+#include "labelPairHashes.H"
 
 using namespace Foam;
 
@@ -122,7 +123,6 @@ int main(int argc, char *argv[])
         << (wordHashSet(setA) | wordHashSet(tableA) | wordHashSet(tableB))
         << nl;
 
-
     labelHashSet setB
     {
         1, 11, 42
@@ -130,6 +130,13 @@ int main(int argc, char *argv[])
 
     Info<< "setB : " << setB << endl;
 
+    labelPair pair(12, 15);
+    setB.set(pair);
+
+    Info<< "setB : " << setB << endl;
+    setB.unset(pair);
+
+
     labelHashSet setC(1);
     setC.insert(2008);
     setC.insert(1984);
diff --git a/applications/test/pTraits/Test-pTraits.C b/applications/test/pTraits/Test-pTraits.C
index 548661573d..a914911d29 100644
--- a/applications/test/pTraits/Test-pTraits.C
+++ b/applications/test/pTraits/Test-pTraits.C
@@ -51,6 +51,9 @@ void printTraits(const pTraits<T>& p)
 }
 
 
+#pragma GCC diagnostic warning "-Wmaybe-uninitialized"
+#pragma GCC diagnostic warning "-Wuninitialized"
+
 int main()
 {
     printTraits<bool>();
@@ -71,6 +74,12 @@ int main()
 
     printTraits(pTraits<scalar>(3.14159));
 
+    label abc;
+    Info<< "unintialized primitive:"<< abc << endl;
+
+    label def = label();
+    Info<< "intialized primitive:"<< def << endl;
+
     Info<< "End\n" << endl;
 
     return 0;
diff --git a/src/OpenFOAM/containers/HashTables/HashSet/HashSet.H b/src/OpenFOAM/containers/HashTables/HashSet/HashSet.H
index 437ca74eb6..e6b0ad0c2e 100644
--- a/src/OpenFOAM/containers/HashTables/HashSet/HashSet.H
+++ b/src/OpenFOAM/containers/HashTables/HashSet/HashSet.H
@@ -86,7 +86,7 @@ public:
         HashSet(const UList<Key>& lst);
 
         //- Construct from an initializer list of Key
-        HashSet(std::initializer_list<Key>);
+        HashSet(std::initializer_list<Key> lst);
 
         //- Construct as copy
         HashSet(const HashSet<Key, Hash>& hs)
@@ -122,7 +122,7 @@ public:
             return HashTable<nil, Key, Hash>::insert(key, nil());
         }
 
-        //- Insert keys from a UList of Key
+        //- Insert keys from the list of Key
         //  Return the number of new elements inserted
         label insert(const UList<Key>& lst);
 
diff --git a/src/OpenFOAM/containers/HashTables/HashTable/HashTable.C b/src/OpenFOAM/containers/HashTables/HashTable/HashTable.C
index eebdde2519..ea9ca3cab6 100644
--- a/src/OpenFOAM/containers/HashTables/HashTable/HashTable.C
+++ b/src/OpenFOAM/containers/HashTables/HashTable/HashTable.C
@@ -431,7 +431,7 @@ Foam::label Foam::HashTable<T, Key, Hash>::erase
 template<class T, class Key, class Hash>
 void Foam::HashTable<T, Key, Hash>::resize(const label sz)
 {
-    label newSize = HashTableCore::canonicalSize(sz);
+    const label newSize = HashTableCore::canonicalSize(sz);
 
     if (newSize == tableSize_)
     {
@@ -452,7 +452,7 @@ void Foam::HashTable<T, Key, Hash>::resize(const label sz)
         tmpTable->insert(iter.key(), *iter);
     }
 
-    label oldSize = tableSize_;
+    const label oldSize = tableSize_;
     tableSize_ = tmpTable->tableSize_;
     tmpTable->tableSize_ = oldSize;
 
diff --git a/src/OpenFOAM/containers/HashTables/HashTable/HashTable.H b/src/OpenFOAM/containers/HashTables/HashTable/HashTable.H
index b2c048879b..4afacce573 100644
--- a/src/OpenFOAM/containers/HashTables/HashTable/HashTable.H
+++ b/src/OpenFOAM/containers/HashTables/HashTable/HashTable.H
@@ -126,7 +126,7 @@ class HashTable
 {
     // Private data type for table entries
 
-        //- Structure to hold a hashed entry with SLList for collisions
+        //- Structure to hold a hashed entry, with a SLList for collisions
         struct hashedEntry
         {
             //- The lookup key
@@ -139,7 +139,7 @@ class HashTable
             T obj_;
 
             //- Construct from key, next pointer and object
-            inline hashedEntry(const Key&, hashedEntry* next, const T&);
+            inline hashedEntry(const Key& key, hashedEntry* next, const T& obj);
 
 
         private:
@@ -169,7 +169,8 @@ class HashTable
         //  No checks for zero-sized tables.
         inline label hashKeyIndex(const Key& key) const;
 
-        //- Assign a new hashedEntry to a possibly already existing key
+        //- Assign a new hashedEntry to a possibly already existing key.
+        //  Return true if the new entry was set.
         bool set(const Key& key, const T& newEntry, const bool protect);
 
 
@@ -201,7 +202,7 @@ public:
         HashTable(const label size = 128);
 
         //- Construct from Istream
-        HashTable(Istream&, const label size = 128);
+        HashTable(Istream& is, const label size = 128);
 
         //- Construct as copy
         HashTable(const HashTable<T, Key, Hash>& ht);
@@ -254,9 +255,12 @@ public:
         // Edit
 
             //- Insert a new hashedEntry
+            //  Return true if the entry inserted, which means that it did
+            //  not previously exist in the table.
             inline bool insert(const Key& key, const T& newEntry);
 
-            //- Assign a new hashedEntry, overwriting existing entries
+            //- Assign a new hashedEntry, overwriting existing entries.
+            //  Returns true.
             inline bool set(const Key& key, const T& newEntry);
 
             //- Erase a hashedEntry specified by given iterator
@@ -306,13 +310,15 @@ public:
         //- Find and return a hashedEntry
         inline const T& operator[](const Key& key) const;
 
-        //- Find and return a hashedEntry, create it null if not present
+        //- Return existing entry or create a new entry.
+        //  A newly created entry is created as a nameless T() and is thus
+        //  value-initialized. For primitives, this will be zero.
         inline T& operator()(const Key& key);
 
         //- Assignment
         void operator=(const HashTable<T, Key, Hash>& rhs);
 
-        //- Assignment to an initializer list
+        //- Assignment from an initializer list
         void operator=(std::initializer_list<Tuple2<Key, T>> lst);
 
         //- Equality. Hash tables are equal if the keys and values are equal.