Extra

Deprecated: This module is provided as documentation of all new functions, you should import the more specific modules directly.

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).

Control.Concurrent.Extra

Extra functions available in Control.Concurrent.Extra.

getNumCapabilities :: IO Int

Returns the number of Haskell threads that can run truly simultaneously (on separate physical processors) at any given time. To change this value, use setNumCapabilities.

Since: base-4.4.0.0

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.

Since: base-4.5.0.0

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

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.

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.

Since: base-4.6.0.0

once :: IO a -> IO (IO a)

Given an action, produce a wrapped action that runs at most once. If the function raises an exception, the same exception will be reraised each time.

let x ||| y = do t1 <- onceFork x; t2 <- onceFork y; t1; t2
\(x :: IO Int) -> void (once x) == return ()
\(x :: IO Int) -> join (once x) == x
\(x :: IO Int) -> (do y <- once x; y; y) == x
\(x :: IO Int) -> (do y <- once x; y ||| y) == x

onceFork :: IO a -> IO (IO a)

Like once, but immediately starts running the computation on a background thread.

\(x :: IO Int) -> join (onceFork x) == x
\(x :: IO Int) -> (do a <- onceFork x; a; a) == x

data Lock

Like an MVar, but has no value. Used to guarantee single-threaded access, typically to some system resource. As an example:

lock <- newLock
let output = withLock . putStrLn
forkIO $ do ...; output "hello"
forkIO $ do ...; output "world"

Here we are creating a lock to ensure that when writing output our messages do not get interleaved. This use of MVar never blocks on a put. It is permissible, but rare, that a withLock contains a withLock inside it - but if so, watch out for deadlocks.

newLock :: IO Lock

Create a new Lock.

withLock :: Lock -> IO a -> IO a

Perform some operation while holding Lock. Will prevent all other operations from using the Lock while the action is ongoing.

withLockTry :: Lock -> IO a -> IO (Maybe a)

Like withLock but will never block. If the operation cannot be executed immediately it will return Nothing.

data Var a

Like an MVar, but must always be full. Used to operate on a mutable variable in a thread-safe way. As an example:

hits <- newVar 0
forkIO $ do ...; modifyVar_ hits (+1); ...
i <- readVar hits
print ("HITS",i)

Here we have a variable which we modify atomically, so modifications are not interleaved. This use of MVar never blocks on a put. No modifyVar operation should ever block, and they should always complete in a reasonable timeframe. A Var should not be used to protect some external resource, only the variable contained within. Information from a readVar should not be subsequently inserted back into the Var.

newVar :: a -> IO (Var a)

Create a new Var with a value.

readVar :: Var a -> IO a

Read the current value of the Var.

writeVar :: Var a -> a -> IO ()

Write a value to become the new value of Var.

modifyVar :: Var a -> (a -> IO (a, b)) -> IO b

Modify a Var producing a new value and a return result.

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

Modify a Var, a restricted version of modifyVar.

withVar :: Var a -> (a -> IO b) -> IO b

Perform some operation using the value in the Var, a restricted version of modifyVar.

data Barrier a

Starts out empty, then is filled exactly once. As an example:

bar <- newBarrier
forkIO $ do ...; val <- ...; signalBarrier bar val
print =<< waitBarrier bar

Here we create a barrier which will contain some computed value. A thread is forked to fill the barrier, while the main thread waits for it to complete. A barrier has similarities to a future or promise from other languages, has been known as an IVar in other Haskell work, and in some ways is like a manually managed thunk.

newBarrier :: IO (Barrier a)

Create a new Barrier.

signalBarrier :: Partial => Barrier a -> a -> IO ()

Write a value into the Barrier, releasing anyone at waitBarrier. Any subsequent attempts to signal the Barrier will throw an exception.

waitBarrier :: Barrier a -> IO a

Wait until a barrier has been signaled with signalBarrier.

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

A version of waitBarrier that never blocks, returning Nothing if the barrier has not yet been signaled.

Control.Exception.Extra

Extra functions available in Control.Exception.Extra.

type Partial = HasCallStack

A constraint which documents that a function is partial, and on GHC 8.0 and above produces a stack trace on failure. For example:

myHead :: Partial => [a] -> a
myHead [] = error "bad"
myHead (x:xs) = x

When using Partial with GHC 7.8 or below you need to enable the language feature ConstraintKinds, e.g. {-# LANGUAGE ConstraintKinds #-} at the top of the file.

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

Retry an operation at most n times (n must be positive). If the operation fails the nth time it will throw that final exception.

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

retryBool :: Exception e => (e -> Bool) -> Int -> IO a -> IO a

Retry an operation at most n times (n must be positive), while the exception value and type match a predicate. If the operation fails the nth time it will throw that final exception.

errorWithoutStackTrace :: [Char] -> a

A variant of error that does not produce a stack trace.

Since: base-4.9.0.0

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

Show a value, but if the result contains exceptions, produce <Exception>. Defined as stringException . show. Particularly useful for printing exceptions to users, remembering that exceptions can themselves contain undefined values.

stringException :: String -> IO String

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

stringException "test"                           == return "test"
stringException ("test" ++ undefined)            == return "test<Exception>"
stringException ("test" ++ undefined ++ "hello") == return "test<Exception>"
stringException ['t','e','s','t',undefined]      == return "test<Exception>"

errorIO :: Partial => String -> IO a

Like error, but in the IO monad. Note that while fail in IO raises an IOException, this function raises an ErrorCall exception.

try (errorIO "Hello") == return (Left (ErrorCall "Hello"))

displayException :: Exception e => e -> String

Render this exception value in a human-friendly manner.

Default implementation: show.

Since: base-4.8.0.0

ignore :: IO () -> IO ()

Ignore any exceptions thrown by the action.

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

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

A version of catch without the Exception context, restricted to SomeException, so catches all exceptions.

handle_ :: (SomeException -> IO a) -> IO a -> IO a

Like catch_ but for handle

try_ :: IO a -> IO (Either SomeException a)

Like catch_ but for try

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

Like catch_ but for catchJust

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

Like catch_ but for handleJust

tryJust_ :: (SomeException -> Maybe b) -> IO a -> IO (Either b a)

Like catch_ but for tryJust

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

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 "")

handleBool :: Exception e => (e -> Bool) -> (e -> IO a) -> IO a -> IO a

Like catchBool but for handle.

tryBool :: Exception e => (e -> Bool) -> IO a -> IO (Either e a)

Like catchBool but for try.

Control.Monad.Extra

Extra functions available in Control.Monad.Extra.

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

Perform some operation on Just, given the field inside the Just.

