Types.hs 11.5 KB
Newer Older
1 2 3 4 5 6
{-# LANGUAGE CPP #-}
{-# LANGUAGE DerivingStrategies #-}
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
{-# LANGUAGE MagicHash #-}
{-# LANGUAGE NoImplicitPrelude #-}
{-# LANGUAGE StandaloneDeriving #-}
7
{-# LANGUAGE Trustworthy #-}
8 9
{-# OPTIONS_GHC -Wno-unused-binds #-}
-- XXX -Wno-unused-binds stops us warning about unused constructors,
Ian Lynagh's avatar
Ian Lynagh committed
10
-- but really we should just remove them if we don't want them
11

12
-----------------------------------------------------------------------------
13
-- |
14 15
-- Module      :  Foreign.C.Types
-- Copyright   :  (c) The FFI task force 2001
16
-- License     :  BSD-style (see the file libraries/base/LICENSE)
17
--
18
-- Maintainer  :  ffi@haskell.org
19 20
-- Stability   :  provisional
-- Portability :  portable
21
--
22
-- Mapping of C types to corresponding Haskell types.
23 24 25 26
--
-----------------------------------------------------------------------------

module Foreign.C.Types
Don Stewart's avatar
Don Stewart committed
27 28 29
        ( -- * Representations of C types
          -- $ctypes

30 31 32 33 34 35
          -- ** Platform differences
          -- | This module contains platform specific information about types.
          --   __/As such the types presented on this page reflect the platform
          --   on which the documentation was generated and may not coincide with
          --   the types on your platform./__

Don Stewart's avatar
Don Stewart committed
36
          -- ** Integral types
Gabor Greif's avatar
Gabor Greif committed
37
          -- | These types are represented as @newtype@s of
Don Stewart's avatar
Don Stewart committed
38 39 40 41 42
          -- types in "Data.Int" and "Data.Word", and are instances of
          -- 'Prelude.Eq', 'Prelude.Ord', 'Prelude.Num', 'Prelude.Read',
          -- 'Prelude.Show', 'Prelude.Enum', 'Typeable', 'Storable',
          -- 'Prelude.Bounded', 'Prelude.Real', 'Prelude.Integral' and
          -- 'Bits'.
43 44 45 46
          CChar(..),    CSChar(..),   CUChar(..)
        , CShort(..),   CUShort(..),  CInt(..),      CUInt(..)
        , CLong(..),    CULong(..)
        , CPtrdiff(..), CSize(..),    CWchar(..),    CSigAtomic(..)
Ryan Scott's avatar
Ryan Scott committed
47
        , CLLong(..),   CULLong(..), CBool(..)
48
        , CIntPtr(..),  CUIntPtr(..), CIntMax(..),   CUIntMax(..)
Don Stewart's avatar
Don Stewart committed
49 50

          -- ** Numeric types
ian@well-typed.com's avatar
ian@well-typed.com committed
51
          -- | These types are represented as @newtype@s of basic
Don Stewart's avatar
Don Stewart committed
52 53 54
          -- foreign types, and are instances of
          -- 'Prelude.Eq', 'Prelude.Ord', 'Prelude.Num', 'Prelude.Read',
          -- 'Prelude.Show', 'Prelude.Enum', 'Typeable' and 'Storable'.
55
        , CClock(..),   CTime(..),    CUSeconds(..), CSUSeconds(..)
Don Stewart's avatar
Don Stewart committed
56

57
        -- extracted from CTime, because we don't want this comment in
58
        -- the Haskell language reports:
59

ian@well-typed.com's avatar
ian@well-typed.com committed
60
        -- | To convert 'CTime' to 'Data.Time.UTCTime', use the following:
61
        --
ian@well-typed.com's avatar
ian@well-typed.com committed
62
        -- > \t -> posixSecondsToUTCTime (realToFrac t :: POSIXTime)
63 64
        --

Don Stewart's avatar
Don Stewart committed
65
          -- ** Floating types
Gabor Greif's avatar
Gabor Greif committed
66
          -- | These types are represented as @newtype@s of
Don Stewart's avatar
Don Stewart committed
67 68 69 70
          -- 'Prelude.Float' and 'Prelude.Double', and are instances of
          -- 'Prelude.Eq', 'Prelude.Ord', 'Prelude.Num', 'Prelude.Read',
          -- 'Prelude.Show', 'Prelude.Enum', 'Typeable', 'Storable',
          -- 'Prelude.Real', 'Prelude.Fractional', 'Prelude.Floating',
71 72 73 74 75
          -- 'Prelude.RealFrac' and 'Prelude.RealFloat'. That does mean
          -- that `CFloat`'s (respectively `CDouble`'s) instances of
          -- 'Prelude.Eq', 'Prelude.Ord', 'Prelude.Num' and
          -- 'Prelude.Fractional' are as badly behaved as `Prelude.Float`'s
          -- (respectively `Prelude.Double`'s).
76
        , CFloat(..),   CDouble(..)
77 78 79
        -- XXX GHC doesn't support CLDouble yet
        -- , CLDouble(..)

80 81 82 83
          -- See Note [Exporting constructors of marshallable foreign types]
          -- in Foreign.Ptr for why the constructors for these newtypes are
          -- exported.

Don Stewart's avatar
Don Stewart committed
84
          -- ** Other types
85 86

          -- Instances of: Eq and Storable
Don Stewart's avatar
Don Stewart committed
87 88
        , CFile,        CFpos,     CJmpBuf
        ) where
89

90
import Foreign.Storable
91
import Data.Bits        ( Bits(..), FiniteBits(..) )
Don Stewart's avatar
Don Stewart committed
92 93
import Data.Int         ( Int8,  Int16,  Int32,  Int64  )
import Data.Word        ( Word8, Word16, Word32, Word64 )
94 95 96 97 98 99 100 101

import GHC.Base
import GHC.Float
import GHC.Enum
import GHC.Real
import GHC.Show
import GHC.Read
import GHC.Num
102

103
#include "HsBaseConfig.h"
104 105
#include "CTypes.h"

ross's avatar
ross committed
106
-- | Haskell type representing the C @char@ type.
107
INTEGRAL_TYPE(CChar,HTYPE_CHAR)
ross's avatar
ross committed
108
-- | Haskell type representing the C @signed char@ type.
109
INTEGRAL_TYPE(CSChar,HTYPE_SIGNED_CHAR)
ross's avatar
ross committed
110
-- | Haskell type representing the C @unsigned char@ type.
111
INTEGRAL_TYPE(CUChar,HTYPE_UNSIGNED_CHAR)
112

ross's avatar
ross committed
113
-- | Haskell type representing the C @short@ type.
114
INTEGRAL_TYPE(CShort,HTYPE_SHORT)
ross's avatar
ross committed
115
-- | Haskell type representing the C @unsigned short@ type.
116
INTEGRAL_TYPE(CUShort,HTYPE_UNSIGNED_SHORT)
117

ross's avatar
ross committed
118
-- | Haskell type representing the C @int@ type.
119
INTEGRAL_TYPE(CInt,HTYPE_INT)
ross's avatar
ross committed
120
-- | Haskell type representing the C @unsigned int@ type.
121
INTEGRAL_TYPE(CUInt,HTYPE_UNSIGNED_INT)
122

ross's avatar
ross committed
123
-- | Haskell type representing the C @long@ type.
124
INTEGRAL_TYPE(CLong,HTYPE_LONG)
ross's avatar
ross committed
125
-- | Haskell type representing the C @unsigned long@ type.
126
INTEGRAL_TYPE(CULong,HTYPE_UNSIGNED_LONG)
127

ross's avatar
ross committed
128
-- | Haskell type representing the C @long long@ type.
129
INTEGRAL_TYPE(CLLong,HTYPE_LONG_LONG)
ross's avatar
ross committed
130
-- | Haskell type representing the C @unsigned long long@ type.
131
INTEGRAL_TYPE(CULLong,HTYPE_UNSIGNED_LONG_LONG)
132

Ryan Scott's avatar
Ryan Scott committed
133 134 135 136 137
-- | Haskell type representing the C @bool@ type.
--
-- @since 4.10.0.0
INTEGRAL_TYPE_WITH_CTYPE(CBool,bool,HTYPE_BOOL)

138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161
{-# RULES
"fromIntegral/a->CChar"   fromIntegral = \x -> CChar   (fromIntegral x)
"fromIntegral/a->CSChar"  fromIntegral = \x -> CSChar  (fromIntegral x)
"fromIntegral/a->CUChar"  fromIntegral = \x -> CUChar  (fromIntegral x)
"fromIntegral/a->CShort"  fromIntegral = \x -> CShort  (fromIntegral x)
"fromIntegral/a->CUShort" fromIntegral = \x -> CUShort (fromIntegral x)
"fromIntegral/a->CInt"    fromIntegral = \x -> CInt    (fromIntegral x)
"fromIntegral/a->CUInt"   fromIntegral = \x -> CUInt   (fromIntegral x)
"fromIntegral/a->CLong"   fromIntegral = \x -> CLong   (fromIntegral x)
"fromIntegral/a->CULong"  fromIntegral = \x -> CULong  (fromIntegral x)
"fromIntegral/a->CLLong"  fromIntegral = \x -> CLLong  (fromIntegral x)
"fromIntegral/a->CULLong" fromIntegral = \x -> CULLong (fromIntegral x)

"fromIntegral/CChar->a"   fromIntegral = \(CChar   x) -> fromIntegral x
"fromIntegral/CSChar->a"  fromIntegral = \(CSChar  x) -> fromIntegral x
"fromIntegral/CUChar->a"  fromIntegral = \(CUChar  x) -> fromIntegral x
"fromIntegral/CShort->a"  fromIntegral = \(CShort  x) -> fromIntegral x
"fromIntegral/CUShort->a" fromIntegral = \(CUShort x) -> fromIntegral x
"fromIntegral/CInt->a"    fromIntegral = \(CInt    x) -> fromIntegral x
"fromIntegral/CUInt->a"   fromIntegral = \(CUInt   x) -> fromIntegral x
"fromIntegral/CLong->a"   fromIntegral = \(CLong   x) -> fromIntegral x
"fromIntegral/CULong->a"  fromIntegral = \(CULong  x) -> fromIntegral x
"fromIntegral/CLLong->a"  fromIntegral = \(CLLong  x) -> fromIntegral x
"fromIntegral/CULLong->a" fromIntegral = \(CULLong x) -> fromIntegral x
Ryan Scott's avatar
Ryan Scott committed
162
"fromIntegral/CBool->a"   fromIntegral = \(CBool   x) -> fromIntegral x
163 164
 #-}

ross's avatar
ross committed
165
-- | Haskell type representing the C @float@ type.
166
FLOATING_TYPE(CFloat,HTYPE_FLOAT)
ross's avatar
ross committed
167
-- | Haskell type representing the C @double@ type.
168
FLOATING_TYPE(CDouble,HTYPE_DOUBLE)
169
-- XXX GHC doesn't support CLDouble yet
170

171 172 173 174 175 176 177 178
{-# RULES
"realToFrac/a->CFloat"    realToFrac = \x -> CFloat   (realToFrac x)
"realToFrac/a->CDouble"   realToFrac = \x -> CDouble  (realToFrac x)

"realToFrac/CFloat->a"    realToFrac = \(CFloat   x) -> realToFrac x
"realToFrac/CDouble->a"   realToFrac = \(CDouble  x) -> realToFrac x
 #-}

179 180 181 182
-- GHC doesn't support CLDouble yet
-- "realToFrac/a->CLDouble"  realToFrac = \x -> CLDouble (realToFrac x)
-- "realToFrac/CLDouble->a"  realToFrac = \(CLDouble x) -> realToFrac x

ross's avatar
ross committed
183
-- | Haskell type representing the C @ptrdiff_t@ type.
184
INTEGRAL_TYPE(CPtrdiff,HTYPE_PTRDIFF_T)
ross's avatar
ross committed
185
-- | Haskell type representing the C @size_t@ type.
186
INTEGRAL_TYPE(CSize,HTYPE_SIZE_T)
ross's avatar
ross committed
187
-- | Haskell type representing the C @wchar_t@ type.
188
INTEGRAL_TYPE(CWchar,HTYPE_WCHAR_T)
ross's avatar
ross committed
189
-- | Haskell type representing the C @sig_atomic_t@ type.
190
INTEGRAL_TYPE(CSigAtomic,HTYPE_SIG_ATOMIC_T)
191 192 193 194 195 196 197 198 199 200 201 202 203

{-# RULES
"fromIntegral/a->CPtrdiff"   fromIntegral = \x -> CPtrdiff   (fromIntegral x)
"fromIntegral/a->CSize"      fromIntegral = \x -> CSize      (fromIntegral x)
"fromIntegral/a->CWchar"     fromIntegral = \x -> CWchar     (fromIntegral x)
"fromIntegral/a->CSigAtomic" fromIntegral = \x -> CSigAtomic (fromIntegral x)

"fromIntegral/CPtrdiff->a"   fromIntegral = \(CPtrdiff   x) -> fromIntegral x
"fromIntegral/CSize->a"      fromIntegral = \(CSize      x) -> fromIntegral x
"fromIntegral/CWchar->a"     fromIntegral = \(CWchar     x) -> fromIntegral x
"fromIntegral/CSigAtomic->a" fromIntegral = \(CSigAtomic x) -> fromIntegral x
 #-}

ross's avatar
ross committed
204
-- | Haskell type representing the C @clock_t@ type.
205
ARITHMETIC_TYPE(CClock,HTYPE_CLOCK_T)
ross's avatar
ross committed
206
-- | Haskell type representing the C @time_t@ type.
207
ARITHMETIC_TYPE(CTime,HTYPE_TIME_T)
208
-- | Haskell type representing the C @useconds_t@ type.
209
--
210
-- @since 4.4.0.0
211

212
ARITHMETIC_TYPE(CUSeconds,HTYPE_USECONDS_T)
213
-- | Haskell type representing the C @suseconds_t@ type.
214
--
215
-- @since 4.4.0.0
216
ARITHMETIC_TYPE(CSUSeconds,HTYPE_SUSECONDS_T)
217 218

-- FIXME: Implement and provide instances for Eq and Storable
ross's avatar
ross committed
219
-- | Haskell type representing the C @FILE@ type.
220
data CFile = CFile
ross's avatar
ross committed
221
-- | Haskell type representing the C @fpos_t@ type.
222
data CFpos = CFpos
ross's avatar
ross committed
223
-- | Haskell type representing the C @jmp_buf@ type.
224 225
data CJmpBuf = CJmpBuf

226 227 228 229
INTEGRAL_TYPE(CIntPtr,HTYPE_INTPTR_T)
INTEGRAL_TYPE(CUIntPtr,HTYPE_UINTPTR_T)
INTEGRAL_TYPE(CIntMax,HTYPE_INTMAX_T)
INTEGRAL_TYPE(CUIntMax,HTYPE_UINTMAX_T)
230 231 232 233 234 235 236 237

{-# RULES
"fromIntegral/a->CIntPtr"  fromIntegral = \x -> CIntPtr  (fromIntegral x)
"fromIntegral/a->CUIntPtr" fromIntegral = \x -> CUIntPtr (fromIntegral x)
"fromIntegral/a->CIntMax"  fromIntegral = \x -> CIntMax  (fromIntegral x)
"fromIntegral/a->CUIntMax" fromIntegral = \x -> CUIntMax (fromIntegral x)
 #-}

238
-- C99 types which are still missing include:
239
-- wint_t, wctrans_t, wctype_t
240

ross's avatar
ross committed
241 242 243 244 245 246 247 248
{- $ctypes

These types are needed to accurately represent C function prototypes,
in order to access C library interfaces in Haskell.  The Haskell system
is not required to represent those types exactly as C does, but the
following guarantees are provided concerning a Haskell type @CT@
representing a C type @t@:

ross's avatar
ross committed
249 250 251 252
* If a C function prototype has @t@ as an argument or result type, the
  use of @CT@ in the corresponding position in a foreign declaration
  permits the Haskell program to access the full range of values encoded
  by the C type; and conversely, any Haskell value for @CT@ has a valid
ross's avatar
ross committed
253 254
  representation in C.

ross's avatar
ross committed
255
* @'sizeOf' ('Prelude.undefined' :: CT)@ will yield the same value as
ross's avatar
ross committed
256 257
  @sizeof (t)@ in C.

ross's avatar
ross committed
258 259
* @'alignment' ('Prelude.undefined' :: CT)@ matches the alignment
  constraint enforced by the C implementation for @t@.
ross's avatar
ross committed
260

ross's avatar
ross committed
261 262
* The members 'peek' and 'poke' of the 'Storable' class map all values
  of @CT@ to the corresponding value of @t@ and vice versa.
ross's avatar
ross committed
263

ross's avatar
ross committed
264 265 266
* When an instance of 'Prelude.Bounded' is defined for @CT@, the values
  of 'Prelude.minBound' and 'Prelude.maxBound' coincide with @t_MIN@
  and @t_MAX@ in C.
ross's avatar
ross committed
267

ross's avatar
ross committed
268 269 270
* When an instance of 'Prelude.Eq' or 'Prelude.Ord' is defined for @CT@,
  the predicates defined by the type class implement the same relation
  as the corresponding predicate in C on @t@.
ross's avatar
ross committed
271

ross's avatar
ross committed
272 273 274 275 276
* When an instance of 'Prelude.Num', 'Prelude.Read', 'Prelude.Integral',
  'Prelude.Fractional', 'Prelude.Floating', 'Prelude.RealFrac', or
  'Prelude.RealFloat' is defined for @CT@, the arithmetic operations
  defined by the type class implement the same function as the
  corresponding arithmetic operations (if available) in C on @t@.
ross's avatar
ross committed
277 278 279 280 281 282 283

* When an instance of 'Bits' is defined for @CT@, the bitwise operation
  defined by the type class implement the same function as the
  corresponding bitwise operation in C on @t@.

-}