-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Universal hashing of bytes
--   
--   Taken together, universal hash functions and a good source of entropy
--   provide a foundation for hash maps guarantee O(1) lookups even if an
--   adversary chooses the keys. This library implements such a hash map.
--   The implementation of lookup is tuned for performance. The functions
--   for building hash maps are not since they are intended to be called
--   infrequently.
@package bytehash
@version 0.1.1.2


-- | Hash functions for byte sequences of a bounded size.
module Data.Bytes.Hash

-- | Hash a byte array of length <tt>n</tt>. This takes advantage of the
--   machine-word alignment guarantee that GHC provides for byte arrays.
byteArray :: ByteArray -> ByteArray -> Word32

-- | Hash a byte sequence of length <tt>n</tt>.
bytes :: ByteArray -> Bytes -> Word32

-- | Statically defined source of entropy. Exactly 16384 bytes.
entropy :: Ptr Word8


-- | Implementation of static hash map data structure.
module Data.Bytes.HashMap

-- | A static perfect hash table where the keys are byte arrays. This table
--   cannot be updated after its creation, but all lookups have guaranteed
--   O(1) worst-case cost. It consumes linear space. This is an excellent
--   candidate for use with compact regions.
data Map v

-- | An empty <tt>Map</tt>.
empty :: Map v

-- | Returns the value associated with the key in the map.
lookup :: Bytes -> Map v -> Maybe v

-- | Build a static hash map. This may be used on input that comes from an
--   adversarial user. It always produces a perfect hash map.
fromList :: CryptHandle -> [(Bytes, v)] -> IO (Map v)

-- | Build a map from keys that are known at compile time. All keys must be
--   64 bytes or less. This uses a built-in source of entropy and is
--   entirely deterministic. An adversarial user could feed this function
--   keys that cause it to error out rather than completing.
fromTrustedList :: [(Bytes, v)] -> Map v
fromListWith :: forall v. CryptHandle -> (v -> v -> v) -> [(Bytes, v)] -> IO (Map v)

-- | Recover the elements of the hashmap. These are ordered
--   lexicographically by their corresponding keys. That is, this function
--   returns the same output regardless of the entropy used to build the
--   hashmap.
elements :: Map v -> [v]
data HashMapException
HashMapException :: !Int -> [Bytes] -> [[(Word, Bytes)]] -> HashMapException

-- | For each slot, gives the number of keys that hash to it after the
--   first hash function has been applied.
distribution :: Map v -> [(Int, Int)]

-- | The number of non-matching entropies being used.
distinctEntropies :: Map v -> Int
instance GHC.Exception.Type.Exception Data.Bytes.HashMap.HashMapException
instance GHC.Classes.Eq Data.Bytes.HashMap.HashMapException
instance GHC.Show.Show Data.Bytes.HashMap.HashMapException


-- | Implementation of static hash map data structure.
module Data.Bytes.HashMap.Word

-- | A static perfect hash table where the keys are byte arrays. This table
--   cannot be updated after its creation, but all lookups have guaranteed
--   O(1) worst-case cost. It consumes linear space. This is an excellent
--   candidate for use with compact regions.
data Map
lookup :: Bytes -> Map -> Maybe Word
fromList :: CryptHandle -> [(Bytes, Word)] -> IO Map

-- | Build a map from keys that are known at compile time. All keys must be
--   64 bytes or less. This uses a built-in source of entropy and is
--   entirely deterministic. An adversarial user could feed this function
--   keys that cause it to error out rather than completing.
fromTrustedList :: [(Bytes, Word)] -> Map
fromListWith :: CryptHandle -> (Word -> Word -> Word) -> [(Bytes, Word)] -> IO Map
distribution :: Map -> [(Int, Int)]

-- | The number of non-matching entropies being used.
distinctEntropies :: Map -> Int