Add explicit `{-# LANGUAGE CPP, PackageImports #-}` pragmas
[packages/haskell2010.git] / Foreign / C / String.hs
1 {-# LANGUAGE CPP, PackageImports #-}
2 #if __GLASGOW_HASKELL__ >= 701
3 {-# LANGUAGE Safe #-}
4 #endif
5
6 -- |
7 -- Utilities for primitive marshalling of C strings.
8 --
9 -- The marshalling converts each Haskell character, representing a Unicode
10 -- code point, to one or more bytes in a manner that, by default, is
11 -- determined by the current locale. As a consequence, no guarantees
12 -- can be made about the relative length of a Haskell string and its
13 -- corresponding C string, and therefore all the marshalling routines
14 -- include memory allocation. The translation between Unicode and the
15 -- encoding of the current locale may be lossy.
16
17 module Foreign.C.String (
18
19 -- * C strings
20
21 CString, -- = Ptr CChar
22 CStringLen, -- = (Ptr CChar, Int)
23
24 -- ** Using a locale-dependent encoding
25
26 -- | Currently these functions are identical to their @CAString@ counterparts;
27 -- eventually they will use an encoding determined by the current locale.
28
29 -- conversion of C strings into Haskell strings
30 --
31 peekCString, -- :: CString -> IO String
32 peekCStringLen, -- :: CStringLen -> IO String
33
34 -- conversion of Haskell strings into C strings
35 --
36 newCString, -- :: String -> IO CString
37 newCStringLen, -- :: String -> IO CStringLen
38
39 -- conversion of Haskell strings into C strings using temporary storage
40 --
41 withCString, -- :: String -> (CString -> IO a) -> IO a
42 withCStringLen, -- :: String -> (CStringLen -> IO a) -> IO a
43
44 charIsRepresentable, -- :: Char -> IO Bool
45
46 -- ** Using 8-bit characters
47
48 -- | These variants of the above functions are for use with C libraries
49 -- that are ignorant of Unicode. These functions should be used with
50 -- care, as a loss of information can occur.
51
52 castCharToCChar, -- :: Char -> CChar
53 castCCharToChar, -- :: CChar -> Char
54
55 castCharToCUChar, -- :: Char -> CUChar
56 castCUCharToChar, -- :: CUChar -> Char
57 castCharToCSChar, -- :: Char -> CSChar
58 castCSCharToChar, -- :: CSChar -> Char
59
60 peekCAString, -- :: CString -> IO String
61 peekCAStringLen, -- :: CStringLen -> IO String
62 newCAString, -- :: String -> IO CString
63 newCAStringLen, -- :: String -> IO CStringLen
64 withCAString, -- :: String -> (CString -> IO a) -> IO a
65 withCAStringLen, -- :: String -> (CStringLen -> IO a) -> IO a
66
67 -- * C wide strings
68
69 -- | These variants of the above functions are for use with C libraries
70 -- that encode Unicode using the C @wchar_t@ type in a system-dependent
71 -- way. The only encodings supported are
72 --
73 -- * UTF-32 (the C compiler defines @__STDC_ISO_10646__@), or
74 --
75 -- * UTF-16 (as used on Windows systems).
76
77 CWString, -- = Ptr CWchar
78 CWStringLen, -- = (Ptr CWchar, Int)
79
80 peekCWString, -- :: CWString -> IO String
81 peekCWStringLen, -- :: CWStringLen -> IO String
82 newCWString, -- :: String -> IO CWString
83 newCWStringLen, -- :: String -> IO CWStringLen
84 withCWString, -- :: String -> (CWString -> IO a) -> IO a
85 withCWStringLen, -- :: String -> (CWStringLen -> IO a) -> IO a
86
87 ) where
88 import "base" Foreign.C.String