GHC.Internal.Base

Uninhabited data type

Since Void values logically don't exist, this witnesses the logical reasoning tool of "ex falso quodlibet".

>>> let x :: Either Void Int; x = Right 5>>> :{case x of    Right r -> r    Left l  -> absurd l:}5

If Void is uninhabited then any Functor that holds only values of type Void is holding no values. It is implemented in terms of fmap absurd.

The class of semigroups (types with an associative binary operation).

Instances should satisfy the following:

Associativity

x <> (y <> z) = (x <> y) <> z

You can alternatively define sconcat instead of (<>), in which case the laws are:

Unit

sconcat (pure x) = x

Multiplication

sconcat (join xss) = sconcat (fmap sconcat xss)

The class of monoids (types with an associative binary operation that has an identity). Instances should satisfy the following:

Right identity

x <> mempty = x

Left identity

mempty <> x = x

Associativity

x <> (y <> z) = (x <> y) <> z

(

Semigroup

law)

Concatenation

mconcat = foldr (<>) mempty

You can alternatively define mconcat instead of mempty, in which case the laws are:

Unit

mconcat (pure x) = x

Multiplication

mconcat (join xss) = mconcat (fmap mconcat xss)

Subclass

mconcat (toList xs) = sconcat xs

The method names refer to the monoid of lists under concatenation, but there are many other instances.

Some types can be viewed as a monoid in more than one way, e.g. both addition and multiplication on numbers. In such cases we often define newtypes and make those instances of Monoid, e.g. Data.Semigroup.Sum and Data.Semigroup.Product.

NOTE: Semigroup is a superclass of Monoid since base-4.11.0.0.

A type f is a Functor if it provides a function fmap which, given any types a and b lets you apply any function from (a -> b) to turn an f a into an f b, preserving the structure of f. Furthermore f needs to adhere to the following:

Identity

fmap id == id

Composition

fmap (f . g) == fmap f . fmap g

Note, that the second law follows from the free theorem of the type fmap and the first law, so you need only check that the former condition holds. See these articles by School of Haskell or David Luposchainsky for an explanation.

A functor with application, providing operations to

• embed pure expressions (pure), and

• sequence computations and combine their results (<*> and liftA2).

A minimal complete definition must include implementations of pure and one of either <*> or liftA2. If it defines both, then they must behave the same as their default definitions:

(<*>) = liftA2 id

liftA2 f x y = f Prelude.<$> x <*> y

Further, any definition must satisfy the following:

Identity

pure id <*> v = v

Composition

pure (.) <*> u <*> v <*> w = u <*> (v <*> w)

Homomorphism

pure f <*> pure x = pure (f x)

Interchange

u <*> pure y = pure ($ y) <*> u

The other methods have the following default definitions, which may be overridden with equivalent specialized implementations:

• u *> v = (id <$ u) <*> v

• u <* v = liftA2 const u v

As a consequence of these laws, the Functor instance for f will satisfy

• fmap f x = pure f <*> x

It may be useful to note that supposing

forall x y. p (q x y) = f x . g y

it follows from the above that

liftA2 p (liftA2 q u v) = liftA2 f u . liftA2 g v

If f is also a Monad, it should satisfy

• pure = return

• m1 <*> m2 = m1 >>= (\x1 -> m2 >>= (\x2 -> return (x1 x2)))

• (*>) = (>>)

(which implies that pure and <*> satisfy the applicative functor laws).

A variant of <*> with the types of the arguments reversed. It differs from flip (<*>) in that the effects are resolved in the order the arguments are presented.

Examples

>>> (<**>) (print 1) (id <$ print 2)12

>>> flip (<*>) (print 1) (id <$ print 2)21

>>> ZipList [4, 5, 6] <**> ZipList [(+1), (*2), (/3)]ZipList {getZipList = [5.0,10.0,2.0]}

Lift a function to actions. Equivalent to Functor's fmap but implemented using only Applicative's methods: liftA f a = pure f <*> a

As such this function may be used to implement a Functor instance from an Applicative one.

This function can be used to define `fmap = liftA`, if Applicative is already defined for a data type.

Examples

