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.

src/OpenFOAM/containers/HashTables/HashTable/HashTableI.H

@@ -79,10 +79,10 @@ template<class T, class Key, class Hash>
 inline bool Foam::HashTable<T, Key, Hash>::insert
 (
     const Key& key,
-    const T& newEntry
+    const T& obj
 )
 {
-    return this->set(key, newEntry, true);
+    return this->set(key, obj, true);
 }
 
 
@@ -90,10 +90,10 @@ template<class T, class Key, class Hash>
 inline bool Foam::HashTable<T, Key, Hash>::set
 (
     const Key& key,
-    const T& newEntry
+    const T& obj
 )
 {
-    return this->set(key, newEntry, false);
+    return this->set(key, obj, false);
 }
 
 
@@ -105,6 +105,18 @@ Foam::HashTable<T, Key, Hash>::xfer()
 }
 
 
+template<class T, class Key, class Hash>
+inline const T& Foam::HashTable<T, Key, Hash>::lookup
+(
+    const Key& key,
+    const T& deflt
+) const
+{
+    const_iterator iter = this->find(key);
+    return iter.found() ? iter.object() : deflt;
+}
+
+
 // * * * * * * * * * * * * * * * Member Operators  * * * * * * * * * * * * * //
 
 template<class T, class Key, class Hash>
@@ -156,6 +168,36 @@ inline T& Foam::HashTable<T, Key, Hash>::operator()(const Key& key)
 }
 
 
+template<class T, class Key, class Hash>
+inline T& Foam::HashTable<T, Key, Hash>::operator()
+(
+    const Key& key,
+    const T& deflt
+)
+{
+    iterator iter = this->find(key);
+
+    if (iter.found())
+    {
+        return iter.object();
+    }
+
+    this->insert(key, deflt);
+    return find(key).object();
+}
+
+
+template<class T, class Key, class Hash>
+inline const T& Foam::HashTable<T, Key, Hash>::operator()
+(
+    const Key& key,
+    const T& deflt
+) const
+{
+    return this->lookup(key, deflt);
+}
+
+
 // * * * * * * * * * * * * * * * iterator base * * * * * * * * * * * * * * * //
 
 template<class T, class Key, class Hash>