mod package:rebase

integer modulus, satisfying

(x `div` y)*y + (x `mod` y) == x

WARNING: This function is partial (because it throws when 0 is passed as the divisor) for all the integer types in base.

Generalisation of mod to any instance of Real

Monadic state transformer. Maps an old state to a new state inside a state monad. The old state is thrown away.

Main> :t modify ((+1) :: Int -> Int)
modify (...) :: (MonadState Int a) => a ()

This says that modify (+1) acts over any Monad that is a member of the MonadState class, with an Int state.

A variant of modify in which the computation is strict in the new state.

A different MonadError analogue to the withExceptT function. Modify the value (and possibly the type) of an error in an ExceptT-transformed monad, while stripping the ExceptT layer. This is useful for adapting the MonadError constraint of a computation. For example:

data DatabaseError = ...

performDatabaseQuery :: (MonadError DatabaseError m, ...) => m PersistedValue

data AppError
= MkDatabaseError DatabaseError
| ...

app :: (MonadError AppError m, ...) => m ()

Given these types, performDatabaseQuery cannot be used directly inside app, because the error types don't match. Using modifyError, an equivalent function with a different error type can be constructed:

performDatabaseQuery' :: (MonadError AppError m, ...) => m PersistedValue
performDatabaseQuery' = modifyError MkDatabaseError performDatabaseQuery

Since the error types do match, performDatabaseQuery' _can_ be used in app, assuming all other constraints carry over. This works by instantiating the m in the type of performDatabaseQuery to ExceptT DatabaseError m', which satisfies the MonadError DatabaseError constraint. Immediately, the ExceptT DatabaseError layer is unwrapped, producing Either a DatabaseError or a PersistedValue. If it's the former, the error is wrapped in MkDatabaseError and re-thrown in the inner monad, otherwise the result value is returned.

Catch any IOException that occurs in the computation and throw a modified version.

Mutate the contents of an IORef, combining readIORef and writeIORef. This is not an atomic update, consider using atomicModifyIORef when operating in a multithreaded environment. Be warned that modifyIORef does not apply the function strictly. This means if the program calls modifyIORef many times, but seldom uses the value, thunks will pile up in memory resulting in a space leak. This is a common mistake made when using an IORef as a counter. For example, the following will likely produce a stack overflow:

ref <- newIORef 0
replicateM_ 1000000 $ modifyIORef ref (+1)
readIORef ref >>= print

To avoid this problem, use modifyIORef' instead.

Strict version of modifyIORef. This is not an atomic update, consider using atomicModifyIORef' when operating in a multithreaded environment.

A slight variation on modifyMVar_ that allows a value to be returned (b) in addition to the modified value of the MVar.

Like modifyMVar, but the IO action in the second argument is executed with asynchronous exceptions masked.

Like modifyMVar_, but the IO action in the second argument is executed with asynchronous exceptions masked.

An exception-safe wrapper for modifying the contents of an MVar. Like withMVar, modifyMVar will replace the original contents of the MVar if an exception is raised during the operation. This function is only atomic if there are no other producers for this MVar. In other words, it cannot guarantee that, by the time modifyMVar_ gets the chance to write to the MVar, the value of the MVar has not been altered by a write operation from another thread.

Mutate the contents of an STRef.

>>> :{
runST (do
ref <- newSTRef ""
modifySTRef ref (const "world")
modifySTRef ref (++ "!")
modifySTRef ref ("Hello, " ++)
readSTRef ref )
:}
"Hello, world!"

Be warned that modifySTRef does not apply the function strictly. This means if the program calls modifySTRef many times, but seldom uses the value, thunks will pile up in memory resulting in a space leak. This is a common mistake made when using an STRef as a counter. For example, the following will leak memory and may produce a stack overflow:

>>> import Control.Monad (replicateM_)

>>> :{
print (runST (do
ref <- newSTRef 0
replicateM_ 1000 $ modifySTRef ref (+1)
readSTRef ref ))
:}
1000

To avoid this problem, use modifySTRef' instead.

Strict version of modifySTRef

Mutate the contents of a TVar. N.B., this version is non-strict.

Strict version of modifyTVar.

Lm: Letter, Modifier

Sk: Symbol, Modifier

Atomically modifies the contents of an IORef. This function is useful for using IORef in a safe way in a multithreaded program. If you only have one IORef, then using atomicModifyIORef to access and modify it will prevent race conditions. Extending the atomicity to multiple IORefs is problematic, so it is recommended that if you need to do anything more complicated then using MVar instead is a good idea. atomicModifyIORef does not apply the function strictly. This is important to know even if all you are doing is replacing the value. For example, this will leak memory:

ref <- newIORef '1'
forever $ atomicModifyIORef ref (\_ -> ('2', ()))

Use atomicModifyIORef' or atomicWriteIORef to avoid this problem. This function imposes a memory barrier, preventing reordering; see Data.IORef#memmodel for details.

Strict version of atomicModifyIORef. This forces both the value stored in the IORef and the value returned. The new value is installed in the IORef before the returned value is forced. So

atomicModifyIORef' ref (x -> (x+1, undefined))

will increment the IORef and then throw an exception in the calling thread. This function imposes a memory barrier, preventing reordering; see Data.IORef#memmodel for details.

simultaneous div and mod WARNING: This function is partial (because it throws when 0 is passed as the divisor) for all the integer types in base.

Generalisation of divMod to any instance of Real