Safe Haskell | None |
---|

This module documents all the functions available in this package.

Most users should import the specific modules (e.g. `Data.List.Extra`

), which
also reexport their non-`Extra`

modules (e.g. `Data.List`

).

- withNumCapabilities :: Int -> IO a -> IO a
- setNumCapabilities :: Int -> IO ()
- forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId
- data Lock
- newLock :: IO Lock
- withLock :: Lock -> IO a -> IO a
- withLockTry :: Lock -> IO a -> IO (Maybe a)
- data Var a
- newVar :: a -> IO (Var a)
- readVar :: Var a -> IO a
- modifyVar :: Var a -> (a -> IO (a, b)) -> IO b
- modifyVar_ :: Var a -> (a -> IO a) -> IO ()
- withVar :: Var a -> (a -> IO b) -> IO b
- data Barrier a
- newBarrier :: IO (Barrier a)
- signalBarrier :: Barrier a -> a -> IO ()
- waitBarrier :: Barrier a -> IO a
- waitBarrierMaybe :: Barrier a -> IO (Maybe a)
- retry :: Int -> IO a -> IO a
- showException :: Show e => e -> IO String
- stringException :: String -> IO String
- ignore :: IO () -> IO ()
- catch_ :: IO a -> (SomeException -> IO a) -> IO a
- handle_ :: (SomeException -> IO a) -> IO a -> IO a
- try_ :: IO a -> IO (Either SomeException a)
- catchJust_ :: (SomeException -> Maybe b) -> IO a -> (b -> IO a) -> IO a
- handleJust_ :: (SomeException -> Maybe b) -> (b -> IO a) -> IO a -> IO a
- tryJust_ :: (SomeException -> Maybe b) -> IO a -> IO (Either b a)
- catchBool :: Exception e => (e -> Bool) -> IO a -> (e -> IO a) -> IO a
- handleBool :: Exception e => (e -> Bool) -> (e -> IO a) -> IO a -> IO a
- tryBool :: Exception e => (e -> Bool) -> IO a -> IO (Either e a)
- whenJust :: Applicative m => Maybe a -> (a -> m ()) -> m ()
- unit :: m () -> m ()
- partitionM :: Monad m => (a -> m Bool) -> [a] -> m ([a], [a])
- concatMapM :: Monad m => (a -> m [b]) -> [a] -> m [b]
- mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b]
- loopM :: Monad m => (a -> m (Either a b)) -> a -> m b
- whileM :: Monad m => m Bool -> m ()
- whenM :: Monad m => m Bool -> m () -> m ()
- unlessM :: Monad m => m Bool -> m () -> m ()
- ifM :: Monad m => m Bool -> m a -> m a -> m a
- notM :: Functor m => m Bool -> m Bool
- (||^) :: Monad m => m Bool -> m Bool -> m Bool
- (&&^) :: Monad m => m Bool -> m Bool -> m Bool
- orM :: Monad m => [m Bool] -> m Bool
- andM :: Monad m => [m Bool] -> m Bool
- anyM :: Monad m => (a -> m Bool) -> [a] -> m Bool
- allM :: Monad m => (a -> m Bool) -> [a] -> m Bool
- findM :: Monad m => (a -> m Bool) -> [a] -> m (Maybe a)
- firstJustM :: Monad m => (a -> m (Maybe b)) -> [a] -> m (Maybe b)
- isLeft :: Either t t1 -> Bool
- isRight :: Either t t1 -> Bool
- fromLeft :: Either l r -> l
- fromRight :: Either l r -> r
- fromEither :: Either a a -> a
- modifyIORef' :: IORef a -> (a -> a) -> IO ()
- writeIORef' :: IORef a -> a -> IO ()
- atomicModifyIORef' :: IORef a -> (a -> (a, b)) -> IO b
- atomicWriteIORef :: IORef a -> a -> IO ()
- atomicWriteIORef' :: IORef a -> a -> IO ()
- lower :: String -> String
- upper :: String -> String
- trim :: String -> String
- trimStart :: String -> String
- trimEnd :: String -> String
- dropAround :: (a -> Bool) -> [a] -> [a]
- word1 :: String -> (String, String)
- drop1 :: [a] -> [a]
- list :: b -> (a -> [a] -> b) -> [a] -> b
- uncons :: [a] -> Maybe (a, [a])
- unsnoc :: [a] -> Maybe ([a], a)
- cons :: a -> [a] -> [a]
- snoc :: [a] -> a -> [a]
- groupSort :: Ord k => [(k, v)] -> [(k, [v])]
- groupSortOn :: Ord a => (k -> a) -> [(k, v)] -> [(k, [v])]
- nubOn :: Eq b => (a -> b) -> [a] -> [a]
- groupOn :: Eq b => (a -> b) -> [a] -> [[a]]
- sortOn :: Ord b => (a -> b) -> [a] -> [a]
- repeatedly :: ([a] -> (b, [a])) -> [a] -> [b]
- for :: [a] -> (a -> b) -> [b]
- disjoint :: Eq a => [a] -> [a] -> Bool
- allSame :: Eq a => [a] -> Bool
- anySame :: Eq a => [a] -> Bool
- dropEnd :: Int -> [a] -> [a]
- takeEnd :: Int -> [a] -> [a]
- breakEnd :: (a -> Bool) -> [a] -> ([a], [a])
- spanEnd :: (a -> Bool) -> [a] -> ([a], [a])
- dropWhileEnd :: (a -> Bool) -> [a] -> [a]
- dropWhileEnd' :: (a -> Bool) -> [a] -> [a]
- takeWhileEnd :: (a -> Bool) -> [a] -> [a]
- stripSuffix :: Eq a => [a] -> [a] -> Maybe [a]
- concatUnzip :: [([a], [b])] -> ([a], [b])
- concatUnzip3 :: [([a], [b], [c])] -> ([a], [b], [c])
- merge :: Ord a => [a] -> [a] -> [a]
- mergeBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]
- replace :: Eq a => [a] -> [a] -> [a] -> [a]
- wordsBy :: (a -> Bool) -> [a] -> [[a]]
- linesBy :: (a -> Bool) -> [a] -> [[a]]
- firstJust :: (a -> Maybe b) -> [a] -> Maybe b
- breakOn :: Eq a => [a] -> [a] -> ([a], [a])
- breakOnEnd :: Eq a => [a] -> [a] -> ([a], [a])
- splitOn :: Eq a => [a] -> [a] -> [[a]]
- split :: (a -> Bool) -> [a] -> [[a]]
- chunksOf :: Int -> [a] -> [[a]]
- first :: (a -> a') -> (a, b) -> (a', b)
- second :: (b -> b') -> (a, b) -> (a, b')
- (***) :: (a -> a') -> (b -> b') -> (a, b) -> (a', b')
- (&&&) :: (a -> b) -> (a -> c) -> a -> (b, c)
- dupe :: a -> (a, a)
- both :: (a -> b) -> (a, a) -> (b, b)
- fst3 :: (a, b, c) -> a
- snd3 :: (a, b, c) -> b
- thd3 :: (a, b, c) -> c
- first3 :: (a -> a') -> (a, b, c) -> (a', b, c)
- second3 :: (b -> b') -> (a, b, c) -> (a, b', c)
- third3 :: (c -> c') -> (a, b, c) -> (a, b, c')
- dupe3 :: a -> (a, a, a)
- both3 :: (a -> b) -> (a, a, a) -> (b, b, b)
- showDP :: RealFloat a => Int -> a -> String
- intToDouble :: Int -> Double
- intToFloat :: Int -> Float
- floatToDouble :: Float -> Double
- doubleToFloat :: Double -> Float
- withCurrentDirectory :: FilePath -> IO a -> IO a
- getDirectoryContentsRecursive :: FilePath -> IO [FilePath]
- createDirectoryPrivate :: String -> IO ()
- getExecutablePath :: IO FilePath
- lookupEnv :: String -> IO (Maybe String)
- isWindows :: Bool
- getProcessorCount :: IO Int
- readFileEncoding :: TextEncoding -> FilePath -> IO String
- readFileUTF8 :: FilePath -> IO String
- readFileBinary :: FilePath -> IO String
- readFile' :: FilePath -> IO String
- readFileEncoding' :: TextEncoding -> FilePath -> IO String
- readFileUTF8' :: FilePath -> IO String
- readFileBinary' :: FilePath -> IO String
- writeFileEncoding :: TextEncoding -> FilePath -> String -> IO ()
- writeFileUTF8 :: FilePath -> String -> IO ()
- writeFileBinary :: FilePath -> String -> IO ()
- withTempFile :: (FilePath -> IO a) -> IO a
- withTempDir :: (FilePath -> IO a) -> IO a
- newTempFile :: (IO FilePath, FilePath -> IO ())
- newTempDir :: (IO FilePath, FilePath -> IO ())
- captureOutput :: IO a -> IO (String, a)
- withBuffering :: Handle -> BufferMode -> IO a -> IO a
- system_ :: String -> IO ()
- systemOutput :: String -> IO (ExitCode, String)
- systemOutput_ :: String -> IO String
- type Seconds = Double
- sleep :: Seconds -> IO ()
- subtractTime :: UTCTime -> UTCTime -> Seconds
- showDuration :: Seconds -> String
- offsetTime :: IO (IO Seconds)
- offsetTimeIncrease :: IO (IO Seconds)
- duration :: IO a -> IO (Seconds, a)

