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


-- | Containers for STM
--   
--   This library is based on an STM-specialized implementation of Hash
--   Array Mapped Trie. It provides efficient implementations of
--   <tt>Map</tt>, <tt>Set</tt> and other data structures, which are
--   marginally slower than their counterparts from "unordered-containers",
--   but scale well on concurrent access patterns.
--   
--   For details on performance of the library see <a>this blog post</a>.
@package stm-containers
@version 0.2.16

module STMContainers.Set

-- | A hash set, based on an STM-specialized hash array mapped trie.
data Set e

-- | A constraint for elements.
type Element a = (Eq a, Hashable a)

-- | Construct a new set.
new :: STM (Set e)

-- | Construct a new set in IO.
--   
--   This is useful for creating it on a top-level using
--   <a>unsafePerformIO</a>, because using <a>atomically</a> inside
--   <a>unsafePerformIO</a> isn't possible.
newIO :: IO (Set e)

-- | Insert a new element.
insert :: (Element e) => e -> Set e -> STM ()

-- | Delete an element.
delete :: (Element e) => e -> Set e -> STM ()

-- | Delete all the associations.
deleteAll :: Set e -> STM ()

-- | Lookup an element.
lookup :: (Element e) => e -> Set e -> STM Bool

-- | Focus on an element with a strategy.
--   
--   This function allows to perform simultaneous lookup and modification.
--   
--   The strategy is over a unit since we already know, which element we're
--   focusing on and it doesn't make sense to replace it, however we still
--   can decide wether to keep or remove it.
focus :: (Element e) => StrategyM STM () r -> e -> Set e -> STM r

-- | Check, whether the set is empty.
null :: Set e -> STM Bool

-- | Get the number of elements.
size :: Set e -> STM Int

-- | Stream elements.
--   
--   Amongst other features this function provides an interface to folding
--   via the <a>fold</a> function.
stream :: Set e -> ListT STM e
instance GHC.Classes.Eq e => STMContainers.HAMT.Nodes.Element (STMContainers.Set.HAMTElement e)

module STMContainers.Map

-- | A hash table, based on an STM-specialized hash array mapped trie.
data Map k v

-- | A constraint for keys.
type Key a = (Eq a, Hashable a)

-- | Construct a new map.
new :: STM (Map k v)

-- | Construct a new map in IO.
--   
--   This is useful for creating it on a top-level using
--   <a>unsafePerformIO</a>, because using <a>atomically</a> inside
--   <a>unsafePerformIO</a> isn't possible.
newIO :: IO (Map k v)

-- | Insert a value at a key.
insert :: (Key k) => v -> k -> Map k v -> STM ()

-- | Delete an item by a key.
delete :: (Key k) => k -> Map k v -> STM ()

-- | Delete all the associations.
deleteAll :: Map k v -> STM ()

-- | Look up an item.
lookup :: (Key k) => k -> Map k v -> STM (Maybe v)

-- | Focus on an item by a key with a strategy.
--   
--   This function allows to perform composite operations in a single
--   access to a map item. E.g., you can look up an item and delete it at
--   the same time, or update it and return the new value.
focus :: (Key k) => StrategyM STM v r -> k -> Map k v -> STM r

-- | Check, whether the map is empty.
null :: Map k v -> STM Bool

-- | Get the number of elements.
size :: Map k v -> STM Int

-- | Stream associations.
--   
--   Amongst other features this function provides an interface to folding
--   via the <a>fold</a> function.
stream :: Map k v -> ListT STM (k, v)
instance GHC.Classes.Eq k => STMContainers.HAMT.Nodes.Element (k, v)

module STMContainers.Multimap

-- | A multimap, based on an STM-specialized hash array mapped trie.
--   
--   Basically it's just a wrapper API around <tt><a>Map</a> k (<a>Set</a>
--   v)</tt>.
data Multimap k v

-- | A constraint for associations.
type Association k v = (Key k, Value v)

-- | A constraint for keys.
type Key k = Key k

-- | A constraint for values.
type Value v = Element v

-- | Construct a new multimap.
new :: STM (Multimap k v)