whenJust Nothing  print == return ()
whenJust (Just 1) print == print 1

whenJustM :: Monad m => m (Maybe a) -> (a -> m ()) -> m ()

Like whenJust, but where the test can be monadic.

whenMaybe :: Applicative m => Bool -> m a -> m (Maybe a)

Like when, but return either Nothing if the predicate was False, of Just with the result of the computation.

whenMaybe True  (print 1) == fmap Just (print 1)
whenMaybe False (print 1) == return Nothing

whenMaybeM :: Monad m => m Bool -> m a -> m (Maybe a)

Like whenMaybe, but where the test can be monadic.

unit :: m () -> m ()

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

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

maybeM :: Monad m => m b -> (a -> m b) -> m (Maybe a) -> m b

Monadic generalisation of maybe.

eitherM :: Monad m => (a -> m c) -> (b -> m c) -> m (Either a b) -> m c

Monadic generalisation of either.

loop :: (a -> Either a b) -> a -> b

A looping operation, where the predicate returns Left as a seed for the next loop or Right to abort the loop.

loop (\x -> if x < 10 then Left $ x * 2 else Right $ show x) 1 == "16"

loopM :: Monad m => (a -> m (Either a b)) -> a -> m b

A monadic version of loop, where the predicate returns Left as a seed for the next loop or Right to abort the loop.

whileM :: Monad m => m Bool -> m ()

Keep running an operation until it becomes False. As an example:

whileM $ do sleep 0.1; notM $ doesFileExist "foo.txt"
readFile "foo.txt"

If you need some state persisted between each test, use loopM.

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

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]

A version of concatMap that works with a monadic predicate.

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

Like concatMapM, but has its arguments flipped, so can be used instead of the common fmap concat $ forM pattern.

mconcatMapM :: (Monad m, Monoid b) => (a -> m b) -> [a] -> m b

A version of mconcatMap that works with a monadic predicate.

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

A version of mapMaybe that works with a monadic predicate.

findM :: Monad m => (a -> m Bool) -> [a] -> m (Maybe a)

Like find, but where the test can be monadic.

findM (Just . isUpper) "teST"             == Just (Just 'S')
findM (Just . isUpper) "test"             == Just Nothing
findM (Just . const True) ["x",undefined] == Just (Just "x")

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

Like findM, but also allows you to compute some additional information in the predicate.

fold1M :: (Partial, Monad m) => (a -> a -> m a) -> [a] -> m a

A variant of foldM that has no base case, and thus may only be applied to non-empty lists.

fold1M (\x y -> Just x) [] == undefined
fold1M (\x y -> Just $ x + y) [1, 2, 3] == Just 6

fold1M_ :: (Partial, Monad m) => (a -> a -> m a) -> [a] -> m ()

Like fold1M but discards the result.

whenM :: Monad m => m Bool -> m () -> m ()

Like when, but where the test can be monadic.

unlessM :: Monad m => m Bool -> m () -> m ()

Like unless, but where the test can be monadic.

ifM :: Monad m => m Bool -> m a -> m a -> m a

Like if, but where the test can be monadic.

notM :: Functor m => m Bool -> m Bool

Like not, but where the test can be monadic.

(||^) :: Monad m => m Bool -> m Bool -> m Bool

The lazy || operator lifted to a monad. If the first argument evaluates to True the second argument will not be evaluated.

Just True  ||^ undefined  == Just True
Just False ||^ Just True  == Just True
Just False ||^ Just False == Just False

(&&^) :: Monad m => m Bool -> m Bool -> m Bool

The lazy && operator lifted to a monad. If the first argument evaluates to False the second argument will not be evaluated.

Just False &&^ undefined  == Just False
Just True  &&^ Just True  == Just True
Just True  &&^ Just False == Just False

orM :: Monad m => [m Bool] -> m Bool

A version of or lifted to a monad. Retains the short-circuiting behaviour.

orM [Just False,Just True ,undefined] == Just True
orM [Just False,Just False,undefined] == undefined
\xs -> Just (or xs) == orM (map Just xs)

andM :: Monad m => [m Bool] -> m Bool

A version of and lifted to a monad. Retains the short-circuiting behaviour.

andM [Just True,Just False,undefined] == Just False
andM [Just True,Just True ,undefined] == undefined
\xs -> Just (and xs) == andM (map Just xs)

anyM :: Monad m => (a -> m Bool) -> [a] -> m Bool

A version of any lifted to a monad. Retains the short-circuiting behaviour.

anyM Just [False,True ,undefined] == Just True
anyM Just [False,False,undefined] == undefined
\(f :: Int -> Maybe Bool) xs -> anyM f xs == orM (map f xs)

allM :: Monad m => (a -> m Bool) -> [a] -> m Bool

A version of all lifted to a monad. Retains the short-circuiting behaviour.

allM Just [True,False,undefined] == Just False
allM Just [True,True ,undefined] == undefined
\(f :: Int -> Maybe Bool) xs -> anyM f xs == orM (map f xs)

Data.Either.Extra

Extra functions available in Data.Either.Extra.

isLeft :: Either a b -> Bool

Return True if the given value is a Left-value, False otherwise.

Examples

Basic usage:

>>> isLeft (Left "foo")
True
>>> isLeft (Right 3)
False

Assuming a Left value signifies some sort of error, we can use isLeft to write a very simple error-reporting function that does absolutely nothing in the case of success, and outputs "ERROR" if any error occurred.

This example shows how isLeft might be used to avoid pattern matching when one does not care about the value contained in the constructor:

>>> import Control.Monad ( when )
>>> let report e = when (isLeft e) $ putStrLn "ERROR"
>>> report (Right 1)
>>> report (Left "parse error")
ERROR

Since: base-4.7.0.0

isRight :: Either a b -> Bool

Return True if the given value is a Right-value, False otherwise.

Examples

Basic usage:

>>> isRight (Left "foo")
False
>>> isRight (Right 3)
True

Assuming a Left value signifies some sort of error, we can use isRight to write a very simple reporting function that only outputs "SUCCESS" when a computation has succeeded.

This example shows how isRight might be used to avoid pattern matching when one does not care about the value contained in the constructor:

>>> import Control.Monad ( when )
>>> let report e = when (isRight e) $ putStrLn "SUCCESS"
>>> report (Left "parse error")
>>> report (Right 1)
SUCCESS

Since: base-4.7.0.0

fromLeft :: a -> Either a b -> a

Return the contents of a Left-value or a default value otherwise.

Examples

Basic usage:

>>> fromLeft 1 (Left 3)
3
>>> fromLeft 1 (Right "foo")
1

