Futhark.Util

Non-Futhark-specific utilities. If you find yourself writing general functions on generic data structures, consider putting them here.

Sometimes it is also preferable to copy a small function rather than introducing a large dependency. In this case, make sure to note where you got it from (and make sure that the license is compatible).

Documentation

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

Like nub, but without the quadratic runtime.

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

Like nubBy, but without the quadratic runtime.

mapAccumLM :: (Monad m, Traversable t) => (acc -> x -> m (acc, y)) -> acc -> t x -> m (acc, t y)

Like mapAccumL, but monadic and generalised to any Traversable.

maxinum :: (Num a, Ord a, Foldable f) => f a -> a

Like maximum, but returns zero for an empty list.

mininum :: (Num a, Ord a, Foldable f) => f a -> a

Like minimum, but returns zero for an empty list.

chunk :: Int -> [a] -> [[a]]

chunk n a splits a into n-size-chunks. If the length of a is not divisible by n, the last chunk will have fewer than n elements (but it will never be empty).

chunks :: [Int] -> [a] -> [[a]]

chunks ns a splits a into chunks determined by the elements of ns. It must hold that sum ns == length a, or the resulting list may contain too few chunks, or not all elements of a.

chunkLike :: [[a]] -> [b] -> [[b]]

chunkLike xss ys chunks the elements of ys to match the elements of xss. The sum of the lengths of the sublists of xss must match the length of ys.

dropAt :: Int -> Int -> [a] -> [a]

dropAt i n drops n elements starting at element i.

takeLast :: Int -> [a] -> [a]

takeLast n l takes the last n elements of l.

dropLast :: Int -> [a] -> [a]

dropLast n l drops the last n elements of l.

mapEither :: (a -> Either b c) -> [a] -> ([b], [c])

A combination of map and partitionEithers.

partitionMaybe :: (a -> Maybe b) -> [a] -> ([b], [a])

A combination of partition and mapMaybe

maybeNth :: Integral int => int -> [a] -> Maybe a

Return the list element at the given index, if the index is valid.

maybeHead :: [a] -> Maybe a

Return the first element of the list, if it exists.

lookupWithIndex :: Eq a => a -> [(a, b)] -> Maybe (Int, b)

Lookup a value, returning also the index at which it appears.

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

Like splitAt, but from the end.

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

Like splitAt, but produces three lists.

focusNth :: Integral int => int -> [a] -> Maybe ([a], a, [a])

Return the list element at the given index, if the index is valid, along with the elements before and after.

focusMaybe :: (a -> Maybe b) -> [a] -> Maybe ([a], b, [a])

Return the first list element that satisifes a predicate, along with the elements before and after.

hashText :: Text -> Text

Compute a hash of a text that is stable across OS versions. Returns the hash as a text as well, ready for human consumption.

showText :: Show a => a -> Text

Like show, but produces text.

unixEnvironment :: [(String, String)]

The Unix environment when the Futhark compiler started.

isEnvVarAtLeast :: String -> Int -> Bool

True if the environment variable, viewed as an integer, has at least this numeric value. Returns False if variable is unset or not numeric.

startupTime :: UTCTime

The time at which the process started - or more accurately, the first time this binding was forced.

fancyTerminal :: Bool

Are we running in a terminal capable of fancy commands and visualisation?

hFancyTerminal :: Handle -> IO Bool

Is this handle connected to a terminal capable of fancy commands and visualisation?

runProgramWithExitCode :: FilePath -> [String] -> ByteString -> IO (Either IOException (ExitCode, String, String))

Like readProcessWithExitCode, but also wraps exceptions when the indicated binary cannot be launched, or some other exception is thrown. Also does shenanigans to handle improperly encoded outputs.

directoryContents :: FilePath -> IO [FilePath]

Every non-directory file contained in a directory tree.

fromPOSIX :: FilePath -> FilePath

Some bad operating systems do not use forward slash as directory separator - this is where we convert Futhark includes (which always use forward slash) to native paths.

toPOSIX :: FilePath -> FilePath

Turn a POSIX filepath into a filepath for the native system.

trim :: String -> String

Remove leading and trailing whitespace from a string. Not an efficient implementation!

pmapIO :: Maybe Int -> (a -> IO b) -> [a] -> IO [b]

Run various IO actions concurrently, possibly with a bound on the number of threads. The list must be finite. The ordering of the result list is not deterministic - add your own sorting if needed. If any of the actions throw an exception, then that exception is propagated to this function.

interactWithFileSafely :: IO a -> IO (Maybe (Either String a))

Do some operation on a file, returning Nothing if the file does not exist, and Left if some other error occurs.

convFloat :: (RealFloat from, RealFloat to) => from -> to

Convert between different floating-point types, preserving infinities and NaNs.

type UserText = Text

As the user typed it.

type EncodedText = Text

Encoded form.

zEncodeText :: UserText -> EncodedText

Z-encode a text using a slightly simplified variant of GHC Z-encoding. The encoded string is a valid identifier in most programming languages.

atMostChars :: Int -> Text -> Text

Truncate to at most this many characters, making the last three characters "..." if truncation is necessary.

invertMap :: (Ord v, Ord k) => Map k v -> Map v (Set k)

Invert a map, handling duplicate values (now keys) by constructing a set of corresponding values.

cartesian :: (Monoid m, Foldable t) => (a -> a -> m) -> t a -> t a -> m

Compute the cartesian product of two foldable collections, using the given combinator function.

traverseFold :: (Monoid m, Traversable t, Applicative f) => (a -> f m) -> t a -> f m

Applicatively fold a traversable.

fixPoint :: Eq a => (a -> a) -> a -> a

Perform fixpoint iteration.

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

Like concatMap, but monoidal and monadic.

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

Topological sorting of an array with an adjancency function, if there is a cycle, it causes an error. dep a b means a -> b, and the returned array guarantee that for i < j:

not ( dep (ret !! j) (ret !! i) ).

debugTraceM :: Monad m => Int -> String -> m ()

traceM, but only if FUTHARK_COMPILER_DEBUGGING is set to to the appropriate level.