-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Ill-defined library.
--
-- Ill-defined unrelated utilities used by other packages from
-- http://functionalley.eu
@package toolshed
@version 0.17.0.2
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION
--
--
--
-- - Facilitates testing of custom implementations of Read &
-- Show.
-- - CAVEAT: it doesn't actually do any IO.
--
module ToolShed.Test.ReversibleIO
-- | Checks that composing read & show is equivalent to
-- the identity.
isReversible :: (Eq r, Read r, Show r) => r -> Bool
-- | Checks whether read can skip prepended white space;
-- isReversible is a prerequisite.
readPrependedWhiteSpace :: (Eq r, Read r, Show r) => r -> Bool
-- | Checks whether read both copes with garbage following the valid
-- input-data, & leaves it unchanged.
readTrailingGarbage :: (Eq a, Read a, Show a) => (Char -> Bool) -> a -> String -> Bool
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Facilities testing of custom
-- implementations of Enum.
--
module ToolShed.Test.ReversibleEnum
-- | Checks that composing toEnum & fromEnum is
-- equivalent to the identity.
isReversible :: (Eq r, Enum r) => r -> Bool
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Facilities testing of custom
-- implementations of Enum.
--
module ToolShed.Test.ReversibleBoundedEnum
-- | Checks that composing pred & succ is equivalent to
-- the identity.
isReversible :: (Bounded r, Eq r, Enum r) => r -> Bool
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Provides a simple predicate.
--
module ToolShed.Test.QuickCheck.Result
-- | Check whether the specified result is successful.
isSuccessful :: Result -> Bool
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Implements Arbitrary for
-- Set; which was subsequently implemented in
-- "QuickCheck-2.8.2".
-- - EXAMPLE Test.QuickCheck.sample
-- (Test.QuickCheck.arbitrary :: Test.QuickCheck.Gen.Gen (Data.Set.Set
-- Int))
--
module ToolShed.Test.QuickCheck.Arbitrary.Set
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Implements Arbitrary for
-- Map; which was subsequently implemented in
-- "QuickCheck-2.8.2".
-- - EXAMPLE Test.QuickCheck.sample
-- (Test.QuickCheck.arbitrary :: Test.QuickCheck.Gen.Gen (Data.Map.Map
-- Char Int))
--
module ToolShed.Test.QuickCheck.Arbitrary.Map
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION
--
--
-- Implements Arbitrary for Array, where the array-index is
-- required to be a bounded enumerable type.
--
--
-- - EXAMPLE Test.QuickCheck.sample
-- (Test.QuickCheck.arbitrary :: Test.QuickCheck.Gen.Gen
-- (Data.Array.IArray.Array Data.Int.Int8 Int))
--
module ToolShed.Test.QuickCheck.Arbitrary.Array
instance (GHC.Enum.Bounded i, GHC.Arr.Ix i, GHC.Enum.Enum i, Test.QuickCheck.Arbitrary.Arbitrary e) => Test.QuickCheck.Arbitrary.Arbitrary (GHC.Arr.Array i e)
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Facilities testing of custom
-- implementations of Ix.
--
module ToolShed.Test.Ix
-- | Checks that implementations of Data.Array.IArray.Ix satisfy rules.
index :: (Bounded a, Ix a) => a -> Bool
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Determines the CPU-time, required to
-- evaluate the specified pure expression.
--
module ToolShed.System.TimePure
-- |
-- - Time the specified pure expression, returning the required number
-- of CPU-seconds and the result, as a Pair.
-- - CAVEAT: as a side-effect, the expression is deep
-- evaluated.
--
getCPUSeconds :: (Fractional seconds, NFData expression) => expression -> IO (seconds, expression)
-- |
-- - Print the time required by the specified pure expression.
-- - CAVEAT: as a side-effect, the expression is deep
-- evaluated.
--
printCPUSeconds :: NFData expression => expression -> IO expression
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Determines the CPU-time, required to
-- evaluate the specified IO-action.
--
module ToolShed.System.TimeAction
-- | Time the specified IO-action, returning the required number of
-- CPU-seconds and the result, as a Pair.
getCPUSeconds :: Fractional seconds => IO result -> IO (seconds, result)
-- | Print the time required by the specified IO-action.
printCPUSeconds :: IO result -> IO result
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Utilities related to
-- random-numbers.
--
module ToolShed.System.Random
-- | Constructs an infinite list of independent random-generators.
randomGens :: RandomGen randomGen => randomGen -> [randomGen]
-- |
-- - Shuffles the specified finite list, using the Fisher-Yates
-- algorithm;
-- https://en.wikipedia.org/wiki/Fisher-Yates_shuffle.
-- - The resulting list has the same length and constituents as the
-- original; only the order has changed.
-- - The input list is traversed, but the items aren't evaluated.
--
shuffle :: RandomGen randomGen => randomGen -> [a] -> [a]
-- |
-- - Generate an infinite list of items, each independently randomly
-- selected from the specified finite list.
-- - CAVEAT: because the selections are made non-destructively,
-- duplicates may be returned; cf. shuffle.
--
generateSelection :: RandomGen randomGen => randomGen -> [a] -> Maybe [a]
-- |
-- - Generate an infinite list of data, each independently selected
-- random instances of the specified bounded type.
-- - E.g. (generateSelectionFromBounded fmap
-- System.Random.getStdGen) :: IO [Bool] .
--
generateSelectionFromBounded :: (RandomGen randomGen, Bounded a, Random a) => randomGen -> [a]
-- | Return a randomly selected element from those provided.
select :: (Foldable foldable, RandomGen randomGen) => randomGen -> foldable a -> Maybe a
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION File-operations.
--
module ToolShed.System.File
-- | The ordered sequence of directories, searched for a file.
type SearchPath = [FilePath]
-- | A file-path, and the contents read from it.
type LocatedData a = (FilePath, a)
-- |
-- - When supplied with an absolute file-path, the
-- search-path is ignored and an exception is thrown if either the
-- file-path is invalid or the file doesn't exist.
-- - If the specified file-name is relative, all matching
-- instances on the specified search-path are returned.
-- - CAVEAT: doesn't perform file-globbing.
--
locate :: FilePath -> SearchPath -> IO [FilePath]
-- | Traverse the search-path, looking for matching instances of the
-- specified file-name, and either throw an exception, or return a pair
-- composed from the path to the first matching file, together with its
-- contents.
getFile :: FilePath -> SearchPath -> IO (LocatedData String)
-- |
-- - Returns the polymorphic data, read from the first matching file on
-- the search-path, along with the path from which it was
-- read.
-- - Returns an error on failure to parse the contents of the first
-- matching file found on the search-path.
--
fromFile :: Read a => FilePath -> SearchPath -> IO (LocatedData a)
-- | Accessor.
getFilePath :: LocatedData a -> FilePath
-- | Accessor.
getData :: LocatedData a -> a
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION A class to define the simple
-- interface, to which data which can self-validation, should
-- conform.
--
module ToolShed.SelfValidate
-- | The interface to which data which can self-validate should conform.
class SelfValidator v where isValid = null . getErrors
getErrors :: SelfValidator v => v -> [String]
isValid :: SelfValidator v => v -> Bool
-- | Returns the first error only (so only call on failure of
-- isValid), since subsequent tests may be based on invalid data.
getFirstError :: SelfValidator v => v -> String
-- | Extracts the failed tests from those specified.
extractErrors :: [(Bool, String)] -> [String]
instance ToolShed.SelfValidate.SelfValidator v => ToolShed.SelfValidate.SelfValidator (GHC.Base.Maybe v)
instance (ToolShed.SelfValidate.SelfValidator a, ToolShed.SelfValidate.SelfValidator b) => ToolShed.SelfValidate.SelfValidator (a, b)
instance (ToolShed.SelfValidate.SelfValidator a, ToolShed.SelfValidate.SelfValidator b, ToolShed.SelfValidate.SelfValidator c) => ToolShed.SelfValidate.SelfValidator (a, b, c)
instance ToolShed.SelfValidate.SelfValidator v => ToolShed.SelfValidate.SelfValidator [v]
instance ToolShed.SelfValidate.SelfValidator v => ToolShed.SelfValidate.SelfValidator (Data.Set.Base.Set v)
instance ToolShed.SelfValidate.SelfValidator v => ToolShed.SelfValidate.SelfValidator (Data.Map.Base.Map k v)
instance (GHC.Arr.Ix index, ToolShed.SelfValidate.SelfValidator element) => ToolShed.SelfValidate.SelfValidator (GHC.Arr.Array index element)
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Defines a standard interface to which
-- various options-related data can conform.
--
module ToolShed.Options
-- | The required interface.
class Default a => Options a
blankValue :: Options a => a
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Miscellaneous operations on
-- triples.
-- - CAVEAT Import fully qualified, since some
-- identifiers clash with Quadruple.
--
module ToolShed.Data.Triple
-- | Extends the concept of curry.
curry3 :: ((a, b, c) -> result) -> a -> b -> c -> result
-- | Extends the concept of uncurry.
uncurry3 :: (a -> b -> c -> result) -> (a, b, c) -> result
-- | Access the first datum from the specified triple.
getFirst :: (a, b, c) -> a
-- | Access the second datum from the specified triple.
getSecond :: (a, b, c) -> b
-- | Access the third datum from the specified triple.
getThird :: (a, b, c) -> c
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Miscellaneous String-orientated
-- functions.
--
module ToolShed.Data.String
-- | Replaces any embedded tab-characters with the appropriate number of
-- spaces.
deTab :: Int -> String -> String
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Miscellaneous operations on
-- quadruples.
-- - CAVEAT Import fully qualified, since some
-- identifiers clash with Triple.
--
module ToolShed.Data.Quadruple
-- | Extends the concept of curry.
curry4 :: ((a, b, c, d) -> result) -> a -> b -> c -> d -> result
-- | Extends the concept of uncurry.
uncurry4 :: (a -> b -> c -> d -> result) -> (a, b, c, d) -> result
-- | Access the first datum from the specified quadruple.
getFirst :: (a, b, c, d) -> a
-- | Access the second datum from the specified quadruple.
getSecond :: (a, b, c, d) -> b
-- | Access the third datum from the specified quadruple.
getThird :: (a, b, c, d) -> c
-- | Access the fourth datum from the specified quadruple.
getFourth :: (a, b, c, d) -> d
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Miscellaneous operations on
-- Pairs.
--
module ToolShed.Data.Pair
-- |
-- - Apply the same transformation to both halves of a
-- Pair.
-- - CAVEAT: even though the function may be polymorphic, the pair is
-- required to have identical types.
--
mirror :: (a -> b) -> (a, a) -> (b, b)
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION
--
module ToolShed.Data.List.Splits
-- |
-- - Create the set of all Splits, migrating left from the
-- specified location.
-- - CAVEAT: init fails when fst has been reduced to
-- null.
--
splitsLeftFrom :: Int -> [a] -> [Split a]
-- |
-- - Create the set of all Splits, migrating right from the
-- specified location.
-- - CAVEAT: pattern-match against : fails, when snd
-- has been reduced to null.
--
splitsRightFrom :: Int -> [a] -> [Split a]
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Run-length encoder and decoder.
--
module ToolShed.Data.List.Runlength
-- | Describes the number of consecutive equal items in a list.
type Code a = (Int, a)
-- | Run-length encodes the specified list.
encode :: Eq a => [a] -> [Code a]
-- | Performs run-length decoding to retrieve the original unencoded
-- list.
decode :: [Code a] -> [a]
-- | Accessor.
getLength :: Code a -> Int
-- | Accessor.
getDatum :: Code a -> a
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Miscellaneous polymorphic
-- list-operations.
--
module ToolShed.Data.List
-- | The length of the chunks into which a list is split.
type ChunkLength = Int
-- | The type of function required by findConvergenceBy,
-- permutationsBy.
type Matches a = a -> a -> Bool
-- |
-- - Splits a list into chunks of the specified length.
-- - The last chunk will be shorter, if the chunk-length isn't an
-- aliquot part of the input list-length.
-- - If the chunk-length is zero, the resulting list will be an
-- infinite sequence of null lists.
-- - CAVEAT: a similar function is available in the module
-- Data.List.Split, though this one checks for (chunkLength
-- < 0).
--
chunk :: ChunkLength -> [a] -> [[a]]
-- | Remove the single indexed element from the list.
excise :: Int -> [a] -> [a]
-- | A convenient way to compose the Matches-function required by
-- findConvergenceBy & permutationsBy.
equalityBy :: Eq b => (a -> b) -> Matches a
-- | A specific instance of findConvergenceBy.
findConvergence :: Eq a => [a] -> a
-- | Take the first element from the (potentially infinite) list, which
-- matches the subsequent element, according to the specified function.
findConvergenceBy :: Matches a -> [a] -> a
-- | Interleaves the specified lists, taking the first item from the first
-- list.
interleave :: [a] -> [a] -> [a]
-- | Converts a list of Pairs, into a narrower list.
linearise :: [(a, a)] -> [a]
-- |
measureJaroDistance :: (Eq a, Fractional distance) => ([a], [a]) -> distance
-- | A specific instance of mergeBy.
merge :: Ord a => [a] -> [a] -> [a]
-- |
-- - Merge two sorted lists, according to the specified order, to
-- product a single sorted list.
-- - The merge-process is stable, in that where items from each
-- list are equal, they remain in the original order.
-- - CAVEAT: duplicates are preserved.
--
mergeBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]
-- |
-- - A strict version of nub with better time-complexity.
-- - CAVEAT: the specified list must be finite, since the entire set is
-- constructed before streaming to a list.
-- - CAVEAT: it sorts the output as a side-effect, & consequently
-- it requires a type which implements Ord.
--
nub' :: Ord a => [a] -> [a]
-- |
-- - The list of all permutations, generated by selecting any one datum
-- from each sub-list in turn, from the specified list of lists.
-- - A specific instance of permutationsBy, in which no
-- filtering of subsequent lists is performed after each item is
-- selected.
-- - N.B.: differs from permutations, which selects items from a
-- single input list.
--
permutations :: [[a]] -> [[a]]
-- |
-- - The list of all permutations, generated by selecting any one datum
-- from each sub-list in turn, from the specified list of lists.
-- - As each item is selected, the remaining lists are filtered
-- according to the specified Matches-function.
-- - Thus /= could be used to select a different item from each
-- list.
--
permutationsBy :: Matches a -> [[a]] -> [[a]]
-- |
-- - Take until the specified predicate is satisfied; including
-- the item which satisfied it.
-- - N.B.: takeWhile (not . test) would return one fewer
-- item.
--
takeUntil :: (a -> Bool) -> [a] -> [a]
-- | Show a list, delimited by the specified tokens.
showListWith :: (Show token, Show element) => (token, token, token) -> [element] -> ShowS
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION
--
--
--
module ToolShed.Data.Array.IArray
-- | Update a single element of the specified array.
adjust :: (Ix i, IArray a e) => (e -> e) -> i -> a i e -> a i e
-- |
-- - AUTHOR Dr. Alistair Ward
-- - DESCRIPTION Miscellaneous polymorphic operations
-- on Foldable types.
--
module ToolShed.Data.Foldable
-- | A specific instance of gatherBy.
gather :: (Foldable foldable, Ord a) => foldable a -> [[a]]
-- |
-- - Group equal (though not necessarily adjacent; cf. groupBy)
-- elements, according to the specified comparator.
-- - The groups are returned in ascending order, whilst their elements
-- remain in their original order.
--
gatherBy :: (Foldable foldable, Ord b) => (a -> b) -> foldable a -> [[a]]
-- | Whether the specified collection contains any equal items.
hasDuplicates :: (Foldable foldable, Ord a) => foldable a -> Bool