Since: base-4.10.0.0

fromRight :: b -> Either a b -> b

Return the contents of a Right-value or a default value otherwise.

Examples

Basic usage:

>>> fromRight 1 (Right 3)
3
>>> fromRight 1 (Left "foo")
1

Since: base-4.10.0.0

fromEither :: Either a a -> a

Pull the value out of an Either where both alternatives have the same type.

\x -> fromEither (Left x ) == x
\x -> fromEither (Right x) == x

fromLeft' :: Partial => Either l r -> l

The fromLeft' function extracts the element out of a Left and throws an error if its argument is Right. Much like fromJust, using this function in polished code is usually a bad idea.

\x -> fromLeft' (Left  x) == x
\x -> fromLeft' (Right x) == undefined

fromRight' :: Partial => Either l r -> r

The fromRight' function extracts the element out of a Right and throws an error if its argument is Left. Much like fromJust, using this function in polished code is usually a bad idea.

\x -> fromRight' (Right x) == x
\x -> fromRight' (Left  x) == undefined

eitherToMaybe :: Either a b -> Maybe b

Given an Either, convert it to a Maybe, where Left becomes Nothing.

\x -> eitherToMaybe (Left x) == Nothing
\x -> eitherToMaybe (Right x) == Just x

maybeToEither :: a -> Maybe b -> Either a b

Given a Maybe, convert it to an Either, providing a suitable value for the Left should the value be Nothing.

\a b -> maybeToEither a (Just b) == Right b
\a -> maybeToEither a Nothing == Left a

Data.IORef.Extra

Extra functions available in Data.IORef.Extra.

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

Strict version of modifyIORef

Since: base-4.6.0.0

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

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.

Since: base-4.6.0.0

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

Variant of writeIORef with the "barrier to reordering" property that atomicModifyIORef has.

Since: base-4.6.0.0

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

Evaluates the value before calling atomicWriteIORef.

Data.List.Extra

Extra functions available in Data.List.Extra.

lower :: String -> String

Convert a string to lower case.

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

upper :: String -> String

Convert a string to upper case.

upper "This is A TEST" == "THIS IS A TEST"
upper "" == ""

trim :: String -> String

Remove spaces from either side of a string. A combination of trimEnd and trimStart.

trim      "  hello   " == "hello"
trimStart "  hello   " == "hello   "
trimEnd   "  hello   " == "  hello"
\s -> trim s == trimEnd (trimStart s)

trimStart :: String -> String

Remove spaces from the start of a string, see trim.

trimEnd :: String -> String

Remove spaces from the end of a string, see trim.

word1 :: String -> (String, String)

Split the first word off a string. Useful for when starting to parse the beginning of a string, but you want to accurately preserve whitespace in the rest of the string.

word1 "" == ("", "")
word1 "keyword rest of string" == ("keyword","rest of string")
word1 "  keyword\n  rest of string" == ("keyword","rest of string")
\s -> fst (word1 s) == concat (take 1 $ words s)
\s -> words (snd $ word1 s) == drop 1 (words s)

line1 :: String -> (String, String)

Split the first line off a string.

line1 "" == ("", "")
line1 "test" == ("test","")
line1 "test\n" == ("test","")
line1 "test\nrest" == ("test","rest")
line1 "test\nrest\nmore" == ("test","rest\nmore")

escapeHTML :: String -> String

Escape a string such that it can be inserted into an HTML document or " attribute without any special interpretation. This requires escaping the <, >, & and " characters. Note that it will escape " and ' even though that is not required in an HTML body (but is not harmful).

escapeHTML "this is a test" == "this is a test"
escapeHTML "<b>\"g&t\"</n>" == "&lt;b&gt;&quot;g&amp;t&quot;&lt;/n&gt;"
escapeHTML "t'was another test" == "t&#39;was another test"

escapeJSON :: String -> String

Escape a string so it can form part of a JSON literal. This requires escaping the special whitespace and control characters. Additionally, Note that it does not add quote characters around the string.

escapeJSON "this is a test" == "this is a test"
escapeJSON "\ttab\nnewline\\" == "\\ttab\\nnewline\\\\"
escapeJSON "\ESC[0mHello" == "\\u001b[0mHello"

unescapeHTML :: String -> String

Invert of escapeHTML (does not do general HTML unescaping)

\xs -> unescapeHTML (escapeHTML xs) == xs

unescapeJSON :: String -> String

General JSON unescaping, inversion of escapeJSON and all other JSON escapes.

\xs -> unescapeJSON (escapeJSON xs) == xs

dropEnd :: Int -> [a] -> [a]

Drop a number of elements from the end of the list.

dropEnd 3 "hello"  == "he"
dropEnd 5 "bye"    == ""
dropEnd (-1) "bye" == "bye"
\i xs -> dropEnd i xs `isPrefixOf` xs
\i xs -> length (dropEnd i xs) == max 0 (length xs - max 0 i)
\i -> take 3 (dropEnd 5 [i..]) == take 3 [i..]

takeEnd :: Int -> [a] -> [a]

Take a number of elements from the end of the list.

takeEnd 3 "hello"  == "llo"
takeEnd 5 "bye"    == "bye"
takeEnd (-1) "bye" == ""
\i xs -> takeEnd i xs `isSuffixOf` xs
\i xs -> length (takeEnd i xs) == min (max 0 i) (length xs)

splitAtEnd :: Int -> [a] -> ([a], [a])

splitAtEnd n xs returns a split where the second element tries to contain n elements.

splitAtEnd 3 "hello" == ("he","llo")
splitAtEnd 3 "he"    == ("", "he")
\i xs -> uncurry (++) (splitAt i xs) == xs
\i xs -> splitAtEnd i xs == (dropEnd i xs, takeEnd i xs)

breakEnd :: (a -> Bool) -> [a] -> ([a], [a])

Break, but from the end.

breakEnd isLower "youRE" == ("you","RE")
breakEnd isLower "youre" == ("youre","")
breakEnd isLower "YOURE" == ("","YOURE")
\f xs -> breakEnd (not . f) xs == spanEnd f  xs

spanEnd :: (a -> Bool) -> [a] -> ([a], [a])

Span, but from the end.

spanEnd isUpper "youRE" == ("you","RE")
spanEnd (not . isSpace) "x y z" == ("x y ","z")
\f xs -> uncurry (++) (spanEnd f xs) == xs
\f xs -> spanEnd f xs == swap (both reverse (span f (reverse xs)))

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

Since: base-4.5.0.0

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

