ENH: improve HashTable iterator access and management

- provide key_iterator/const_key_iterator for all hashes,
  reuse directly for HashSet as iterator/const_iterator, respectively.

- additional keys() method for HashTable that returns a wrapped to
  a pair of begin/end const_iterators with additional size/empty
  information that allows these to be used directly by anything else
  expecting things with begin/end/size. Unfortunately does not yet
  work with std::distance().

  Example,
     for (auto& k : labelHashTable.keys())
     {
        ...
     }

src/OpenFOAM/containers/HashTables/HashTable/HashTableCore.C

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2012 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2017 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -33,38 +33,53 @@ namespace Foam
 defineTypeNameAndDebug(HashTableCore, 0);
 }
 
-const Foam::label Foam::HashTableCore::maxTableSize
-(
-    Foam::HashTableCore::canonicalSize
-    (
-        Foam::labelMax/2
-    )
-);
+
+// Approximately labelMax/4
+const Foam::label Foam::HashTableCore::maxTableSize(1 << (sizeof(label)*8-3));
 
 
 // * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * * //
 
-Foam::label Foam::HashTableCore::canonicalSize(const label size)
+Foam::label Foam::HashTableCore::canonicalSize(const label requested_size)
 {
-    if (size < 1)
+    if (requested_size < 1)
     {
         return 0;
     }
 
-    // enforce power of two
-    uLabel goodSize = size;
+    // Enforce power of two - makes for a vey fast modulus etc.
+    // Use unsigned for these calculations.
+    //
+    // - The lower limit (8) is somewhat arbitrary, but if the hash table
+    //   is too small, there will be many direct table collisions.
+    // - The uper limit (approx. labelMax/4) must be a power of two,
+    //   need not be extremely large for hashing.
 
-    if (goodSize & (goodSize - 1))
+    uLabel powerOfTwo = 8; // lower-limit
+
+    const uLabel size = requested_size;
+    if (size < powerOfTwo)
     {
-        // brute-force is fast enough
-        goodSize = 1;
-        while (goodSize < unsigned(size))
-        {
-            goodSize <<= 1;
-        }
+        return powerOfTwo;
     }
+    else if (requested_size >= maxTableSize)
+    {
+        return maxTableSize;
+    }
+    else if (size & (size-1))  // <- Modulus of i^2
+    {
+        // Determine power-of-two. Brute-force is fast enough.
+        while (powerOfTwo < size)
+        {
+            powerOfTwo <<= 1;
+        }
 
-    return goodSize;
+        return powerOfTwo;
+    }
+    else
+    {
+        return size;
+    }
 }