Distribution.Solver.Compat.Prelude

deepseq: fully evaluates the first argument, before returning the second.

The name deepseq is used to illustrate the relationship to seq: where seq is shallow in the sense that it only evaluates the top level of its argument, deepseq traverses the entire data structure evaluating it completely.

deepseq can be useful for forcing pending exceptions, eradicating space leaks, or forcing lazy I/O to happen. It is also useful in conjunction with parallel Strategies (see the parallel package).

There is no guarantee about the ordering of evaluation. The implementation may evaluate the components of the structure in any order or in parallel. To impose an actual order on evaluation, use pseq from Control.Parallel in the parallel package.

Identity function.

id x = x

This function might seem useless at first glance, but it can be very useful in a higher order context.

Examples

>>> length $ filter id [True, True, False, True]3

>>> Just (Just 3) >>= idJust 3

>>> foldr id 0 [(^3), (*5), (+2)]1000

Right to left function composition.

prop> (f . g) x = f (g x)

prop> f . id = f = id . f

Examples

>>> map ((*2) . length) [[], [0, 1, 2], [0]][0,6,2]

>>> foldr (.) id [(+1), (*3), (^3)] 225

>>> let (...) = (.).(.) in ((*2)...(+)) 5 1030

Basic numeric class.

The Haskell Report defines no laws for Num. However, (+) and (*) are customarily expected to define a ring and have the following properties:

Associativity of (+)

(x + y) + z

=

x + (y + z)

Commutativity of (+)

x + y

=

y + x

fromInteger 0 is the additive identity

x + fromInteger 0

=

x

negate gives the additive inverse

x + negate x

=

fromInteger 0

Associativity of (*)

(x * y) * z

=

x * (y * z)

fromInteger 1 is the multiplicative identity

x * fromInteger 1

=

x

and

fromInteger 1 * x

=

x

Distributivity of (*) with respect to (+)

a * (b + c)

=

(a * b) + (a * c)

and

(b + c) * a

=

(b * a) + (c * a)

Coherence with toInteger

if the type also implements

GHC.Real.Integral

, then

fromInteger

is a left inverse for

toInteger

, i.e.

fromInteger (toInteger i) == i

Note that it isn't customarily expected that a type instance of both Num and Ord implement an ordered ring. Indeed, in base only Integer and Rational do.

The Data class comprehends a fundamental primitive gfoldl for folding over constructor applications, say terms. This primitive can be instantiated in several ways to map over the immediate subterms of a term; see the gmap combinators later in this class. Indeed, a generic programmer does not necessarily need to use the ingenious gfoldl primitive but rather the intuitive gmap combinators. The gfoldl primitive is completed by means to query top-level constructors, to turn constructor representations into proper terms, and to list all possible datatype constructors. This completion allows us to serve generic programming scenarios like read, show, equality, term generation.

The combinators gmapT, gmapQ, gmapM, etc are all provided with default definitions in terms of gfoldl, leaving open the opportunity to provide datatype-specific definitions. (The inclusion of the gmap combinators as members of class Data allows the programmer or the compiler to derive specialised, and maybe more efficient code per datatype. Note: gfoldl is more higher-order than the gmap combinators. This is subject to ongoing benchmarking experiments. It might turn out that the gmap combinators will be moved out of the class Data.)

Conceptually, the definition of the gmap combinators in terms of the primitive gfoldl requires the identification of the gfoldl function arguments. Technically, we also need to identify the type constructor c for the construction of the result type from the folded term type.

In the definition of gmapQx combinators, we use phantom type constructors for the c in the type of gfoldl because the result type of a query does not involve the (polymorphic) type of the term argument. In the definition of gmapQl we simply use the plain constant type constructor because gfoldl is left-associative anyway and so it is readily suited to fold a left-associative binary operation over the immediate subterms. In the definition of gmapQr, extra effort is needed. We use a higher-order accumulation trick to mediate between left-associative constructor application vs. right-associative binary operation (e.g., (:)). When the query is meant to compute a value of type r, then the result type within generic folding is r -> r. So the result of folding is a function to which we finally pass the right unit.

With the -XDeriveDataTypeable option, GHC can generate instances of the Data class automatically. For example, given the declaration

data T a b = C1 a b | C2 deriving (Typeable, Data)