A version of dropWhileEnd but with different strictness properties. The function dropWhileEnd can be used on an infinite list and tests the property on each character. In contrast, dropWhileEnd' is strict in the spine of the list but only tests the trailing suffix. This version usually outperforms dropWhileEnd if the list is short or the test is expensive. Note the tests below cover both the prime and non-prime variants.

dropWhileEnd  isSpace "ab cde  " == "ab cde"
dropWhileEnd' isSpace "ab cde  " == "ab cde"
last (dropWhileEnd  even [undefined,3]) == undefined
last (dropWhileEnd' even [undefined,3]) == 3
head (dropWhileEnd  even (3:undefined)) == 3
head (dropWhileEnd' even (3:undefined)) == undefined

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

A version of takeWhile operating from the end.

takeWhileEnd even [2,3,4,6] == [4,6]

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

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

Examples:

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

stripInfix :: Eq a => [a] -> [a] -> Maybe ([a], [a])

Return the the string before and after the search string, or Nothing if the search string is not present.

Examples:

stripInfix "::" "a::b::c" == Just ("a", "b::c")
stripInfix "/" "foobar"   == Nothing

stripInfixEnd :: Eq a => [a] -> [a] -> Maybe ([a], [a])

Similar to stripInfix, but searches from the end of the string.

stripInfixEnd "::" "a::b::c" == Just ("a::b", "c")

dropPrefix :: Eq a => [a] -> [a] -> [a]

Drops the given prefix from a list. It returns the original sequence if the sequence doesn't start with the given prefix.

dropPrefix "Mr. " "Mr. Men" == "Men"
dropPrefix "Mr. " "Dr. Men" == "Dr. Men"

dropSuffix :: Eq a => [a] -> [a] -> [a]

Drops the given suffix from a list. It returns the original sequence if the sequence doesn't end with the given suffix.

dropSuffix "!" "Hello World!"  == "Hello World"
dropSuffix "!" "Hello World!!" == "Hello World!"
dropSuffix "!" "Hello World."  == "Hello World."

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

A variant of words with a custom test. In particular, adjacent separators are discarded, as are leading or trailing separators.

wordsBy (== ':') "::xyz:abc::123::" == ["xyz","abc","123"]
\s -> wordsBy isSpace s == words s

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

A variant of lines with a custom test. In particular, if there is a trailing separator it will be discarded.

linesBy (== ':') "::xyz:abc::123::" == ["","","xyz","abc","","123",""]
\s -> linesBy (== '\n') s == lines s
linesBy (== ';') "my;list;here;" == ["my","list","here"]

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

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. If you want the remainder without the match, use stripInfix.

breakOn "::" "a::b::c" == ("a", "::b::c")
breakOn "/" "foobar"   == ("foobar", "")
\needle haystack -> let (prefix,match) = breakOn needle haystack in prefix ++ match == haystack

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

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 :: (Partial, Eq a) => [a] -> [a] -> [[a]]

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.

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"    ""                 == [""]
\s x -> s /= "" ==> intercalate s (splitOn s x) == x
\c x -> splitOn [c] x                           == split (==c) x

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

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.

split (== 'a') "aabbaca" == ["","","bb","c",""]
split (== 'a') ""        == [""]
split (== ':') "::xyz:abc::123::" == ["","","xyz","abc","","123","",""]
split (== ',') "my,list,here" == ["my","list","here"]

chunksOf :: Partial => Int -> [a] -> [[a]]

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"    == undefined

notNull :: [a] -> Bool

A composition of not and null.

notNull []  == False
notNull [1] == True
\xs -> notNull xs == not (null xs)

list :: b -> (a -> [a] -> b) -> [a] -> b

Non-recursive transform over a list, like maybe.

list 1 (\v _ -> v - 2) [5,6,7] == 3
list 1 (\v _ -> v - 2) []      == 1
\nil cons xs -> maybe nil (uncurry cons) (uncons xs) == list nil cons xs

uncons :: [a] -> Maybe (a, [a])

Decompose a list into its head and tail. If the list is empty, returns Nothing. If the list is non-empty, returns Just (x, xs), where x is the head of the list and xs its tail.

Since: base-4.8.0.0

unsnoc :: [a] -> Maybe ([a], a)

If the list is empty returns Nothing, otherwise returns the init and the last.

unsnoc "test" == Just ("tes",'t')
unsnoc ""     == Nothing
\xs -> unsnoc xs == if null xs then Nothing else Just (init xs, last xs)

cons :: a -> [a] -> [a]

Append an element to the start of a list, an alias for '(:)'.

cons 't' "est" == "test"
\x xs -> uncons (cons x xs) == Just (x,xs)

snoc :: [a] -> a -> [a]

Append an element to the end of a list, takes O(n) time.

snoc "tes" 't' == "test"
\xs x -> unsnoc (snoc xs x) == Just (xs,x)

drop1 :: [a] -> [a]

Equivalent to drop 1, but likely to be faster and a single lexeme.

drop1 ""         == ""
drop1 "test"     == "est"
\xs -> drop 1 xs == drop1 xs

mconcatMap :: Monoid b => (a -> b) -> [a] -> b

Version on concatMap generalised to a Monoid rather than just a list.

mconcatMap Sum [1,2,3] == Sum 6
\f xs -> mconcatMap f xs == concatMap f xs

groupSort :: Ord k => [(k, v)] -> [(k, [v])]

A combination of group and sort.

groupSort [(1,'t'),(3,'t'),(2,'e'),(2,'s')] == [(1,"t"),(2,"es"),(3,"t")]
\xs -> map fst (groupSort xs) == sort (nub (map fst xs))
\xs -> concatMap snd (groupSort xs) == map snd (sortOn fst xs)

groupSortOn :: Ord b => (a -> b) -> [a] -> [[a]]

A combination of group and sort, using a part of the value to compare on.

groupSortOn length ["test","of","sized","item"] == [["of"],["test","item"],["sized"]]

groupSortBy :: (a -> a -> Ordering) -> [a] -> [[a]]

A combination of group and sort, using a predicate to compare on.

groupSortBy (compare `on` length) ["test","of","sized","item"] == [["of"],["test","item"],["sized"]]

nubOrd :: Ord a => [a] -> [a]

O(n log n). The nubOrd function removes duplicate elements from a list. In particular, it keeps only the first occurrence of each element. Unlike the standard nub operator, this version requires an Ord instance and consequently runs asymptotically faster.

nubOrd "this is a test" == "this ae"
nubOrd (take 4 ("this" ++ undefined)) == "this"
\xs -> nubOrd xs == nub xs

nubOrdBy :: (a -> a -> Ordering) -> [a] -> [a]

A version of nubOrd with a custom predicate.

nubOrdBy (compare `on` length) ["a","test","of","this"] == ["a","test","of"]

nubOrdOn :: Ord b => (a -> b) -> [a] -> [a]

A version of nubOrd which operates on a portion of the value.

nubOrdOn length ["a","test","of","this"] == ["a","test","of"]

nubOn :: Eq b => (a -> b) -> [a] -> [a]

A version of nub where the equality is done on some extracted value. nubOn f is equivalent to nubBy ((==) on f), but has the performance advantage of only evaluating f once for each element in the input list.

groupOn :: Eq b => (a -> b) -> [a] -> [[a]]

A version of group where the equality is done on some extracted value.

sortOn :: Ord b => (a -> b) -> [a] -> [a]

Sort a list by comparing the results of a key function applied to each element. sortOn f is equivalent to sortBy (comparing f), but has the performance advantage of only evaluating f once for each element in the input list. This is called the decorate-sort-undecorate paradigm, or Schwartzian transform.

Elements are arranged from from lowest to highest, keeping duplicates in the order they appeared in the input.

>>> sortOn fst [(2, "world"), (4, "!"), (1, "Hello")]
[(1,"Hello"),(2,"world"),(4,"!")]

Since: base-4.8.0.0

nubSort :: Ord a => [a] -> [a]

O(n log n). The nubSort function sorts and removes duplicate elements from a list. In particular, it keeps only the first occurrence of each element.

nubSort "this is a test" == " aehist"
\xs -> nubSort xs == nub (sort xs)

nubSortBy :: (a -> a -> Ordering) -> [a] -> [a]

A version of nubSort with a custom predicate.

nubSortBy (compare `on` length) ["a","test","of","this"] == ["a","of","test"]

nubSortOn :: Ord b => (a -> b) -> [a] -> [a]

A version of nubSort which operates on a portion of the value.

nubSortOn length ["a","test","of","this"] == ["a","of","test"]

maximumOn :: Ord b => (a -> b) -> [a] -> a

A version of maximum where the comparison is done on some extracted value.

minimumOn :: Ord b => (a -> b) -> [a] -> a

A version of minimum where the comparison is done on some extracted value.

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

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] -> Bool

Are all elements the same.

allSame [1,1,2] == False
allSame [1,1,1] == True
allSame [1]     == True
allSame []      == True
allSame (1:1:2:undefined) == False
\xs -> allSame xs == (length (nub xs) <= 1)

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

Is there any element which occurs more than once.

anySame [1,1,2] == True
anySame [1,2,3] == False
anySame (1:2:1:undefined) == True
anySame [] == False
\xs -> anySame xs == (length (nub xs) < length xs)

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

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
\xs -> repeatedly line1 xs == lines xs

for :: [a] -> (a -> b) -> [b]

Flipped version of map.

for [1,2,3] (+1) == [2,3,4]

firstJust :: (a -> Maybe b) -> [a] -> Maybe b

Find the first element of a list for which the operation returns Just, along with the result of the operation. Like find but useful where the function also computes some expensive information that can be reused. Particular useful when the function is monadic, see firstJustM.

firstJust id [Nothing,Just 3]  == Just 3
firstJust id [Nothing,Nothing] == Nothing

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

A merging of unzip and concat.

concatUnzip [("a","AB"),("bc","C")] == ("abc","ABC")

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

A merging of unzip3 and concat.

concatUnzip3 [("a","AB",""),("bc","C","123")] == ("abc","ABC","123")

zipFrom :: (Partial, Enum a) => a -> [b] -> [(a, b)]

zip against an enumeration. Never truncates the output - raises an error if the enumeration runs out.

\i xs -> zip [i..] xs == zipFrom i xs
zipFrom False [1..3] == undefined

zipWithFrom :: (Partial, Enum a) => (a -> b -> c) -> a -> [b] -> [c]

zipFrom generalised to any combining operation. Never truncates the output - raises an error if the enumeration runs out.

\i xs -> zipWithFrom (,) i xs == zipFrom i xs

replace :: (Partial, Eq a) => [a] -> [a] -> [a] -> [a]

Replace a subsequence everywhere it occurs. The first argument must not be the empty list.

replace "el" "_" "Hello Bella" == "H_lo B_la"
replace "el" "e" "Hello"       == "Helo"
replace "" "e" "Hello"         == undefined
\xs ys -> not (null xs) ==> replace xs xs ys == ys

merge :: Ord a => [a] -> [a] -> [a]

Merge two lists which are assumed to be ordered.

merge "ace" "bd" == "abcde"
\xs ys -> merge (sort xs) (sort ys) == sort (xs ++ ys)

mergeBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]

