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


-- | A mutable hashmap, implicitly indexed by UTCTime.
--   
--   A mutable hashmap, implicitly indexed by UTCTime.
@package timemap
@version 0.0.4


-- | A time-indexed mutable map for hashable keys.
--   
--   The goal of this map is to provide moderately fast lookups and
--   insertions for key/value pairs, while implicitly keeping track of the
--   last modification time of each entity. The auxilliary time data is
--   used for <a>filterSince</a> and <a>filterFromNow</a>, which quickly
--   prune the data set to get rid of old entities.
module Data.TimeMap

-- | A mutable reference for a time-indexed map, similar to a <a>STRef</a>.
data TimeMap k a

-- | Create a fresh, empty map.
newTimeMap :: STM (TimeMap k a)

-- | Inserts a key and value into a <a>TimeMap</a> - it adds the value or
--   overwites an existing entity.
insert :: (Hashable k, Eq k) => k -> a -> TimeMap k a -> IO ()
insertWithTime :: (Hashable k, Eq k) => UTCTime -> k -> a -> TimeMap k a -> STM ()

-- | Updates or deletes the value at <tt>k</tt>, while updating its time.
update :: (Hashable k, Eq k) => (a -> Maybe a) -> k -> TimeMap k a -> IO ()
updateWithTime :: (Hashable k, Eq k) => UTCTime -> (a -> Maybe a) -> k -> TimeMap k a -> STM ()

-- | Adjusts the value at <tt>k</tt>, while updating its time.
adjust :: (Hashable k, Eq k) => (a -> a) -> k -> TimeMap k a -> IO ()
adjustWithTime :: (Hashable k, Eq k) => UTCTime -> (a -> a) -> k -> TimeMap k a -> STM ()

-- | Deletes the value at <tt>k</tt>.
delete :: (Hashable k, Eq k) => k -> TimeMap k a -> STM ()

-- | Resets the key to the current time, and fails silently when the key
--   isn't present.
touch :: (Hashable k, Eq k) => k -> TimeMap k a -> IO ()

-- | Performs a non-mutating lookup for some key.
lookup :: (Hashable k, Eq k) => k -> TimeMap k a -> STM (Maybe a)
timeOf :: (Hashable k, Eq k) => k -> TimeMap k a -> STM (Maybe UTCTime)
ageOf :: (Hashable k, Eq k) => k -> TimeMap k a -> IO (Maybe NominalDiffTime)
keys :: (Hashable k, Eq k) => TimeMap k a -> STM (HashSet k)
elems :: TimeMap k a -> STM [a]
toList :: (Hashable k, Eq k) => TimeMap k a -> STM [(k, a)]
size :: TimeMap k a -> STM Int
null :: TimeMap k a -> STM Bool
filter :: (Hashable k, Eq k) => (a -> Bool) -> TimeMap k a -> STM ()
filterWithKey :: (Hashable k, Eq k) => (k -> a -> Bool) -> TimeMap k a -> STM ()

-- | Filters out all entries older than or equal to a designated time
filterSince :: (Hashable k, Eq k) => UTCTime -> TimeMap k a -> STM ()

-- | Filters out all entries within some time frame
--   
--   <pre>
--   filterFromNow 1 -- removes entities older than or equal to one second from now
--   </pre>
filterFromNow :: (Hashable k, Eq k) => NominalDiffTime -> TimeMap k a -> IO ()
