GHC.Internal.Types

The character type Char represents Unicode codespace and its elements are code points as in definitions D9 and D10 of the Unicode Standard.

Character literals in Haskell are single-quoted: 'Q', 'Я' or 'Ω'. To represent a single quote itself use '\'', and to represent a backslash use '\\'. The full grammar can be found in the section 2.6 of the Haskell 2010 Language Report.

To specify a character by its code point one can use decimal, hexadecimal or octal notation: '\65', '\x41' and '\o101' are all alternative forms of 'A'. The largest code point is '\x10ffff'.

There is a special escape syntax for ASCII control characters:

Data.Char provides utilities to work with Char.

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 Prelude.minBound and Prelude.maxBound from the Prelude.Bounded class.

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

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.

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.

A value of type IO a is a computation which, when performed, does some I/O before returning a value of type a.

There is really only one way to "perform" an I/O action: bind it to Main.main in your program. When your program is run, the I/O will be performed. It isn't possible to perform I/O from an arbitrary function, unless that function is itself in the IO monad and called at some point, directly or indirectly, from Main.main.

IO is a monad, so IO actions can be combined using either the do-notation or the Prelude.>> and Prelude.>>= operations from the Prelude.Monad class.

The builtin linked list type.

In Haskell, lists are one of the most important data types as they are often used analogous to loops in imperative programming languages. These lists are singly linked, which makes them unsuited for operations that require \mathcal{O}(1) access. Instead, they are intended to be traversed.

You can use List a or [a] in type signatures:

length :: [a] -> Int

or

length :: List a -> Int

They are fully equivalent, and List a will be normalised to [a].

Usage

Lists are constructed recursively using the right-associative constructor operator (or cons) (:) :: a -> [a] -> [a], which prepends an element to a list, and the empty list [].

(1 : 2 : 3 : []) == (1 : (2 : (3 : []))) == [1, 2, 3]

Lists can also be constructed using list literals of the form [x_1, x_2, ..., x_n] which are syntactic sugar and, unless -XOverloadedLists is enabled, are translated into uses of (:) and []

Data.String.String literals, like "I 💜 hs", are translated into Lists of characters, ['I', ' ', '💜', ' ', 'h', 's'].

Implementation

Internally and in memory, all the above are represented like this, with arrows being pointers to locations in memory.

╭───┬───┬──╮   ╭───┬───┬──╮   ╭───┬───┬──╮   ╭────╮
│(:)│   │ ─┼──>│(:)│   │ ─┼──>│(:)│   │ ─┼──>│ [] │
╰───┴─┼─┴──╯   ╰───┴─┼─┴──╯   ╰───┴─┼─┴──╯   ╰────╯
      v              v              v
      1              2              3

Examples

>>> ['H', 'a', 's', 'k', 'e', 'l', 'l']
"Haskell"

>>> 1 : [4, 1, 5, 9]
[1,4,1,5,9]

>>> [] : [] : []
[[],[]]

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

SPEC is used by GHC in the SpecConstr pass in order to inform the compiler when to be particularly aggressive. In particular, it tells GHC to specialize regardless of size or the number of specializations. However, not all loops fall into this category.

Libraries can specify this by using SPEC data type to inform which loops should be aggressively specialized. For example, instead of

loop x where loop arg = ...

write

loop SPEC x where loop !_ arg = ...

There is no semantic difference between SPEC and SPEC2, we just need a type with two constructors lest it is optimised away before SpecConstr.

This type is reexported from GHC.Exts since GHC 9.0 and base-4.15. For compatibility with earlier releases import it from GHC.Internal.Types in ghc-internal package.

(Kind) This is the kind of type-level symbols.

The type constructor Any :: forall k. k is a type to which you can unsafely coerce any type, and back.

For unsafeCoerce this means for all lifted types t that unsafeCoerce (unsafeCoerce x :: Any) :: t is equivalent to x and safe.

The same is true for *all* types when using unsafeCoerce# :: forall (r1 :: RuntimeRep) (r2 :: RuntimeRep) (a :: TYPE r1) (b :: TYPE r2). a -> b but only if you instantiate r1 and r2 to the same runtime representation. For example using (unsafeCoerce# :: forall (a :: TYPE IntRep) (b :: TYPE IntRep). a -> b) x is fine, but (unsafeCoerce# :: forall (a :: TYPE IntRep) (b :: TYPE FloatRep). a -> b) will likely cause seg-faults or worse. For this resason, users should always prefer unsafeCoerce over unsafeCoerce# when possible.

Here are some more examples: bad_a1 :: Any (TYPE 'IntRep) bad_a1 = unsafeCoerce# True

bad_a2 :: Any (TYPE ('BoxedRep 'UnliftedRep)) bad_a2 = unsafeCoerce# True Here bad_a1 is bad because we started with True :: (Bool :: Type), represented by a boxed heap pointer, and coerced it to a1 :: Any (TYPE 'IntRep), whose representation is a non-pointer integer. That's why we had to use unsafeCoerce#; it is really unsafe because it can change representations. Similarly bad_a2 is bad because although both True and bad_a2 are represented by a heap pointer, True is lifted but bad_a2@ is not; bugs here may be rather subtle.

If you must use unsafeCoerce# to cast to Any, type annotations are recommended to make sure that Any has the correct kind. As casting between different runtimereps is unsound. For example to cast a ByteArray# to Any you might use: unsafeCoerce# b :: (Any :: TYPE ('BoxedRep 'Unlifted))

Lifted, homogeneous equality. By lifted, we mean that it can be bogus (deferred type error). By homogeneous, the two types a and b must have the same kinds.

Lifted, heterogeneous equality. By lifted, we mean that it can be bogus (deferred type error). By heterogeneous, the two types a and b might have different kinds. Because ~~ can appear unexpectedly in error messages to users who do not care about the difference between heterogeneous equality ~~ and homogeneous equality ~, this is printed as ~ unless -fprint-equality-relations is set.

In 0.7.0, the fixity was set to infix 4 to match the fixity of Data.Type.Equality.:~~:.

Coercible is a two-parameter class that 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 Coercible 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.

Whether a boxed type is lifted or unlifted.

GHC maintains a property that the kind of all inhabited types (as distinct from type constructors or type-level data) tells us the runtime representation of values of that type. This datatype encodes the choice of runtime value. Note that TYPE is parameterised by RuntimeRep; this is precisely what we mean by the fact that a type's kind encodes the runtime representation.

For boxed values (that is, values that are represented by a pointer), a further distinction is made, between lifted types (that contain ⊥), and unlifted ones (that don't).

The runtime representation of lifted types.

The runtime representation of unlifted types.

The kind of types with lifted values. For example Int :: Type.

The kind of boxed, unlifted values, for example Array# or a user-defined unlifted data type, using -XUnliftedDataTypes.

The kind of lifted constraints

The runtime representation of a zero-width tuple, represented by no bits at all

The kind of the empty unboxed tuple type (# #)

Length of a SIMD vector type

Element of a SIMD vector type

Data type Dict provides a simple way to wrap up a (lifted) constraint as a type