GHC.Exts

base-4.8.2.0: Basic libraries

Copyright | (c) The University of Glasgow 2002
License | see libraries/base/LICENSE
Maintainer | cvs-ghc@haskell.org
Stability | internal
Portability | non-portable (GHC Extensions)
Safe Haskell | Unsafe
Language | Haskell2010

GHC.Exts

Contents

- Representations of some basic types
- The maximum tuple size
- Primitive operations
- Fusion
- Overloaded string literals
- Debugging
- Ids with special behaviour
- Safe coercions
- Transform comprehensions
- Event logging
- SpecConstr annotations
- The call stack
- The Constraint kind
- Overloaded lists

Description

GHC Extensions: this is the Approved Way to get at GHC-specific extensions.

Note: no other base module should import this module.

Synopsis

- data Int :: * = I# Int#
- data Word :: * = W# Word#
- data Float :: * = F# Float#
- data Double :: * = D# Double#
- data Char :: * = C# Char#
- data Ptr a = Ptr Addr#
- data FunPtr a = FunPtr Addr#
- maxTupleSize :: Int
- module GHC.Prim
- shiftL# :: Word# -> Int# -> Word#
- shiftRL# :: Word# -> Int# -> Word#
- iShiftL# :: Int# -> Int# -> Int#
- iShiftRA# :: Int# -> Int# -> Int#
- iShiftRL# :: Int# -> Int# -> Int#
- uncheckedShiftL64# :: Word# -> Int# -> Word#
- uncheckedShiftRL64# :: Word# -> Int# -> Word#
- uncheckedIShiftL64# :: Int# -> Int# -> Int#
- uncheckedIShiftRA64# :: Int# -> Int# -> Int#
- isTrue# :: Int# -> Bool
- build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
- augment :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a] -> [a]
- class IsString a where
  - fromString :: String -> a
- breakpoint :: a -> a
- breakpointCond :: Bool -> a -> a
- lazy :: a -> a
- inline :: a -> a
- coerce :: Coercible * a b => a -> b
- class Coercible a b
- newtype Down a = Down a
- groupWith :: Ord b => (a -> b) -> [a] -> [[a]]
- sortWith :: Ord b => (a -> b) -> [a] -> [a]
- the :: Eq a => [a] -> a
- traceEvent :: String -> IO ()
- data SpecConstrAnnotation
  - = NoSpecConstr
  - | ForceSpecConstr
- currentCallStack :: IO [String]
- data Constraint :: BOX
- class IsList l where
  - type Item l
  - fromList :: [Item l] -> l
  - fromListN :: Int -> [Item l] -> l
  - toList :: l -> [Item l]

# Representations of some basic types

data Int :: * Source

A fixed-precision integer type with at least the range `[-2^29 .. 2^29-1]`. The exact range for a given implementation can be determined by using `minBound` and `maxBound` from the `Bounded` class.

Constructors

I# Int# |

Instances

Bounded Int |
Enum Int |
Eq Int |
Integral Int |
Data Int |
Num Int |
Ord Int |
Read Int |
Real Int |
Show Int |
Ix Int |
Generic Int |
FiniteBits Int |
Bits Int |
Storable Int |
PrintfArg Int |
type Rep Int |

data Word :: * Source

A `Word` is an unsigned integral type, with the same size as `Int`.

Constructors

W# Word# |

Instances

Bounded Word |
Enum Word |
Eq Word |
Integral Word |
Data Word |
Num Word |
Ord Word |
Read Word |
Real Word |
Show Word |
Ix Word |
FiniteBits Word |
Bits Word |
Storable Word |
PrintfArg Word |

data Float :: * Source

Single-precision floating point numbers. It is desirable that this type be at least equal in range and precision to the IEEE single-precision type.

Constructors

F# Float# |

Instances

Eq Float |
Floating Float |
Data Float |
Ord Float |
Read Float |
RealFloat Float |
Generic Float |
Storable Float |
PrintfArg Float |
type Rep Float |

data Double :: * Source

Double-precision floating point numbers. It is desirable that this type be at least equal in range and precision to the IEEE double-precision type.

Constructors

D# Double# |

Instances

Eq Double |
Floating Double |
Data Double |
Ord Double |
Read Double |
RealFloat Double |
Generic Double |
Storable Double |
PrintfArg Double |
type Rep Double |

data Char :: * Source