Using the Applicative instance for Lists:

>>> liftA (+1) [1, 2][2,3]

Or the Applicative instance for Maybe

>>> liftA (+1) (Just 3)Just 4

Lift a ternary function to actions.

Sequence two Applicative actions, discarding the result of the first one.

Defined as `thenA fa fb = (id fa) <* fb`.

This can be used to explicitly define `(*>) = thenA`, which is the default definition.

The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.

'join bss' can be understood as the do expression

do bs <- bss
   bs

Examples

>>> join [[1, 2, 3], [4, 5, 6], [7, 8, 9]][1,2,3,4,5,6,7,8,9]

>>> join (Just (Just 3))Just 3

A common use of join is to run an IO computation returned from an GHC.Conc.STM transaction, since GHC.Conc.STM transactions can't perform IO directly. Recall that

GHC.Internal.Conc.atomically :: STM a -> IO a

is used to run GHC.Conc.STM transactions atomically. So, by specializing the types of GHC.Internal.Conc.atomically and join to

GHC.Internal.Conc.atomically :: STM (IO b) -> IO (IO b)
join       :: IO (IO b)  -> IO b

we can compose them as

join . GHC.Internal.Conc.atomically :: STM (IO b) -> IO b

to run an GHC.Conc.STM transaction and the IO action it returns.

The Monad class defines the basic operations over a monad, a concept from a branch of mathematics known as category theory. From the perspective of a Haskell programmer, however, it is best to think of a monad as an abstract datatype of actions. Haskell's do expressions provide a convenient syntax for writing monadic expressions.

Instances of Monad should satisfy the following:

Left identity

return a >>= k = k a

Right identity

m >>= return = m

Associativity

m >>= (\x -> k x >>= h) = (m >>= k) >>= h

Furthermore, the Monad and Applicative operations should relate as follows:

• pure = return

• m1 <*> m2 = m1 >>= (\x1 -> m2 >>= (\x2 -> return (x1 x2)))

The above laws imply:

• fmap f xs  =  xs >>= return . f

• (>>) = (*>)

and that pure and (<*>) satisfy the applicative functor laws.

The instances of Monad for GHC.List.List, Data.Maybe.Maybe and System.IO.IO defined in the Prelude satisfy these laws.

Same as >>=, but with the arguments interchanged.

as >>= f == f =<< as

Conditional execution of Applicative expressions. For example,

Examples

when debug (putStrLn "Debugging")

will output the string Debugging if the Boolean value debug is True, and otherwise do nothing.

>>> putStr "pi:" >> when False (print 3.14159)pi:

Evaluate each action in the sequence from left to right, and collect the results.

mapM f is equivalent to sequence . map f.

Promote a function to a monad. This is equivalent to fmap but specialised to Monads.

This function can be used to define `fmap = liftM`, if Monad is already defined for a data type.

Promote a function to a monad, scanning the monadic arguments from left to right.

This function can be used to define `liftA2 = liftM2`, if Monad is already defined for a data type.

Examples

>>> liftM2 (+) [0,1] [0,2][0,2,1,3]

>>> liftM2 (+) (Just 1) NothingNothing

>>> liftM2 (+) (+ 3) (* 2) 518

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

In many situations, the liftM operations can be replaced by uses of ap, which promotes function application.

return f `ap` x1 `ap` ... `ap` xn

is equivalent to

liftM<n> f x1 x2 ... xn

This function can be used to define `(*) = ap`, if Monad is already defined for a data type.

Examples

>>> pure (\x y z -> x + y * z) `ap` Just 1 `ap` Just 5 `ap` Just 10Just 51

Sequence two monadic actions, discarding the result of the first one.

Defined as `thenM ma mb = ma >>= const mb`.

This can be used to define `(*>) = thenM`.

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

Monads that also support choice and failure.

Non-empty (and non-strict) list type.

foldr, applied to a binary operator, a starting value (typically the right-identity of the operator), and a list, reduces the list using the binary operator, from right to left:

foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)

A list producer that can be fused with foldr. This function is merely

   build g = g (:) []

