ENH: added HashTable 'lookup' and 'retain' methods

- lookup(): with a default value (const access)
  For example,
      Map<label> something;
      value = something.lookup(key, -1);

    being equivalent to the following:

      Map<label> something;
      value = -1;  // bad value
      if (something.found(key))
      {
          value = something[key];
      }

    except that lookup also makes it convenient to handle const references.
    Eg,

      const labelList& ids = someHash.lookup(key, labelList());

- For consistency, provide a two parameter HashTable '()' operator.
  The lookup() method is, however, normally preferable when
  const-only access is to be ensured.

- retain(): the counterpart to erase(), it only retains entries
  corresponding to the listed keys.

  For example,
      HashTable<someType> largeCache;
      wordHashSet preserve = ...;

      largeCache.retain(preserve);

    being roughly equivalent to the following two-stage process,
    but with reduced overhead and typing, and fewer potential mistakes.

      HashTable<someType> largeCache;
      wordHashSet preserve = ...;

      {
          wordHashSet cull(largeCache.toc()); // all keys
          cull.erase(preserve);               // except those to preserve
          largeCache.erase(cull);             //
      }

  The HashSet &= operator and retain() are functionally equivalent,
  but retain() also works with dissimilar value types.

applications/test/HashSet/Test-hashSet.C

@@ -197,8 +197,12 @@ int main(int argc, char *argv[])
         Info<< "setD has no 11" << endl;
     }
 
+    Info<< "setB : " << flatOutput(setB) << endl;
     Info<< "setD : " << flatOutput(setD) << endl;
 
+    setD -= setB;
+    Info<< "setD -= setB : " << flatOutput(setD) << endl;
+
     // This should not work (yet?)
     // setD[12] = true;
 

applications/test/HashTable/Test-hashTable.C

@@ -25,6 +25,7 @@ License
 
 #include "HashTable.H"
 #include "List.H"
+#include "FlatOutput.H"
 #include "IOstreams.H"
 #include "IStringStream.H"
 #include "OStringStream.H"
@@ -163,15 +164,15 @@ int main()
         << "\ntable2" << table2 << nl;
 
 
-    Info<< "\ntable3" << table3
-        << "\nclearStorage table3 ... ";
-    table3.clearStorage();
-    Info<< table3 << nl;
+    Info<< "\ntable3" << table2
+        << "\nclearStorage table2 ... ";
+    table2.clearStorage();
+    Info<< table2 << nl;
 
     table1 =
     {
-        {"aca", 3.0},
-        {"aaw", 6.0},
+        {"abc", 3.0},
+        {"def", 6.0},
         {"acr", 8.0},
         {"aec", 10.0}
     };
@@ -195,6 +196,25 @@ int main()
     //  List<scalar> table1vals(table1.begin(), table1.end());
     //  wordList table1keys(table1.begin(), table1.end());
 
+    Info<< "\nFrom table1: " << flatOutput(table1.sortedToc()) << nl
+        << "retain keys: " << flatOutput(table3.sortedToc()) << nl;
+
+    table1.retain(table3);
+    Info<< "-> " << flatOutput(table1.sortedToc()) << nl;
+
+    Info<< "Lookup non-existent" << nl;
+
+    Info<< table1.lookup("missing-const", 1.2345e+6)
+        << "  // const-access" << nl;
+
+    Info<< table1("missing-inadvertent", 3.14159)
+        << "  // (inadvertent?) non-const access"  << nl;
+
+    Info<< table1("missing-autovivify")
+        << "  // Known auto-vivification (non-const access)" << nl;
+
+    Info<<"\ntable1: " << table1 << endl;
+
     Info<< "\nDone\n";
 
     return 0;