Like merge, but with a custom ordering function.

Data.Tuple.Extra

Extra functions available in Data.Tuple.Extra.

first :: (a -> a') -> (a, b) -> (a', b)

Update the first component of a pair.

first succ (1,"test") == (2,"test")

second :: (b -> b') -> (a, b) -> (a, b')

Update the second component of a pair.

second reverse (1,"test") == (1,"tset")

(***) :: (a -> a') -> (b -> b') -> (a, b) -> (a', b') infixr 3

Given two functions, apply one to the first component and one to the second. A specialised version of ***.

(succ *** reverse) (1,"test") == (2,"tset")

(&&&) :: (a -> b) -> (a -> c) -> a -> (b, c) infixr 3

Given two functions, apply both to a single argument to form a pair. A specialised version of &&&.

(succ &&& pred) 1 == (2,0)

dupe :: a -> (a, a)

Duplicate a single value into a pair.

dupe 12 == (12, 12)

both :: (a -> b) -> (a, a) -> (b, b)

Apply a single function to both components of a pair.

both succ (1,2) == (2,3)

fst3 :: (a, b, c) -> a

Extract the fst of a triple.

snd3 :: (a, b, c) -> b

Extract the snd of a triple.

thd3 :: (a, b, c) -> c

Extract the final element of a triple.

Data.Typeable.Extra

Extra functions available in Data.Typeable.Extra.

typeRep :: Typeable a => proxy a -> TypeRep

Takes a value of type a and returns a concrete representation of that type.

Since: base-4.7.0.0

data (a :: k) :~: (b :: k) :: forall k. k -> k -> * where infix 4

Propositional equality. If a :~: b is inhabited by some terminating value, then the type a is the same as the type b. To use this equality in practice, pattern-match on the a :~: b to get out the Refl constructor; in the body of the pattern-match, the compiler knows that a ~ b.

Since: base-4.7.0.0

Constructors

Refl :: a :~: a

Instances

TestEquality ((:~:) a :: k -> *)

Since: base-4.7.0.0