The character type `Char` is an enumeration whose values represent Unicode (or equivalently ISO/IEC 10646) characters (see http://www.unicode.org/ for details). This set extends the ISO 8859-1 (Latin-1) character set (the first 256 characters), which is itself an extension of the ASCII character set (the first 128 characters). A character literal in Haskell has type `Char`.

To convert a `Char` to or from the corresponding `Int` value defined by Unicode, use `toEnum` and `fromEnum` from the `Enum` class respectively (or equivalently `ord` and `chr`).

Constructors

C# Char# |

Instances

Bounded Char |
Enum Char |
Eq Char |
Data Char |
Ord Char |
Read Char |
Show Char |
Ix Char |
Generic Char |
Storable Char |
IsChar Char |
PrintfArg Char |
IsString [Char] |
type Rep Char |

data Ptr a

A value of type ``Ptr` a` represents a pointer to an object, or an array of objects, which may be marshalled to or from Haskell values of type `a`.

The type `a` will often be an instance of class `Storable` which provides the marshalling operations. However this is not essential, and you can provide your own operations to access the pointer. For example you might write small foreign functions to get or set the fields of a C `struct`.

Constructors

Ptr Addr# |

Instances

Eq (Ptr a) |
(Data a, Typeable * a) => Data (Ptr a) |
Ord (Ptr a) |
Show (Ptr a) |
Storable (Ptr a) |

data FunPtr a

A value of type ``FunPtr` a` is a pointer to a function callable from foreign code. The type `a` will normally be a foreign type, a function type with zero or more arguments where

- the argument types are marshallable foreign types, i.e. `Char`, `Int`, `Double`, `Float`, `Bool`, `Int8`, `Int16`, `Int32`, `Int64`, `Word8`, `Word16`, `Word32`, `Word64`, ``Ptr` a`, ``FunPtr` a`, ``StablePtr` a` or a renaming of any of these using `newtype`.
- the return type is either a marshallable foreign type or has the form ``IO` t` where `t` is a marshallable foreign type or `()`.

A value of type ``FunPtr` a` may be a pointer to a foreign function, either returned by another foreign function or imported with a a static address import like

    foreign import ccall "stdlib.h &free"
      p_free :: FunPtr (Ptr a -> IO ())

or a pointer to a Haskell function created using a wrapper stub declared to produce a `FunPtr` of the correct type. For example:

    type Compare = Int -> Int -> Bool
    foreign import ccall "wrapper"
      mkCompare :: Compare -> IO (FunPtr Compare)

Calls to wrapper stubs like `mkCompare` allocate storage, which should be released with `freeHaskellFunPtr` when no longer required.

To convert `FunPtr` values to corresponding Haskell functions, one can define a dynamic stub for the specific foreign type, e.g.

    type IntFunction = CInt -> IO ()
    foreign import ccall "dynamic"
      mkFun :: FunPtr IntFunction -> IntFunction

Constructors

FunPtr Addr# |

Instances

Eq (FunPtr a) |
Ord (FunPtr a) |
Show (FunPtr a) |
Storable (FunPtr a) |

# The maximum tuple size

maxTupleSize :: Int

# Primitive operations

module GHC.Prim

shiftL# :: Word# -> Int# -> Word#

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

shiftRL# :: Word# -> Int# -> Word#

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

iShiftL# :: Int# -> Int# -> Int#

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

iShiftRA# :: Int# -> Int# -> Int#

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)

iShiftRL# :: Int# -> Int# -> Int#

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)

uncheckedShiftL64# :: Word# -> Int# -> Word#

uncheckedShiftRL64# :: Word# -> Int# -> Word#

uncheckedIShiftL64# :: Int# -> Int# -> Int#

uncheckedIShiftRA64# :: Int# -> Int# -> Int#

isTrue# :: Int# -> Bool Source

Alias for `tagToEnum#`. Returns True if its parameter is 1# and False if it is 0#.

# Fusion

build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]

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.

augment :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a] -> [a]

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.

# Overloaded string literals

class IsString a where

Class for string-like datastructures; used by the overloaded string extension (-XOverloadedStrings in GHC).

Methods

fromString :: String -> a

Instances

IsString [Char] |

# Debugging

breakpoint :: a -> a

breakpointCond :: Bool -> a -> a

# Ids with special behaviour

lazy :: a -> a Source

The `lazy` function restrains strictness analysis a little. The call `lazy e` means the same as `e`, but `lazy` has a magical property so far as strictness analysis is concerned: it is lazy in its first argument, even though its semantics is strict. After strictness analysis has run, calls to `lazy` are inlined to be the identity function.

