Add Haddock `/Since: 4.7.0.0/` comments to new symbols
[packages/base.git] / GHC / Exts.hs
1 {-# LANGUAGE Unsafe #-}
2 {-# LANGUAGE MagicHash, UnboxedTuples, DeriveDataTypeable, TypeFamilies, MultiParamTypeClasses, FlexibleInstances #-}
3
4 -----------------------------------------------------------------------------
5 -- |
6 -- Module : GHC.Exts
7 -- Copyright : (c) The University of Glasgow 2002
8 -- License : see libraries/base/LICENSE
9 --
10 -- Maintainer : cvs-ghc@haskell.org
11 -- Stability : internal
12 -- Portability : non-portable (GHC Extensions)
13 --
14 -- GHC Extensions: this is the Approved Way to get at GHC-specific extensions.
15 --
16 -- Note: no other base module should import this module.
17 -----------------------------------------------------------------------------
18
19 module GHC.Exts
20 (
21 -- * Representations of some basic types
22 Int(..),Word(..),Float(..),Double(..),
23 Char(..),
24 Ptr(..), FunPtr(..),
25
26 -- * The maximum tuple size
27 maxTupleSize,
28
29 -- * Primitive operations
30 module GHC.Prim,
31 shiftL#, shiftRL#, iShiftL#, iShiftRA#, iShiftRL#,
32 uncheckedShiftL64#, uncheckedShiftRL64#,
33 uncheckedIShiftL64#, uncheckedIShiftRA64#,
34 isTrue#,
35
36 -- * Fusion
37 build, augment,
38
39 -- * Overloaded string literals
40 IsString(..),
41
42 -- * Debugging
43 breakpoint, breakpointCond,
44
45 -- * Ids with special behaviour
46 lazy, inline,
47
48 -- * Transform comprehensions
49 Down(..), groupWith, sortWith, the,
50
51 -- * Event logging
52 traceEvent,
53
54 -- * SpecConstr annotations
55 SpecConstrAnnotation(..),
56
57 -- * The call stack
58 currentCallStack,
59
60 -- * The Constraint kind
61 Constraint,
62
63 -- * Overloaded lists
64 IsList(..)
65 ) where
66
67 import Prelude
68
69 import GHC.Prim
70 import GHC.Base
71 import GHC.Word
72 import GHC.Int
73 import GHC.Ptr
74 import GHC.Stack
75 import Data.String
76 import Data.List
77 import Data.Data
78 import Data.Ord
79 import qualified Debug.Trace
80
81 -- XXX This should really be in Data.Tuple, where the definitions are
82 maxTupleSize :: Int
83 maxTupleSize = 62
84
85 -- | 'the' ensures that all the elements of the list are identical
86 -- and then returns that unique element
87 the :: Eq a => [a] -> a
88 the (x:xs)
89 | all (x ==) xs = x
90 | otherwise = error "GHC.Exts.the: non-identical elements"
91 the [] = error "GHC.Exts.the: empty list"
92
93 -- | The 'sortWith' function sorts a list of elements using the
94 -- user supplied function to project something out of each element
95 sortWith :: Ord b => (a -> b) -> [a] -> [a]
96 sortWith f = sortBy (\x y -> compare (f x) (f y))
97
98 -- | The 'groupWith' function uses the user supplied function which
99 -- projects an element out of every list element in order to first sort the
100 -- input list and then to form groups by equality on these projected elements
101 {-# INLINE groupWith #-}
102 groupWith :: Ord b => (a -> b) -> [a] -> [[a]]
103 groupWith f xs = build (\c n -> groupByFB c n (\x y -> f x == f y) (sortWith f xs))
104
105 groupByFB :: ([a] -> lst -> lst) -> lst -> (a -> a -> Bool) -> [a] -> lst
106 groupByFB c n eq xs0 = groupByFBCore xs0
107 where groupByFBCore [] = n
108 groupByFBCore (x:xs) = c (x:ys) (groupByFBCore zs)
109 where (ys, zs) = span (eq x) xs
110
111
112 -- -----------------------------------------------------------------------------
113 -- tracing
114
115 traceEvent :: String -> IO ()
116 traceEvent = Debug.Trace.traceEventIO
117 {-# DEPRECATED traceEvent "Use Debug.Trace.traceEvent or Debug.Trace.traceEventIO" #-} -- deprecated in 7.4
118
119
120 {- **********************************************************************
121 * *
122 * SpecConstr annotation *
123 * *
124 ********************************************************************** -}
125
126 -- Annotating a type with NoSpecConstr will make SpecConstr
127 -- not specialise for arguments of that type.
128
129 -- This data type is defined here, rather than in the SpecConstr module
130 -- itself, so that importing it doesn't force stupidly linking the
131 -- entire ghc package at runtime
132
133 data SpecConstrAnnotation = NoSpecConstr | ForceSpecConstr
134 deriving( Data, Typeable, Eq )
135
136
137 {- **********************************************************************
138 * *
139 * The IsList class *
140 * *
141 ********************************************************************** -}
142
143 -- | The 'IsList' class and its methods are intended to be used in
144 -- conjunction with the OverloadedLists extension.
145 --
146 -- /Since: 4.7.0.0/
147 class IsList l where
148 -- | The 'Item' type function returns the type of items of the structure
149 -- @l@.
150 type Item l
151
152 -- | The 'fromList' function constructs the structure @l@ from the given
153 -- list of @Item l@
154 fromList :: [Item l] -> l
155
156 -- | The 'fromListN' function takes the input list's length as a hint. Its
157 -- behaviour should be equivalent to 'fromList'. The hint can be used to
158 -- construct the structure @l@ more efficiently compared to 'fromList'. If
159 -- the given hint does not equal to the input list's length the behaviour of
160 -- 'fromListN' is not specified.
161 fromListN :: Int -> [Item l] -> l
162 fromListN _ = fromList
163
164 -- | The 'toList' function extracts a list of @Item l@ from the structure @l@.
165 -- It should satisfy fromList . toList = id.
166 toList :: l -> [Item l]
167
168 instance IsList [a] where
169 type (Item [a]) = a
170 fromList = id
171 toList = id