ENH: added HashTable count, filter and generalized toc methods

- Generalized means over filtering table entries based on their keys,
  values, or both.  Either filter (retain), or optionally prune elements
  that satisfy the specified predicate.

  filterKeys and filterValues:
  - Take a unary predicate with the signature

        bool operator()(const Key& k);

  - filterEntries:
    Takes a binary predicate with the signature

        bool operator()(const Key& k, const T& v);

==

  The predicates can be normal class methods, or provide on-the-fly
  using a C++ lambda. For example,

      wordRes goodFields = ...;
      allFieldNames.filterKeys
      (
          [&goodFields](const word& k){ return goodFields.match(k); }
      );

  Note that all classes that can match a string (eg, regExp, keyType,
  wordRe, wordRes) or that are derived from a Foam::string (eg, fileName,
  word) are provided with a corresponding

      bool operator()(const std::string&)

  that either performs a regular expression or a literal match.
  This allows such objects to be used directly as a unary predicate
  when filtering any string hash keys.

  Note that HashSet and hashedWordList both have the proper
  operator() methods that also allow them to be used as a unary
  predicate.

- Similar predicate selection with the following:
    * tocKeys, tocValues, tocEntries
    * countKeys, countValues, countEntries

  except that instead of pruning, there is a simple logic inversion.

src/OpenFOAM/containers/HashTables/HashSet/HashSet.H

@@ -156,22 +156,24 @@ public:
       // Edit
 
         //- Insert a new entry
+        //  \return True if the entry inserted, which means that it did
+        //  not previously exist in the set.
         bool insert(const Key& key)
         {
             return this->parent_type::insert(key, nil());
         }
 
         //- Insert keys from the list of Key
-        //  Return the number of new elements inserted
+        //  \return The number of new elements inserted
         label insert(const UList<Key>& lst);
 
         //- Insert keys from the list of Key
-        //  Return the number of new elements inserted
+        //  \return The number of new elements inserted
         template<unsigned Size>
         label insert(const FixedList<Key, Size>& lst);
 
         //- Insert keys from a initializer list of Key
-        //  Return the number of new elements inserted
+        //  \return The number of new elements inserted
         label insert(std::initializer_list<Key> lst);
 
         //- Same as insert (cannot overwrite nil content)
@@ -200,18 +202,21 @@ public:
         }
 
         //- Unset the specified key - same as erase
+        //  \return True if the entry existed and was removed
         bool unset(const Key& key)
         {
             return this->parent_type::erase(key);
         }
 
         //- Unset the listed keys - same as erase
+        //  \return The number of items removed
         label unset(const UList<Key>& lst)
         {
             return this->parent_type::erase(lst);
         }
 
         //- Unset the listed keys - same as erase
+        //  \return The number of items removed
         template<unsigned Size>
         label unset(const FixedList<Key, Size>& lst)
         {
@@ -219,11 +224,36 @@ public:
         }
 
         //- Unset the listed keys - same as erase
+        //  \return The number of items removed
         label unset(std::initializer_list<Key> lst)
         {
             return this->parent_type::erase(lst);
         }
 
+        //- Not applicable for HashSet
+        template<class UnaryPredicate>
+        List<Key> tocValues(const UnaryPredicate&, const bool) = delete;
+
+        //- Not applicable for HashSet
+        template<class BinaryPredicate>
+        List<Key> tocEntries(const BinaryPredicate&, const bool) = delete;
+
+        //- Not applicable for HashSet
+        template<class UnaryPredicate>
+        label countValues(const UnaryPredicate&, const bool) = delete;
+
+        //- Not applicable for HashSet
+        template<class BinaryPredicate>
+        label countEntries(const BinaryPredicate&, const bool) = delete;
+
+        //- Not applicable for HashSet
+        template<class UnaryPredicate>
+        label filterValues(const UnaryPredicate&, const bool) = delete;
+
+        //- Not applicable for HashSet
+        template<class BinaryPredicate>
+        label filterEntries(const BinaryPredicate&, const bool) = delete;
+
 
     // STL iterators
 
@@ -248,12 +278,15 @@ public:
 
     // Member Operators
 
-        //- This operation doesn't make much sense for a hash-set
-        void operator()(const Key& key) = delete;
-
         //- Return true if the entry exists, same as found()
+        inline bool operator()(const Key& key) const;
+
+        //- Return true if the entry exists, same as found().
         inline bool operator[](const Key& key) const;
 
+
+      // Comparison
+
         //- Equality. Two hashset are equal when they have the same keys.
         //  Independent of table size or order.
         bool operator==(const this_type& rhs) const;
@@ -262,6 +295,8 @@ public:
         bool operator!=(const this_type& rhs) const;
 
 
+      // Assignment
+
         //- Assignment from a UList of keys
         void operator=(const UList<Key>& lst);
 
@@ -273,6 +308,8 @@ public:
         void operator=(std::initializer_list<Key> lst);
 
 
+      // Logical operations
+
         //- Combine entries from HashSets
         void operator|=(const HashSet<Key, Hash>& rhs);