690e8a3f1cafd9c450cf0e62a58376a4107a8dad
[ghc.git] / libraries / ghc-prim / GHC / Types.hs
1 {-# LANGUAGE NoImplicitPrelude, TypeFamilies #-}
2 -----------------------------------------------------------------------------
3 -- |
4 -- Module : GHC.Types
5 -- Copyright : (c) The University of Glasgow 2009
6 -- License : see libraries/ghc-prim/LICENSE
7 --
8 -- Maintainer : cvs-ghc@haskell.org
9 -- Stability : internal
10 -- Portability : non-portable (GHC Extensions)
11 --
12 -- GHC type definitions.
13 -- Use GHC.Exts from the base package instead of importing this
14 -- module directly.
15 --
16 -----------------------------------------------------------------------------
17
18 module GHC.Types (
19 Bool(..), Char(..), Int(..), Word(..),
20 Float(..), Double(..),
21 Ordering(..), IO(..),
22 isTrue#
23 ) where
24
25 import GHC.Prim
26
27
28 infixr 5 :
29
30 data [] a = [] | a : [a]
31
32 data {-# CTYPE "HsBool" #-} Bool = False | True
33
34 {- | The character type 'Char' is an enumeration whose values represent
35 Unicode (or equivalently ISO\/IEC 10646) characters (see
36 <http://www.unicode.org/> for details). This set extends the ISO 8859-1
37 (Latin-1) character set (the first 256 characters), which is itself an extension
38 of the ASCII character set (the first 128 characters). A character literal in
39 Haskell has type 'Char'.
40
41 To convert a 'Char' to or from the corresponding 'Int' value defined
42 by Unicode, use 'Prelude.toEnum' and 'Prelude.fromEnum' from the
43 'Prelude.Enum' class respectively (or equivalently 'ord' and 'chr').
44 -}
45 data {-# CTYPE "HsChar" #-} Char = C# Char#
46
47 -- | A fixed-precision integer type with at least the range @[-2^29 .. 2^29-1]@.
48 -- The exact range for a given implementation can be determined by using
49 -- 'Prelude.minBound' and 'Prelude.maxBound' from the 'Prelude.Bounded' class.
50 data {-# CTYPE "HsInt" #-} Int = I# Int#
51
52 -- |A 'Word' is an unsigned integral type, with the same size as 'Int'.
53 data {-# CTYPE "HsWord" #-} Word = W# Word#
54
55 -- | Single-precision floating point numbers.
56 -- It is desirable that this type be at least equal in range and precision
57 -- to the IEEE single-precision type.
58 data {-# CTYPE "HsFloat" #-} Float = F# Float#
59
60 -- | Double-precision floating point numbers.
61 -- It is desirable that this type be at least equal in range and precision
62 -- to the IEEE double-precision type.
63 data {-# CTYPE "HsDouble" #-} Double = D# Double#
64
65 data Ordering = LT | EQ | GT
66
67 {- |
68 A value of type @'IO' a@ is a computation which, when performed,
69 does some I\/O before returning a value of type @a@.
70
71 There is really only one way to \"perform\" an I\/O action: bind it to
72 @Main.main@ in your program. When your program is run, the I\/O will
73 be performed. It isn't possible to perform I\/O from an arbitrary
74 function, unless that function is itself in the 'IO' monad and called
75 at some point, directly or indirectly, from @Main.main@.
76
77 'IO' is a monad, so 'IO' actions can be combined using either the do-notation
78 or the '>>' and '>>=' operations from the 'Monad' class.
79 -}
80 newtype IO a = IO (State# RealWorld -> (# State# RealWorld, a #))
81
82
83 -- | A data constructor used to box up all unlifted equalities
84 --
85 -- The type constructor is special in that GHC pretends that it
86 -- has kind (? -> ? -> Fact) rather than (* -> * -> *)
87 data (~) a b = Eq# ((~#) a b)
88
89 -- | A data constructor used to box up unlifted representational equalities.
90 --
91 -- The type constructor is special as GHC pretends the field of EqR# has type
92 -- (a ~R# b), which is not representable in Haskell, and turns it into a class.
93 data Coercible a b = MkCoercible ((~#) a b)
94
95 -- | Alias for tagToEnum#. Returns True of its parameter is 1# and False
96 -- if it is 0#.
97
98 {-# INLINE isTrue# #-}
99 isTrue# :: Int# -> Bool -- See Note [Optimizing isTrue#]
100 isTrue# x = tagToEnum# x
101
102 -- Note [Optimizing isTrue#]
103 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104 --
105 -- Current definition of isTrue# is a temporary workaround. We would like to
106 -- have functions isTrue# and isFalse# defined like this:
107 --
108 -- isTrue# :: Int# -> Bool
109 -- isTrue# 1# = True
110 -- isTrue# _ = False
111 --
112 -- isFalse# :: Int# -> Bool
113 -- isFalse# 0# = True
114 -- isFalse# _ = False
115 --
116 -- These functions would allow us to safely check if a tag can represent True
117 -- or False. Using isTrue# and isFalse# as defined above will not introduce
118 -- additional case into the code. When we scrutinize return value of isTrue#
119 -- or isFalse#, either explicitly in a case expression or implicitly in a guard,
120 -- the result will always be a single case expression (given that optimizations
121 -- are turned on). This results from case-of-case transformation. Consider this
122 -- code (this is both valid Haskell and Core):
123 --
124 -- case isTrue# (a ># b) of
125 -- True -> e1
126 -- False -> e2
127 --
128 -- Inlining isTrue# gives:
129 --
130 -- case (case (a ># b) of { 1# -> True; _ -> False } ) of
131 -- True -> e1
132 -- False -> e2
133 --
134 -- Case-of-case transforms that to:
135 --
136 -- case (a ># b) of
137 -- 1# -> case True of
138 -- True -> e1
139 -- False -> e2
140 -- _ -> case False of
141 -- True -> e1
142 -- False -> e2
143 --
144 -- Which is then simplified by case-of-known-constructor:
145 --
146 -- case (a ># b) of
147 -- 1# -> e1
148 -- _ -> e2
149 --
150 -- While we get good Core here, the code generator will generate very bad Cmm
151 -- if e1 or e2 do allocation. It will push heap checks into case alternatives
152 -- which results in about 2.5% increase in code size. Until this is improved we
153 -- just make isTrue# an alias to tagToEnum#. This is a temporary solution (if
154 -- you're reading this in 2023 then things went wrong).
155 --