More optimization in BitSet and supporting documentation.

src/Data/Graph/Haggle/Internal/BitSet.hs

@@ -11,6 +11,21 @@ import Data.Vector.Unboxed.Mutable ( STVector )
 import qualified Data.Vector.Unboxed.Mutable as V
 import Data.Word ( Word64 )
 
+-- Note that the implementation here assumes thaththe bit numbers are all
+-- unsigned.  A proper implementation would perhaps use 'Natural' instead of
+-- 'Int', but that would require gratuitous fromEnum/toEnum conversions from all
+-- the other API's that just use 'Int', which has about a 33% performance impact
+-- when measured.
+--
+-- The 'setBit' and 'testBit' operations use V.unsafeRead instead of V.read
+-- (where the latter is roughly 25% slower) because this is an internal module
+-- that is generally always used with a positive 'Int' value, and the value is
+-- also checked against 'sz' (which is also probably superfluous).  In other
+-- words, this module prioritizes performance over robustness and should only be
+-- used when the caller can guarantee positive Int values and otherwise good
+-- behavior.
+
+
 data BitSet s = BS (STVector s Word64) {-# UNPACK #-} !Int
 
 bitsPerWord :: Int
@@ -33,7 +48,7 @@ setBit (BS v sz) bitIx
   | otherwise = do
     let wordIx = bitIx `div` bitsPerWord
         bitPos = bitIx `mod` bitsPerWord
-    oldWord <- V.read v wordIx
+    oldWord <- V.unsafeRead v wordIx
     let newWord = B.setBit oldWord bitPos
     V.write v wordIx newWord