# Control.Concurrent.Extra

Extra functions available in `Control.Concurrent.Extra`

.

withNumCapabilities :: Int -> IO a -> IO aSource

On GHC 7.6 and above with the `-threaded`

flag, brackets a call to `setNumCapabilities`

.
On lower versions (which lack `setNumCapabilities`

) this function just runs the argument action.

setNumCapabilities :: Int -> IO ()

Set the number of Haskell threads that can run truly simultaneously
(on separate physical processors) at any given time. The number
passed to `forkOn`

is interpreted modulo this value. The initial
value is given by the `+RTS -N`

runtime flag.

This is also the number of threads that will participate in parallel garbage collection. It is strongly recommended that the number of capabilities is not set larger than the number of physical processor cores, and it may often be beneficial to leave one or more cores free to avoid contention with other processes in the machine.

forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId

fork a thread and call the supplied function when the thread is about to terminate, with an exception or a returned value. The function is called with asynchronous exceptions masked.

forkFinally action and_then = mask $ \restore -> forkIO $ try (restore action) >>= and_then

This function is useful for informing the parent when a child terminates, for example.

modifyVar_ :: Var a -> (a -> IO a) -> IO ()Source

newBarrier :: IO (Barrier a)Source

signalBarrier :: Barrier a -> a -> IO ()Source