Defined in Data.Type.Equality

Methods

testEquality :: (a :~: a0) -> (a :~: b) -> Maybe (a0 :~: b)

a ~ b => Bounded (a :~: b)

Since: base-4.7.0.0

Defined in Data.Type.Equality

Methods

minBound :: a :~: b

maxBound :: a :~: b

a ~ b => Enum (a :~: b)

Since: base-4.7.0.0

Defined in Data.Type.Equality

Methods

succ :: (a :~: b) -> a :~: b

pred :: (a :~: b) -> a :~: b

toEnum :: Int -> a :~: b

fromEnum :: (a :~: b) -> Int

enumFrom :: (a :~: b) -> [a :~: b]

enumFromThen :: (a :~: b) -> (a :~: b) -> [a :~: b]

enumFromTo :: (a :~: b) -> (a :~: b) -> [a :~: b]

enumFromThenTo :: (a :~: b) -> (a :~: b) -> (a :~: b) -> [a :~: b]

Eq (a :~: b)

Defined in Data.Type.Equality

Methods

(==) :: (a :~: b) -> (a :~: b) -> Bool

(/=) :: (a :~: b) -> (a :~: b) -> Bool

Ord (a :~: b)

Defined in Data.Type.Equality

Methods

compare :: (a :~: b) -> (a :~: b) -> Ordering

(<) :: (a :~: b) -> (a :~: b) -> Bool

(<=) :: (a :~: b) -> (a :~: b) -> Bool

(>) :: (a :~: b) -> (a :~: b) -> Bool

(>=) :: (a :~: b) -> (a :~: b) -> Bool

max :: (a :~: b) -> (a :~: b) -> a :~: b

min :: (a :~: b) -> (a :~: b) -> a :~: b

a ~ b => Read (a :~: b)

Since: base-4.7.0.0

Defined in Data.Type.Equality

Methods

readsPrec :: Int -> ReadS (a :~: b)

readList :: ReadS [a :~: b]

readPrec :: ReadPrec (a :~: b)

readListPrec :: ReadPrec [a :~: b]

Show (a :~: b)

Defined in Data.Type.Equality

Methods

showsPrec :: Int -> (a :~: b) -> ShowS

show :: (a :~: b) -> String

showList :: [a :~: b] -> ShowS

data Proxy (t :: k) :: forall k. k -> *

Proxy is a type that holds no data, but has a phantom parameter of arbitrary type (or even kind). Its use is to provide type information, even though there is no value available of that type (or it may be too costly to create one).

Historically, Proxy :: Proxy a is a safer alternative to the 'undefined :: a' idiom.

>>> Proxy :: Proxy (Void, Int -> Int)
Proxy

Proxy can even hold types of higher kinds,

>>> Proxy :: Proxy Either
Proxy

>>> Proxy :: Proxy Functor
Proxy

>>> Proxy :: Proxy complicatedStructure
Proxy

Constructors

Proxy

Instances

Generic1 (Proxy :: k -> *)

Defined in GHC.Generics

Associated Types

type Rep1 Proxy :: k -> *

Methods

from1 :: Proxy a -> Rep1 Proxy a

to1 :: Rep1 Proxy a -> Proxy a

Monad (Proxy :: * -> *)

Since: base-4.7.0.0

Defined in Data.Proxy

Methods

(>>=) :: Proxy a -> (a -> Proxy b) -> Proxy b

(>>) :: Proxy a -> Proxy b -> Proxy b

return :: a -> Proxy a

fail :: String -> Proxy a

Functor (Proxy :: * -> *)

Since: base-4.7.0.0

Defined in Data.Proxy

Methods

fmap :: (a -> b) -> Proxy a -> Proxy b

(<$) :: a -> Proxy b -> Proxy a

Applicative (Proxy :: * -> *)

Since: base-4.7.0.0

Defined in Data.Proxy

Methods

pure :: a -> Proxy a

(<*>) :: Proxy (a -> b) -> Proxy a -> Proxy b

liftA2 :: (a -> b -> c) -> Proxy a -> Proxy b -> Proxy c

(*>) :: Proxy a -> Proxy b -> Proxy b

(<*) :: Proxy a -> Proxy b -> Proxy a

Foldable (Proxy :: * -> *)

Since: base-4.7.0.0

Defined in Data.Foldable

Methods

fold :: Monoid m => Proxy m -> m

foldMap :: Monoid m => (a -> m) -> Proxy a -> m

foldr :: (a -> b -> b) -> b -> Proxy a -> b

foldr' :: (a -> b -> b) -> b -> Proxy a -> b

foldl :: (b -> a -> b) -> b -> Proxy a -> b

foldl' :: (b -> a -> b) -> b -> Proxy a -> b

foldr1 :: (a -> a -> a) -> Proxy a -> a

foldl1 :: (a -> a -> a) -> Proxy a -> a

toList :: Proxy a -> [a]

null :: Proxy a -> Bool

length :: Proxy a -> Int

elem :: Eq a => a -> Proxy a -> Bool

maximum :: Ord a => Proxy a -> a

minimum :: Ord a => Proxy a -> a

sum :: Num a => Proxy a -> a

product :: Num a => Proxy a -> a

Traversable (Proxy :: * -> *)

Since: base-4.7.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Proxy a -> f (Proxy b)

sequenceA :: Applicative f => Proxy (f a) -> f (Proxy a)

mapM :: Monad m => (a -> m b) -> Proxy a -> m (Proxy b)

sequence :: Monad m => Proxy (m a) -> m (Proxy a)

Alternative (Proxy :: * -> *)

Since: base-4.9.0.0

Defined in Data.Proxy

Methods

empty :: Proxy a

(<|>) :: Proxy a -> Proxy a -> Proxy a

some :: Proxy a -> Proxy [a]

many :: Proxy a -> Proxy [a]

MonadPlus (Proxy :: * -> *)

Since: base-4.9.0.0

Defined in Data.Proxy

Methods

mzero :: Proxy a

mplus :: Proxy a -> Proxy a -> Proxy a

Bounded (Proxy t)

Defined in Data.Proxy

Methods

minBound :: Proxy t

maxBound :: Proxy t

Enum (Proxy s)

Since: base-4.7.0.0

Defined in Data.Proxy

Methods

succ :: Proxy s -> Proxy s

pred :: Proxy s -> Proxy s

toEnum :: Int -> Proxy s

fromEnum :: Proxy s -> Int

enumFrom :: Proxy s -> [Proxy s]

enumFromThen :: Proxy s -> Proxy s -> [Proxy s]

enumFromTo :: Proxy s -> Proxy s -> [Proxy s]

