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