GHC will generate an instance that is equivalent to

instance (Data a, Data b) => Data (T a b) where
    gfoldl k z (C1 a b) = z C1 `k` a `k` b
    gfoldl k z C2       = z C2

    gunfold k z c = case constrIndex c of
                        1 -> k (k (z C1))
                        2 -> z C2

    toConstr (C1 _ _) = con_C1
    toConstr C2       = con_C2

    dataTypeOf _ = ty_T

con_C1 = mkConstr ty_T "C1" [] Prefix
con_C2 = mkConstr ty_T "C2" [] Prefix
ty_T   = mkDataType "Module.T" [con_C1, con_C2]

This is suitable for datatypes that are exported transparently.

A Map from keys k to values a.

The Semigroup operation for Map is union, which prefers values from the left operand. If m1 maps a key k to a value a1, and m2 maps the same key to a different value a2, then their union m1 <> m2 maps k to a1.

A set of values a.

Trigonometric and hyperbolic functions and related functions.

The Haskell Report defines no laws for Floating. However, (+), (*) and exp are customarily expected to define an exponential field and have the following properties:

• exp (a + b) = exp a * exp b

• exp (fromInteger 0) = fromInteger 1

The Maybe type encapsulates an optional value. A value of type Maybe a either contains a value of type a (represented as Just a), or it is empty (represented as Nothing). Using Maybe is a good way to deal with errors or exceptional cases without resorting to drastic measures such as error.

The Maybe type is also a monad. It is a simple kind of error monad, where all errors are represented by Nothing. A richer error monad can be built using the Either type.

Partitions a list of Either into two lists. All the Left elements are extracted, in order, to the first component of the output. Similarly the Right elements are extracted to the second component of the output.

Examples

Basic usage:

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> partitionEithers list(["foo","bar","baz"],[3,7])

The pair returned by partitionEithers x should be the same pair as (lefts x, rights x):

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> partitionEithers list == (lefts list, rights list)True

The Either type represents values with two possibilities: a value of type Either a b is either Left a or Right b.

The Either type is sometimes used to represent a value which is either correct or an error; by convention, the Left constructor is used to hold an error value and the Right constructor is used to hold a correct value (mnemonic: "right" also means "correct").

Examples

The type Either String Int is the type of values which can be either a String or an Int. The Left constructor can be used only on Strings, and the Right constructor can be used only on Ints:

>>> let s = Left "foo" :: Either String Int>>> sLeft "foo">>> let n = Right 3 :: Either String Int>>> nRight 3>>> :type ss :: Either String Int>>> :type nn :: Either String Int

The fmap from our Functor instance will ignore Left values, but will apply the supplied function to values contained in a Right:

>>> let s = Left "foo" :: Either String Int>>> let n = Right 3 :: Either String Int>>> fmap (*2) sLeft "foo">>> fmap (*2) nRight 6

The Monad instance for Either allows us to chain together multiple actions which may fail, and fail overall if any of the individual steps failed. First we'll write a function that can either parse an Int from a Char, or fail.

>>> import Data.Char ( digitToInt, isDigit )>>> :{    let parseEither :: Char -> Either String Int        parseEither c          | isDigit c = Right (digitToInt c)          | otherwise = Left "parse error">>> :}

The following should work, since both '1' and '2' can be parsed as Ints.

>>> :{    let parseMultiple :: Either String Int        parseMultiple = do          x <- parseEither '1'          y <- parseEither '2'          return (x + y)>>> :}

>>> parseMultipleRight 3

But the following should fail overall, since the first operation where we attempt to parse 'm' as an Int will fail:

>>> :{    let parseMultiple :: Either String Int        parseMultiple = do          x <- parseEither 'm'          y <- parseEither '2'          return (x + y)>>> :}

>>> parseMultipleLeft "parse error"

The Foldable class represents data structures that can be reduced to a summary value one element at a time. Strict left-associative folds are a good fit for space-efficient reduction, while lazy right-associative folds are a good fit for corecursive iteration, or for folds that short-circuit after processing an initial subsequence of the structure's elements.

Instances can be derived automatically by enabling the DeriveFoldable extension. For example, a derived instance for a binary tree might be:

{-# LANGUAGE DeriveFoldable #-}
data Tree a = Empty
            | Leaf a
            | Node (Tree a) a (Tree a)
    deriving Foldable

A more detailed description can be found in the Overview section of Data.Foldable#overview.

For the class laws see the Laws section of Data.Foldable#laws.

A monoid on applicative functors.

If defined, some and many should be the least solutions of the equations:

• some v = (:) Prelude.<$> v <*> many v

• many v = some v <|> pure []

Examples

>>> Nothing <|> Just 42Just 42

>>> [1, 2] <|> [3, 4][1,2,3,4]

>>> empty <|> print (2^15)32768

\mathcal{O}(n). lookup key assocs looks up a key in an association list. For the result to be Nothing, the list must be finite.

Examples

>>> lookup 2 []Nothing

>>> lookup 2 [(1, "first")]Nothing

>>> lookup 2 [(1, "first"), (2, "second"), (3, "third")]Just "second"

\mathcal{O}(n). filter, applied to a predicate and a list, returns the list of those elements that satisfy the predicate; i.e.,

filter p xs = [ x | x <- xs, p x]

Examples

>>> filter odd [1, 2, 3][1,3]

>>> filter (\l -> length l > 3) ["Hello", ", ", "World", "!"]["Hello","World"]

>>> filter (/= 3) [1, 2, 3, 4, 3, 2, 1][1,2,4,2,1]

intercalate xs xss is equivalent to (concat (intersperse xs xss)). It inserts the list xs in between the lists in xss and concatenates the result.

Laziness

intercalate has the following properties:

>>> take 5 (intercalate undefined ("Lorem" : undefined))"Lorem"

>>> take 6 (intercalate ", " ("Lorem" : undefined))"Lorem*** Exception: Prelude.undefined

Examples

>>> intercalate ", " ["Lorem", "ipsum", "dolor"]"Lorem, ipsum, dolor"

>>> intercalate [0, 1] [[2, 3], [4, 5, 6], []][2,3,0,1,4,5,6,0,1]

>>> intercalate [1, 2, 3] [[], []][1,2,3]

The sortBy function is the non-overloaded version of sort. The argument must be finite.

The supplied comparison relation is supposed to be reflexive and antisymmetric, otherwise, e. g., for _ _ -> GT, the ordered list simply does not exist. The relation is also expected to be transitive: if it is not then sortBy might fail to find an ordered permutation, even if it exists.

Examples

>>> sortBy (\(a,_) (b,_) -> compare a b) [(2, "world"), (4, "!"), (1, "Hello")][(1,"Hello"),(2,"world"),(4,"!")]

on b u x y runs the binary function b on the results of applying unary function u to two arguments x and y. From the opposite perspective, it transforms two inputs and combines the outputs.

(op `on` f) x y = f x `op` f y

Examples

>>> sortBy (compare `on` length) [[0, 1, 2], [0, 1], [], [0]][[],[0],[0,1],[0,1,2]]

>>> ((+) `on` length) [1, 2, 3] [-1]4

>>> ((,) `on` (*2)) 2 3(4,6)

Algebraic properties

• (*) `on` id = (*) -- (if (*) ∉ {⊥, const ⊥})

• ((*) `on` f) `on` g = (*) `on` (f . g)

• flip on f . flip on g = flip on (g . f)

cycle ties a finite list into a circular one, or equivalently, the infinite repetition of the original list. It is the identity on infinite lists.

Examples

>>> cycle []*** Exception: Prelude.cycle: empty list

>>> take 10 (cycle [42])[42,42,42,42,42,42,42,42,42,42]

>>> take 10 (cycle [2, 5, 7])[2,5,7,2,5,7,2,5,7,2]

>>> take 1 (cycle (42 : undefined))[42]

The Binary class provides put and get, methods to encode and decode a Haskell value to a lazy ByteString. It mirrors the Read and Show classes for textual representation of Haskell types, and is suitable for serialising Haskell values to disk, over the network.

For decoding and generating simple external binary formats (e.g. C structures), Binary may be used, but in general is not suitable for complex protocols. Instead use the Put and Get primitives directly.

Instances of Binary should satisfy the following property:

decode . encode == id

That is, the get and put methods should be the inverse of each other. A range of instances are provided for basic Haskell types.