enumFromThenTo :: Proxy s -> Proxy s -> Proxy s -> [Proxy s]

Eq (Proxy s)

Since: base-4.7.0.0

Defined in Data.Proxy

Methods

(==) :: Proxy s -> Proxy s -> Bool

(/=) :: Proxy s -> Proxy s -> Bool

Ord (Proxy s)

Since: base-4.7.0.0

Defined in Data.Proxy

Methods

compare :: Proxy s -> Proxy s -> Ordering

(<) :: Proxy s -> Proxy s -> Bool

(<=) :: Proxy s -> Proxy s -> Bool

(>) :: Proxy s -> Proxy s -> Bool

(>=) :: Proxy s -> Proxy s -> Bool

max :: Proxy s -> Proxy s -> Proxy s

min :: Proxy s -> Proxy s -> Proxy s

Read (Proxy t)

Since: base-4.7.0.0

Defined in Data.Proxy

Methods

readsPrec :: Int -> ReadS (Proxy t)

readList :: ReadS [Proxy t]

readPrec :: ReadPrec (Proxy t)

readListPrec :: ReadPrec [Proxy t]

Show (Proxy s)

Since: base-4.7.0.0

Defined in Data.Proxy

Methods

showsPrec :: Int -> Proxy s -> ShowS

show :: Proxy s -> String

showList :: [Proxy s] -> ShowS

Ix (Proxy s)

Since: base-4.7.0.0

Defined in Data.Proxy

Methods

range :: (Proxy s, Proxy s) -> [Proxy s]

index :: (Proxy s, Proxy s) -> Proxy s -> Int

unsafeIndex :: (Proxy s, Proxy s) -> Proxy s -> Int

inRange :: (Proxy s, Proxy s) -> Proxy s -> Bool

rangeSize :: (Proxy s, Proxy s) -> Int

unsafeRangeSize :: (Proxy s, Proxy s) -> Int

Generic (Proxy t)

Defined in GHC.Generics

Associated Types

type Rep (Proxy t) :: * -> *

Methods

from :: Proxy t -> Rep (Proxy t) x

to :: Rep (Proxy t) x -> Proxy t

Semigroup (Proxy s)

Since: base-4.9.0.0

Defined in Data.Proxy

Methods

(<>) :: Proxy s -> Proxy s -> Proxy s

sconcat :: NonEmpty (Proxy s) -> Proxy s

stimes :: Integral b => b -> Proxy s -> Proxy s

Monoid (Proxy s)

Since: base-4.7.0.0

Defined in Data.Proxy

Methods

mempty :: Proxy s

mappend :: Proxy s -> Proxy s -> Proxy s

mconcat :: [Proxy s] -> Proxy s

type Rep1 (Proxy :: k -> *)

Defined in GHC.Generics

type Rep1 (Proxy :: k -> *) = D1 (MetaData "Proxy" "Data.Proxy" "base" False) (C1 (MetaCons "Proxy" PrefixI False) (U1 :: k -> *))

type Rep (Proxy t)

Defined in GHC.Generics

type Rep (Proxy t) = D1 (MetaData "Proxy" "Data.Proxy" "base" False) (C1 (MetaCons "Proxy" PrefixI False) (U1 :: * -> *))

Data.Version.Extra

Extra functions available in Data.Version.Extra.

makeVersion :: [Int] -> Version

Construct tag-less Version

Since: base-4.8.0.0

readVersion :: Partial => String -> Version

Read a Version or throw an exception.

\x -> readVersion (showVersion x) == x
readVersion "hello" == undefined

Numeric.Extra

Extra functions available in Numeric.Extra.

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

Show a number to a fixed number of decimal places.

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

intToDouble :: Int -> Double

Specialised numeric conversion, type restricted version of fromIntegral.

intToFloat :: Int -> Float

Specialised numeric conversion, type restricted version of fromIntegral.

floatToDouble :: Float -> Double

Specialised numeric conversion, type restricted version of realToFrac.

doubleToFloat :: Double -> Float

Specialised numeric conversion, type restricted version of realToFrac.

System.Directory.Extra

Extra functions available in System.Directory.Extra.

withCurrentDirectory

Arguments

:: FilePath

Directory to execute in

-> IO a

Action to be executed

-> IO a

Run an IO action with the given working directory and restore the original working directory afterwards, even if the given action fails due to an exception.

The operation may fail with the same exceptions as getCurrentDirectory and setCurrentDirectory.

Since: directory-1.2.3.0

createDirectoryPrivate :: String -> IO ()

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

listContents :: FilePath -> IO [FilePath]

List the files and directories directly within a directory. Each result will be prefixed by the query directory, and the special directories . and .. will be ignored. Intended as a cleaned up version of getDirectoryContents.

withTempDir $ \dir -> do writeFile (dir </> "test.txt") ""; (== [dir </> "test.txt"]) <$> listContents dir
let touch = mapM_ $ \x -> createDirectoryIfMissing True (takeDirectory x) >> writeFile x ""
let listTest op as bs = withTempDir $ \dir -> do touch $ map (dir </>) as; res <- op dir; return $ map (drop (length dir + 1)) res == bs
listTest listContents ["bar.txt","foo/baz.txt","zoo"] ["bar.txt","foo","zoo"]

listDirectories :: FilePath -> IO [FilePath]

Like listContents, but only returns the directories in a directory, not the files. Each directory will be prefixed by the query directory.

listTest listDirectories ["bar.txt","foo/baz.txt","zoo"] ["foo"]

listFiles :: FilePath -> IO [FilePath]

Like listContents, but only returns the files in a directory, not other directories. Each file will be prefixed by the query directory.

listTest listFiles ["bar.txt","foo/baz.txt","zoo"] ["bar.txt","zoo"]

listFilesInside :: (FilePath -> IO Bool) -> FilePath -> IO [FilePath]

Like listFilesRecursive, but with a predicate to decide where to recurse into. Typically directories starting with . would be ignored. The initial argument directory will have the test applied to it.

listTest (listFilesInside $ return . not . isPrefixOf "." . takeFileName)
    ["bar.txt","foo" </> "baz.txt",".foo" </> "baz2.txt", "zoo"] ["bar.txt","zoo","foo" </> "baz.txt"]
listTest (listFilesInside $ const $ return False) ["bar.txt"] []

listFilesRecursive :: FilePath -> IO [FilePath]

Like listFiles, but goes recursively through all subdirectories. This function will follow symlinks, and if they form a loop, this function will not terminate.

listTest listFilesRecursive ["bar.txt","zoo","foo" </> "baz.txt"] ["bar.txt","zoo","foo" </> "baz.txt"]

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.)