This behaviour is occasionally useful when controlling evaluation order. Notably, `lazy` is used in the library definition of `par`:

    par :: a -> b -> b
    par x y = case (par# x) of _ -> lazy y

If `lazy` were not lazy, `par` would look strict in `y` which would defeat the whole purpose of `par`.

Like `seq`, the argument of `lazy` can have an unboxed type.

inline :: a -> a Source

The call `inline f` arranges that `f` is inlined, regardless of its size. More precisely, the call `inline f` rewrites to the right-hand side of `f`'s definition. This allows the programmer to control inlining from a particular call site rather than the definition site of the function (c.f. `INLINE` pragmas).

This inlining occurs regardless of the argument to the call or the size of `f`'s definition; it is unconditional. The main caveat is that `f`'s definition must be visible to the compiler; it is therefore recommended to mark the function with an `INLINABLE` pragma at its definition so that GHC guarantees to record its unfolding regardless of size.

If no inlining takes place, the `inline` function expands to the identity function in Phase zero, so its use imposes no overhead.

# Safe coercions

These are available from the Trustworthy module Data.Coerce as well

Since: 4.7.0.0

coerce :: Coercible * a b => a -> b Source

The function `coerce` allows you to safely convert between values of types that have the same representation with no run-time overhead. In the simplest case you can use it instead of a newtype constructor, to go from the newtype's concrete type to the abstract type. But it also works in more complicated settings, e.g. converting a list of newtypes to a list of concrete types.

class Coercible a b Source

This two-parameter class has instances for types `a` and `b` if the compiler can infer that they have the same representation. This class does not have regular instances; instead they are created on-the-fly during type-checking. Trying to manually declare an instance of `Coercible` is an error.

Nevertheless one can pretend that the following three kinds of instances exist. First, as a trivial base-case:

    instance a a

Furthermore, for every type constructor there is an instance that allows to coerce under the type constructor. For example, let `D` be a prototypical type constructor (`data` or `newtype`) with three type arguments, which have roles `nominal`, `representational` resp. `phantom`. Then there is an instance of the form

    instance Coercible b b' => Coercible (D a b c) (D a b' c')

Note that the `nominal` type arguments are equal, the `representational` type arguments can differ, but need to have a `Coercible` instance themself, and the `phantom` type arguments can be changed arbitrarily.

The third kind of instance exists for every `newtype NT = MkNT T` and comes in two variants, namely

    instance Coercible a T => Coercible a NT

    instance Coercible T b => Coercible NT b

This instance is only usable if the constructor `MkNT` is in scope.

If, as a library author of a type constructor like `Set a`, you want to prevent a user of your module to write `coerce :: Set T -> Set NT`, you need to set the role of `Set`'s type parameter to `nominal`, by writing

    type role Set nominal

For more details about this feature, please refer to Safe Coercions by Joachim Breitner, Richard A. Eisenberg, Simon Peyton Jones and Stephanie Weirich.

Since: 4.7.0.0

# Transform comprehensions

newtype Down a

The `Down` type allows you to reverse sort order conveniently. A value of type ``Down` a` contains a value of type `a` (represented as ``Down` a`). If `a` has an ``Ord`` instance associated with it then comparing two values thus wrapped will give you the opposite of their normal sort order. This is particularly useful when sorting in generalised list comprehensions, as in: `then sortWith by `Down` x`

Provides `Show` and `Read` instances (since: 4.7.0.0).

Since: 4.6.0.0

Constructors

Down a |

Instances

Eq a => Eq (Down a) |
Ord a => Ord (Down a) |
Read a => Read (Down a) |
Show a => Show (Down a) |

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

The `groupWith` function uses the user supplied function which projects an element out of every list element in order to first sort the input list and then to form groups by equality on these projected elements

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

The `sortWith` function sorts a list of elements using the user supplied function to project something out of each element

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

`the` ensures that all the elements of the list are identical and then returns that unique element

# Event logging

traceEvent :: String -> IO ()

Deprecated: Use `traceEvent` or `traceEventIO`

# SpecConstr annotations

data SpecConstrAnnotation

Constructors

NoSpecConstr |
ForceSpecConstr |

Instances

Eq SpecConstrAnnotation |
Data SpecConstrAnnotation |

# The call stack

currentCallStack :: IO [String]

returns a '[String]' representing the current call stack. This can be useful for debugging.

The implementation uses the call-stack simulation maintined by the profiler, so it only works if the program was compiled with `-prof` and contains suitable SCC annotations (e.g. by using `-fprof-auto`). Otherwise, the list returned is likely to be empty or uninformative.

Since: 4.5.0.0

# The Constraint kind

data Constraint :: BOX Source

# Overloaded lists

class IsList l where

The `IsList` class and its methods are intended to be used in conjunction with the OverloadedLists extension.

Since: 4.7.0.0

Minimal complete definition

fromList, toList

Associated Types

type Item l

The `Item` type function returns the type of items of the structure `l`.

Methods

fromList :: [Item l] -> l

The `fromList` function constructs the structure `l` from the given list of `Item l`

fromListN :: Int -> [Item l] -> l

The `fromListN` function takes the input list's length as a hint. Its behaviour should be equivalent to `fromList`. The hint can be used to construct the structure `l` more efficiently compared to `fromList`. If the given hint does not equal to the input list's length the behaviour of `fromListN` is not specified.

toList :: l -> [Item l]

The `toList` function extracts a list of `Item l` from the structure `l`. It should satisfy fromList . toList = id.

Instances

IsList Version | Since: 4.8.0.0
IsList [a] |