waitBarrier :: Barrier a -> IO aSource

waitBarrierMaybe :: Barrier a -> IO (Maybe a)Source

# Control.Exception.Extra

Extra functions available in `Control.Exception.Extra`

.

retry :: Int -> IO a -> IO aSource

Retry an operation at most N times (N must be positive).

retry 1 (print "x") == print "x" retry 3 (fail "die") == fail "die"

showException :: Show e => e -> IO StringSource

Show a value, but if the result contains exceptions, produce
`<Exception>`

. Defined as

.
Particularly useful for printing exceptions to users, remembering that exceptions
can themselves contain undefined values.
`stringException`

. show

stringException :: String -> IO StringSource

Fully evaluate an input String. If the String contains embedded exceptions it will produce `<Exception>`

.

stringException ("test" ++ undefined) == return "test<Exception>" stringException ("test" ++ undefined ++ "hello") == return "test<Exception>" stringException "test" == return "test"

ignore :: IO () -> IO ()Source

Ignore any exceptions thrown by the action.

ignore (print 1) == print 1 ignore (fail "die") == return ()

catch_ :: IO a -> (SomeException -> IO a) -> IO aSource

A version of `catch`

without the `Exception`

context, restricted to `SomeException`

,
so catches all exceptions.

catchJust_ :: (SomeException -> Maybe b) -> IO a -> (b -> IO a) -> IO aSource

handleJust_ :: (SomeException -> Maybe b) -> (b -> IO a) -> IO a -> IO aSource

Like `catch_`

but for `handleJust`

catchBool :: Exception e => (e -> Bool) -> IO a -> (e -> IO a) -> IO aSource

Catch an exception if the predicate passes, then call the handler with the original exception. As an example:

> readFileExists x == catchBool isDoesNotExistError (readFile "myfile") (const $ return "")

# Control.Monad.Extra

Extra functions available in `Control.Monad.Extra`

.

whenJust :: Applicative m => Maybe a -> (a -> m ()) -> m ()Source

The identity function which requires the inner argument to be '()'. Useful for functions with overloaded return times.

\(x :: Maybe ()) -> unit x == x

partitionM :: Monad m => (a -> m Bool) -> [a] -> m ([a], [a])Source

A version of `partition`

that works with a monadic predicate.

partitionM (Just . even) [1,2,3] == Just ([2], [1,3]) partitionM (const Nothing) [1,2,3] == Nothing

concatMapM :: Monad m => (a -> m [b]) -> [a] -> m [b]Source

A version of `concatMap`

that works with a monadic predicate.

mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b]Source

A version of `mapMaybe`