Since base 4.11.0.0, getExecutablePath resolves symlinks on Windows. If an executable is launched through a symlink, getExecutablePath returns the absolute path of the original executable.

Since: base-4.6.0.0

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.

Since: base-4.6.0.0

System.Info.Extra

Extra functions available in System.Info.Extra.

isWindows :: Bool

Return True on Windows and False otherwise. A runtime version of #ifdef minw32_HOST_OS. Equivalent to os == "mingw32", but: more efficient; doesn't require typing an easily mistypeable string; actually asks about your OS not a library; doesn't bake in 32bit assumptions that are already false. </rant>

isWindows == (os == "mingw32")

isMac :: Bool

Return True on Mac OS X and False otherwise.

System.IO.Extra

Extra functions available in System.IO.Extra.

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

Capture the stdout and stderr of a computation.

captureOutput (print 1) == return ("1\n",())

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

Execute an action with a custom BufferMode, a wrapper around hSetBuffering.

readFileEncoding :: TextEncoding -> FilePath -> IO String

Like readFile, but setting an encoding.

readFileUTF8 :: FilePath -> IO String

Like readFile, but with the encoding utf8.

readFileBinary :: FilePath -> IO String

Like readFile, but for binary files.

readFile' :: FilePath -> IO String

A strict version of readFile. When the string is produced, the entire file will have been read into memory and the file handle will have been closed. Closing the file handle does not rely on the garbage collector.

\(filter isHexDigit -> s) -> fmap (== s) $ withTempFile $ \file -> do writeFile file s; readFile' file

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

A strict version of readFileEncoding, see readFile' for details.

readFileUTF8' :: FilePath -> IO String

A strict version of readFileUTF8, see readFile' for details.

readFileBinary' :: FilePath -> IO String

A strict version of readFileBinary, see readFile' for details.

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

Write a file with a particular encoding.

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

Write a file with the utf8 encoding.

\s -> withTempFile $ \file -> do writeFileUTF8 file s; fmap (== s) $ readFileUTF8' file

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

Write a binary file.

\(ASCIIString s) -> withTempFile $ \file -> do writeFileBinary file s; fmap (== s) $ readFileBinary' file

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

Create a temporary file in the temporary directory. The file will be deleted after the action completes (provided the file is not still open). The FilePath will not have any file extension, will exist, and will be zero bytes long. If you require a file with a specific name, use withTempDir.

withTempFile doesFileExist == return True
(doesFileExist =<< withTempFile return) == return False
withTempFile readFile' == return ""

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

Create a temporary directory inside the system temporary directory. The directory will be deleted after the action completes.

withTempDir doesDirectoryExist == return True
(doesDirectoryExist =<< withTempDir return) == return False
withTempDir listFiles == return []

newTempFile :: IO (FilePath, IO ())

Provide a function to create a temporary file, and a way to delete a temporary file. Most users should use withTempFile which combines these operations.

newTempDir :: IO (FilePath, IO ())

Provide a function to create a temporary directory, and a way to delete a temporary directory. Most users should use withTempDir which combines these operations.

newTempFileWithin :: FilePath -> IO (FilePath, IO ())

Like newTempFile but using a custom temporary directory.

newTempDirWithin :: FilePath -> IO (FilePath, IO ())

Like newTempDir but using a custom temporary directory.

fileEq :: FilePath -> FilePath -> IO Bool

Returns True if both files have the same content. Raises an error if either file is missing.

fileEq "does_not_exist1" "does_not_exist2" == undefined
fileEq "does_not_exist" "does_not_exist" == undefined
withTempFile $ \f1 -> fileEq "does_not_exist" f1 == undefined
withTempFile $ \f1 -> withTempFile $ \f2 -> fileEq f1 f2
withTempFile $ \f1 -> withTempFile $ \f2 -> writeFile f1 "a" >> writeFile f2 "a" >> fileEq f1 f2
withTempFile $ \f1 -> withTempFile $ \f2 -> writeFile f1 "a" >> writeFile f2 "b" >> notM (fileEq f1 f2)

System.Process.Extra

Extra functions available in System.Process.Extra.

system_ :: Partial => String -> IO ()

A version of system that throws an error if the ExitCode is not ExitSuccess.

systemOutput :: String -> IO (ExitCode, String)

A version of system that also captures the output, both stdout and stderr. Returns a pair of the ExitCode and the output.

systemOutput_ :: Partial => String -> IO String

A version of system that captures the output (both stdout and stderr) and throws an error if the ExitCode is not ExitSuccess.

System.Time.Extra

Extra functions available in System.Time.Extra.

type Seconds = Double

A type alias for seconds, which are stored as Double.

sleep :: Seconds -> IO ()

Sleep for a number of seconds.

fmap (round . fst) (duration $ sleep 1) == return 1

timeout :: Seconds -> IO a -> IO (Maybe a)

A version of timeout that takes Seconds and never overflows the bounds of an Int. In addition, the bug that negative timeouts run for ever has been fixed.

timeout (-3) (print 1) == return Nothing
timeout 0.1  (print 1) == fmap Just (print 1)
do (t, _) <- duration $ timeout 0.1 $ sleep 1000; print t; return $ t < 1
timeout 0.1  (sleep 2 >> print 1) == return Nothing

showDuration :: Seconds -> String

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

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

offsetTime :: IO (IO Seconds)

Call once to start, then call repeatedly to get the elapsed time since the first call. The time is guaranteed to be monotonic. This function is robust to system time changes.

do f <- offsetTime; xs <- replicateM 10 f; return $ xs == sort xs

offsetTimeIncrease :: IO (IO Seconds)

Deprecated: Use offsetTime instead, which is guaranteed to always increase.

A synonym for offsetTime.

duration :: IO a -> IO (Seconds, a)

Record how long a computation takes in Seconds.

do (a,_) <- duration $ sleep 1; return $ a >= 1 && a <= 1.5

Text.Read.Extra

Extra functions available in Text.Read.Extra.

readEither :: Read a => String -> Either String a

Parse a string using the Read instance. Succeeds if there is exactly one valid result. A Left value indicates a parse error.

>>> readEither "123" :: Either String Int
Right 123

>>> readEither "hello" :: Either String Int
Left "Prelude.read: no parse"

Since: base-4.6.0.0

readMaybe :: Read a => String -> Maybe a

Parse a string using the Read instance. Succeeds if there is exactly one valid result.

>>> readMaybe "123" :: Maybe Int
Just 123

>>> readMaybe "hello" :: Maybe Int
Nothing

Since: base-4.6.0.0