but GHC's simplifier will transform an expression of the form foldr k z (build g), which may arise after inlining, to g k z, which avoids producing an intermediate list.

A list producer that can be fused with foldr. This function is merely

   augment g xs = g (:) xs

but GHC's simplifier will transform an expression of the form foldr k z (augment g xs), which may arise after inlining, to g k (foldr k z xs), which avoids producing an intermediate list.

\mathcal{O}(n). map f xs is the list obtained by applying f to each element of xs, i.e.,

map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
map f [x1, x2, ...] == [f x1, f x2, ...]

this means that map id == id

Examples

>>> map (+1) [1, 2, 3][2,3,4]

>>> map id [1, 2, 3][1,2,3]

>>> map (\n -> 3 * n + 1) [1, 2, 3][4,7,10]

(++) appends two lists, i.e.,

[x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
[x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]

If the first list is not finite, the result is the first list.

Performance considerations

This function takes linear time in the number of elements of the first list. Thus it is better to associate repeated applications of (++) to the right (which is the default behaviour): xs ++ (ys ++ zs) or simply xs ++ ys ++ zs, but not (xs ++ ys) ++ zs. For the same reason GHC.Internal.Data.List.concat = GHC.Internal.Data.List.foldr (++) [] has linear performance, while GHC.Internal.Data.List.foldl (++) [] is prone to quadratic slowdown

Examples

>>> [1, 2, 3] ++ [4, 5, 6][1,2,3,4,5,6]

>>> [] ++ [1, 2, 3][1,2,3]

>>> [3, 2, 1] ++ [][3,2,1]

otherwise is defined as the value True. It helps to make guards more readable. eg.

 f x | x < 0     = ...
     | otherwise = ...

String is an alias for a list of characters.

String constants in Haskell are values of type String. That means if you write a string literal like "hello world", it will have the type [Char], which is the same as String.

Note: You can ask the compiler to automatically infer different types with the -XOverloadedStrings language extension, for example "hello world" :: Text. See Data.String.IsString for more information.

Because String is just a list of characters, you can use normal list functions to do basic string manipulation. See Data.List for operations on lists.

Performance considerations

[Char] is a relatively memory-inefficient type. It is a linked list of boxed word-size characters, internally it looks something like:

╭─────┬───┬──╮  ╭─────┬───┬──╮  ╭─────┬───┬──╮  ╭────╮
│ (:) │   │ ─┼─>│ (:) │   │ ─┼─>│ (:) │   │ ─┼─>│ [] │
╰─────┴─┼─┴──╯  ╰─────┴─┼─┴──╯  ╰─────┴─┼─┴──╯  ╰────╯
        v               v               v
       'a'             'b'             'c'

The String "abc" will use 5*3+1 = 16 (in general 5n+1) words of space in memory.

Furthermore, operations like (++) (string concatenation) are O(n) (in the left argument).

For historical reasons, the base library uses String in a lot of places for the conceptual simplicity, but library code dealing with user-data should use the text package for Unicode text, or the the bytestring package for binary data.

The Prelude.fromEnum method restricted to the type Data.Char.Char.

This String equality predicate is used when desugaring pattern-matches against strings.

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

If the first argument evaluates to True, then the result is the second argument. Otherwise an Control.Exception.AssertionFailed exception is raised, containing a String with the source file and line number of the call to assert.

Assertions can normally be turned on or off with a compiler flag (for GHC, assertions are normally on unless optimisation is turned on with -O or the -fignore-asserts option is given). When assertions are turned off, the first argument to assert is ignored, and the second argument is returned as the result.

const x y always evaluates to x, ignoring its second argument.

const x = \_ -> x

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

Examples

>>> const 42 "hello"42

>>> map (const 42) [0..3][42,42,42,42]

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

flip f takes its (first) two arguments in the reverse order of f.

prop> flip f x y = f y x

prop> flip . flip = id

Examples

>>> flip (++) "hello" "world""worldhello"

>>> let (.>) = flip (.) in (+1) .> show $ 5"6"

($) is the function application operator.

Applying ($) to a function f and an argument x gives the same result as applying f to x directly. The definition is akin to this:

($) :: (a -> b) -> a -> b
($) f x = f x

This is id specialized from a -> a to (a -> b) -> (a -> b) which by the associativity of (->) is the same as (a -> b) -> a -> b.

On the face of it, this may appear pointless! But it's actually one of the most useful and important operators in Haskell.

The order of operations is very different between ($) and normal function application. Normal function application has precedence 10 - higher than any operator - and associates to the left. So these two definitions are equivalent:

expr = min 5 1 + 5
expr = ((min 5) 1) + 5

($) has precedence 0 (the lowest) and associates to the right, so these are equivalent:

expr = min 5 $ 1 + 5
expr = (min 5) (1 + 5)

Examples

A common use cases of ($) is to avoid parentheses in complex expressions.

For example, instead of using nested parentheses in the following Haskell function:

-- | Sum numbers in a string: strSum "100  5 -7" == 98
strSum :: String -> Int
strSum s = sum (mapMaybe readMaybe (words s))

we can deploy the function application operator:

-- | Sum numbers in a string: strSum "100  5 -7" == 98
strSum :: String -> Int
strSum s = sum $ mapMaybe readMaybe $ words s

($) is also used as a section (a partially applied operator), in order to indicate that we wish to apply some yet-unspecified function to a given value. For example, to apply the argument 5 to a list of functions:

applyFive :: [Int]
applyFive = map ($ 5) [(+1), (2^)]
>>> [6, 32]

Technical Remark (Representation Polymorphism)

($) is fully representation-polymorphic. This allows it to also be used with arguments of unlifted and even unboxed kinds, such as unboxed integers:

fastMod :: Int -> Int -> Int
fastMod (I# x) (I# m) = I# $ remInt# x m

Strict (call-by-value) application operator. It takes a function and an argument, evaluates the argument to weak head normal form (WHNF), then calls the function with that value.

until p f yields the result of applying f until p holds.

asTypeOf is a type-restricted version of const. It is usually used as an infix operator, and its typing forces its first argument (which is usually overloaded) to have the same type as the second.

Returns the tag of a constructor application; this function was once used by the deriving code for Eq, Ord and Enum.

Used to implement quot for the Integral typeclass. This performs integer division on its two parameters, truncated towards zero.

Example

>>> quotInt 10 25

>>> quot 10 25

Used to implement rem for the Integral typeclass. This gives the remainder after integer division of its two parameters, satisfying

((x `quot` y) * y) + (x `rem` y) == x

Example

>>> remInt 3 21

>>> rem 3 21

Used to implement div for the Integral typeclass. This performs integer division on its two parameters, truncated towards negative infinity.

Example

>>> 10 `divInt` 25

>>> 10 `div` 25

Used to implement mod for the Integral typeclass. This performs the modulo operation, satisfying

((x `div` y) * y) + (x `mod` y) == x

Example

>>> 7 `modInt` 31

>>> 7 `mod` 31

Used to implement quotRem for the Integral typeclass. This gives a tuple equivalent to

(quot x y, mod x y)

Example

>>> quotRemInt 10 2(5,0)

>>> quotRem 10 2(5,0)

Used to implement divMod for the Integral typeclass. This gives a tuple equivalent to

(div x y, mod x y)

Example

>>> divModInt 10 2(5,0)

>>> divMod 10 2(5,0)

This function is used to implement branchless shifts. If the number of bits to shift is greater than or equal to the type size in bits, then the shift must return 0. Instead of doing a test, we use a mask obtained via this function which is branchless too.

shift_mask m b | b < m = 0xFF..FF | otherwise = 0

Shift the argument left by the specified number of bits (which must be non-negative).

Shift the argument right by the specified number of bits (which must be non-negative). The RL means "right, logical" (as opposed to RA for arithmetic) (although an arithmetic right shift wouldn't make sense for Word#)

Shift the argument left by the specified number of bits (which must be non-negative).

Shift the argument right (signed) by the specified number of bits (which must be non-negative). The RA means "right, arithmetic" (as opposed to RL for logical)

Shift the argument right (unsigned) by the specified number of bits (which must be non-negative). The RL means "right, logical" (as opposed to RA for arithmetic)