that works with a monadic predicate.

firstJustM :: Monad m => (a -> m (Maybe b)) -> [a] -> m (Maybe b)Source

# Data.Either.Extra

Extra functions available in `Data.Either.Extra`

.

fromEither :: Either a a -> aSource

Pull the value out of an `Either`

where both alternatives
have the same type.

# Data.IORef.Extra

Extra functions available in `Data.IORef.Extra`

.

modifyIORef' :: IORef a -> (a -> a) -> IO ()

Strict version of `modifyIORef`

writeIORef' :: IORef a -> a -> IO ()Source

Evaluates the value before calling `writeIORef`

atomicModifyIORef' :: IORef a -> (a -> (a, b)) -> IO b

Strict version of `atomicModifyIORef`

. This forces both the value stored
in the `IORef`

as well as the value returned.

atomicWriteIORef :: IORef a -> a -> IO ()

Variant of `writeIORef`

with the "barrier to reordering" property that
`atomicModifyIORef`

has.

atomicWriteIORef' :: IORef a -> a -> IO ()Source

Evaluates the value before calling `atomicWriteIORef`

# Data.List.Extra

Extra functions available in `Data.List.Extra`

.

lower :: String -> StringSource

Documentation about lowercase

lower "This is A TEST" == "this is a test" lower "" == ""

dropAround :: (a -> Bool) -> [a] -> [a]Source

groupSortOn :: Ord a => (k -> a) -> [(k, v)] -> [(k, [v])]Source

repeatedly :: ([a] -> (b, [a])) -> [a] -> [b]Source

Apply some operation repeatedly, producing an element of output and the remainder of the list.

\xs -> repeatedly (splitAt 3) xs == chunksOf 3 xs \xs -> repeatedly word1 (trim xs) == words xs

disjoint :: Eq a => [a] -> [a] -> BoolSource

Are two lists disjoint, with no elements in common.

disjoint [1,2,3] [4,5] == True disjoint [1,2,3] [4,1] == False

allSame :: Eq a => [a] -> BoolSource

Are all elements the same.

allSame [1,1,2] == False allSame [1,1,1] == True allSame [1] == True allSame [] == True

anySame :: Eq a => [a] -> BoolSource

Is there any element which occurs more than once.

anySame [1,1,2] == True anySame [1,2,3] == False

dropWhileEnd :: (a -> Bool) -> [a] -> [a]

The `dropWhileEnd`

function drops the largest suffix of a list
in which the given predicate holds for all elements. For example:

dropWhileEnd isSpace "foo\n" == "foo" dropWhileEnd isSpace "foo bar" == "foo bar" dropWhileEnd isSpace ("foo\n" ++ undefined) == "foo" ++ undefined

dropWhileEnd' :: (a -> Bool) -> [a] -> [a]Source

A version of `dropWhileEnd`

but with different strictness properties.
Often outperforms if the list is short or the test is expensive.

takeWhileEnd :: (a -> Bool) -> [a] -> [a]Source

stripSuffix :: Eq a => [a] -> [a] -> Maybe [a]Source

Return the prefix of the second string if its suffix matches the entire first string.

Examples:

stripSuffix "bar" "foobar" == Just "foo" stripSuffix "" "baz" == Just "baz" stripSuffix "foo" "quux" == Nothing

concatUnzip :: [([a], [b])] -> ([a], [b])Source

concatUnzip3 :: [([a], [b], [c])] -> ([a], [b], [c])Source

breakOn :: Eq a => [a] -> [a] -> ([a], [a])Source

Find the first instance of `needle`

in `haystack`

.
The first element of the returned tuple
is the prefix of `haystack`

before `needle`

is matched. The second
is the remainder of `haystack`

, starting with the match.

Examples:

breakOn "::" "a::b::c" == ("a", "::b::c") breakOn "/" "foobar" == ("foobar", "")

Laws:

\needle haystack -> let (prefix,match) = breakOn needle haystack in prefix ++ match == haystack

breakOnEnd :: Eq a => [a] -> [a] -> ([a], [a])Source

Similar to `breakOn`

, but searches from the end of the
string.

The first element of the returned tuple is the prefix of `haystack`

up to and including the last match of `needle`

. The second is the
remainder of `haystack`

, following the match.

breakOnEnd "::" "a::b::c" == ("a::b::", "c")

splitOn :: Eq a => [a] -> [a] -> [[a]]Source

Break a list into pieces separated by the first list argument, consuming the delimiter. An empty delimiter is invalid, and will cause an error to be raised.

