Document preconditions

Author: meooow25

containers/src/Data/IntSet/Internal/IntTreeCommons.hs

@@ -150,6 +150,8 @@ mask i m = i .&. ((-m) `xor` m)
 {-# INLINE mask #-}
 
 -- | The first switching bit where the two prefixes disagree.
+--
+-- Precondition for defined behavior: p1 /= p2
 branchMask :: Int -> Int -> Int
 branchMask p1 p2 = iHighestBitMask (p1 `xor` p2)
 {-# INLINE branchMask #-}

containers/src/Utils/Containers/Internal/BitUtil.hs

@@ -44,11 +44,15 @@ import GHC.Exts (Int(..), uncheckedIShiftRL#)
 #endif
 
 -- | An @Int@ where only the highest bit is set.
+--
+-- Precondition for defined behavior: w /= 0
 iHighestBitMask :: Int -> Int
 iHighestBitMask w = unsafeShiftL 1 (wordSize - 1 - countLeadingZeros w)
 {-# INLINE iHighestBitMask #-}
 
 -- Right and left logical shifts.
+--
+-- Precondition for defined behavior: 0 <= shift amount < wordSize
 shiftRL, shiftLL :: Word -> Int -> Word
 shiftRL = unsafeShiftR
 shiftLL = unsafeShiftL
@@ -58,6 +62,8 @@ wordSize :: Int
 wordSize = finiteBitSize (0 :: Word)
 
 -- Right logical shift.
+--
+-- Precondition for defined behavior: 0 <= shift amount < wordSize
 iShiftRL :: Int -> Int -> Int
 #ifdef __GLASGOW_HASKELL__
 iShiftRL (I# x#) (I# sh#) = I# (uncheckedIShiftRL# x# sh#)