-- | Construct a new multimap in IO.
--   
--   This is useful for creating it on a top-level using
--   <a>unsafePerformIO</a>, because using <a>atomically</a> inside
--   <a>unsafePerformIO</a> isn't possible.
newIO :: IO (Multimap k v)

-- | Insert an item.
insert :: (Association k v) => v -> k -> Multimap k v -> STM ()

-- | Delete an item by a value and a key.
delete :: (Association k v) => v -> k -> Multimap k v -> STM ()

-- | Delete all values associated with a key.
deleteByKey :: Key k => k -> Multimap k v -> STM ()

-- | Delete all the associations.
deleteAll :: Multimap k v -> STM ()

-- | Look up an item by a value and a key.
lookup :: (Association k v) => v -> k -> Multimap k v -> STM Bool

-- | Look up all values by key.
lookupByKey :: Key k => k -> Multimap k v -> STM (Maybe (Set v))

-- | Focus on an item with a strategy by a value and a key.
--   
--   This function allows to perform simultaneous lookup and modification.
--   
--   The strategy is over a unit since we already know, which value we're
--   focusing on and it doesn't make sense to replace it, however we still
--   can decide wether to keep or remove it.
focus :: (Association k v) => StrategyM STM () r -> v -> k -> Multimap k v -> STM r

-- | Check on being empty.
null :: Multimap k v -> STM Bool

-- | Stream associations.
--   
--   Amongst other features this function provides an interface to folding
--   via the <a>fold</a> function.
stream :: Multimap k v -> ListT STM (k, v)

-- | Stream keys.
streamKeys :: Multimap k v -> ListT STM k

-- | Stream values by a key.
streamByKey :: Association k v => k -> Multimap k v -> ListT STM v

module STMContainers.Bimap

-- | A bidirectional map. Essentially a bijection between subsets of its
--   two argument types.
--   
--   For one value of a left-hand type this map contains one value of the
--   right-hand type and vice versa.
data Bimap a b

-- | A constraint for associations.
type Association a b = (Key a, Key b)

-- | A constraint for keys.
type Key k = Key k

-- | Construct a new bimap.
new :: STM (Bimap a b)

-- | Construct a new bimap in IO.
--   
--   This is useful for creating it on a top-level using
--   <a>unsafePerformIO</a>, because using <a>atomically</a> inside
--   <a>unsafePerformIO</a> isn't possible.
newIO :: IO (Bimap a b)

-- | Insert an association by a left value.
insert1 :: (Association a b) => b -> a -> Bimap a b -> STM ()

-- | Insert an association by a right value.
insert2 :: (Association a b) => a -> b -> Bimap a b -> STM ()

-- | Delete an association by a left value.
delete1 :: (Association a b) => a -> Bimap a b -> STM ()

-- | Delete an association by a right value.
delete2 :: (Association a b) => b -> Bimap a b -> STM ()

-- | Delete all the associations.
deleteAll :: Bimap a b -> STM ()

-- | Look up a right value by a left value.
lookup1 :: (Association a b) => a -> Bimap a b -> STM (Maybe b)

-- | Look up a left value by a right value.
lookup2 :: (Association a b) => b -> Bimap a b -> STM (Maybe a)

-- | Focus on a right value by a left value with a strategy.
--   
--   This function allows to perform composite operations in a single
--   access to a map item. E.g., you can look up an item and delete it at
--   the same time, or update it and return the new value.
focus1 :: (Association a b) => StrategyM STM b r -> a -> Bimap a b -> STM r

-- | Focus on a left value by a right value with a strategy.
--   
--   This function allows to perform composite operations in a single
--   access to a map item. E.g., you can look up an item and delete it at
--   the same time, or update it and return the new value.
focus2 :: (Association a b) => StrategyM STM a r -> b -> Bimap a b -> STM r

-- | Check on being empty.
null :: Bimap a b -> STM Bool

-- | Get the number of elements.
size :: Bimap a b -> STM Int

-- | Stream associations.
--   
--   Amongst other features this function provides an interface to folding
--   via the <a>fold</a> function.
stream :: Bimap a b -> ListT STM (a, b)