Examples:

splitOn "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"] splitOn "aaa" "aaaXaaaXaaaXaaa" == ["","X","X","X",""] splitOn "x" "x" == ["",""] splitOn "x" "" == [""]

and

\s x -> s /= "" ==> intercalate s (splitOn s x) == x \c x -> splitOn [c] x == split (==c) x

split :: (a -> Bool) -> [a] -> [[a]]Source

Splits a list into components delimited by separators, where the predicate returns True for a separator element. The resulting components do not contain the separators. Two adjacent separators result in an empty component in the output. eg.

split (=='a') "aabbaca" == ["","","bb","c",""] split (=='a') "" == [""]

chunksOf :: Int -> [a] -> [[a]]Source

Split a list into chunks of a given size. The last chunk may contain fewer than n elements. The chunk size must be positive.

chunksOf 3 "my test" == ["my ","tes","t"] chunksOf 3 "mytest" == ["myt","est"] chunksOf 8 "" == [] chunksOf 0 "test" == error

# Data.Tuple.Extra

Extra functions available in `Data.Tuple.Extra`

.

# Numeric.Extra

Extra functions available in `Numeric.Extra`

.

showDP :: RealFloat a => Int -> a -> StringSource

Show a number to a number of decimal places.

showDP 4 pi == "3.1416" showDP 0 pi == "3" showDP 2 3 == "3.00"

intToDouble :: Int -> DoubleSource

Specialised numeric conversion.

intToFloat :: Int -> FloatSource

Specialised numeric conversion.

floatToDouble :: Float -> DoubleSource

Specialised numeric conversion.

doubleToFloat :: Double -> FloatSource

Specialised numeric conversion.

# System.Directory.Extra

Extra functions available in `System.Directory.Extra`

.

withCurrentDirectory :: FilePath -> IO a -> IO aSource

Remember that the current directory is a global variable, so calling this function multithreaded is almost certain to go wrong. Avoid changing the dir if you can.

getDirectoryContentsRecursive :: FilePath -> IO [FilePath]Source

Find all the files within a directory, including recursively.
Looks through all folders, including those beginning with `.`

.

createDirectoryPrivate :: String -> IO ()Source

Create a directory with permissions so that only the current user can view it.
On Windows this function is equivalent to `createDirectory`

.

# System.Environment.Extra

Extra functions available in `System.Environment.Extra`

.

getExecutablePath :: IO FilePath

Returns the absolute pathname of the current executable.

Note that for scripts and interactive sessions, this is the path to the interpreter (e.g. ghci.)

lookupEnv :: String -> IO (Maybe String)

Return the value of the environment variable `var`

, or `Nothing`

if
there is no such value.

For POSIX users, this is equivalent to `getEnv`

.

# System.Info.Extra

Extra functions available in `System.Info.Extra`

.

# System.IO.Extra

Extra functions available in `System.IO.Extra`

.

readFileEncoding :: TextEncoding -> FilePath -> IO StringSource

readFileUTF8 :: FilePath -> IO StringSource

readFileBinary :: FilePath -> IO StringSource

readFileEncoding' :: TextEncoding -> FilePath -> IO StringSource

readFileUTF8' :: FilePath -> IO StringSource

writeFileEncoding :: TextEncoding -> FilePath -> String -> IO ()Source

writeFileUTF8 :: FilePath -> String -> IO ()Source

writeFileBinary :: FilePath -> String -> IO ()Source

withTempFile :: (FilePath -> IO a) -> IO aSource

withTempDir :: (FilePath -> IO a) -> IO aSource

captureOutput :: IO a -> IO (String, a)Source

withBuffering :: Handle -> BufferMode -> IO a -> IO aSource

# System.Process.Extra

Extra functions available in `System.Process.Extra`

.

systemOutput_ :: String -> IO StringSource

# System.Time.Extra

Extra functions available in `System.Time.Extra`

.

subtractTime :: UTCTime -> UTCTime -> SecondsSource

showDuration :: Seconds -> StringSource

Show a number of seconds, typically a duration, in a suitable manner with responable precision for a human.

showDuration 3.435 == "3.44s" showDuration 623.8 == "10m24s" showDuration 62003.8 == "17h13m" showDuration 1e8 == "27777h47m"

offsetTime :: IO (IO Seconds)Source

Call once at the start, then call repeatedly to get Time values out

offsetTimeIncrease :: IO (IO Seconds)Source

Like offsetTime, but results will never decrease (though they may stay the same)