remove instances for types/classes that are not part of Haskell
[haskell-report.git] / report / libs / Foreign-Storable.tex
1 \haddockmoduleheading{Foreign.Storable}
2 \label{module:Foreign.Storable}
3 \haddockbeginheader
4 {\haddockverb\begin{verbatim}
5 module Foreign.Storable (
6 Storable(sizeOf,
7 alignment,
8 peekElemOff,
9 pokeElemOff,
10 peekByteOff,
11 pokeByteOff,
12 peek,
13 poke)
14 ) where\end{verbatim}}
15 \haddockendheader
16
17 \begin{haddockdesc}
18 \item[\begin{tabular}{@{}l}
19 class\ Storable\ a\ where
20 \end{tabular}]\haddockbegindoc
21 The member functions of this class facilitate writing values of
22 primitive types to raw memory (which may have been allocated with the
23 above mentioned routines) and reading values from blocks of raw
24 memory. The class, furthermore, includes support for computing the
25 storage requirements and alignment restrictions of storable types.
26 \par
27 Memory addresses are represented as values of type \haddocktt{Ptr\ a}, for some
28 \haddocktt{a} which is an instance of class \haddockid{Storable}. The type argument to
29 \haddockid{Ptr} helps provide some valuable type safety in FFI code (you can't
30 mix pointers of different types without an explicit cast), while
31 helping the Haskell type system figure out which marshalling method is
32 needed for a given pointer.
33 \par
34 All marshalling between Haskell and a foreign language ultimately
35 boils down to translating Haskell data structures into the binary
36 representation of a corresponding data structure of the foreign
37 language and vice versa. To code this marshalling in Haskell, it is
38 necessary to manipulate primitive data types stored in unstructured
39 memory blocks. The class \haddockid{Storable} facilitates this manipulation on
40 all types for which it is instantiated, which are the standard basic
41 types of Haskell, the fixed size \haddocktt{Int} types (\haddockid{Int8}, \haddockid{Int16},
42 \haddockid{Int32}, \haddockid{Int64}), the fixed size \haddocktt{Word} types (\haddockid{Word8}, \haddockid{Word16},
43 \haddockid{Word32}, \haddockid{Word64}), \haddockid{StablePtr}, all types from \haddocktt{Foreign.C.Types},
44 as well as \haddockid{Ptr}.
45 \par
46 Minimal complete definition: \haddockid{sizeOf}, \haddockid{alignment}, one of \haddockid{peek},
47 \haddockid{peekElemOff} and \haddockid{peekByteOff}, and one of \haddockid{poke}, \haddockid{pokeElemOff} and
48 \haddockid{pokeByteOff}.
49 \par
50
51 \haddockpremethods{}\textbf{Methods}
52 \begin{haddockdesc}
53 \item[\begin{tabular}{@{}l}
54 sizeOf\ ::\ a\ ->\ Int
55 \end{tabular}]\haddockbegindoc
56 Computes the storage requirements (in bytes) of the argument.
57 The value of the argument is not used.
58 \par
59
60 \end{haddockdesc}
61 \begin{haddockdesc}
62 \item[\begin{tabular}{@{}l}
63 alignment\ ::\ a\ ->\ Int
64 \end{tabular}]\haddockbegindoc
65 Computes the alignment constraint of the argument. An
66 alignment constraint \haddocktt{x} is fulfilled by any address divisible
67 by \haddocktt{x}. The value of the argument is not used.
68 \par
69
70 \end{haddockdesc}
71 \begin{haddockdesc}
72 \item[\begin{tabular}{@{}l}
73 peekElemOff\ ::\ Ptr\ a\ ->\ Int\ ->\ IO\ a
74 \end{tabular}]\haddockbegindoc
75 Read a value from a memory area regarded as an array
76 of values of the same kind. The first argument specifies
77 the start address of the array and the second the index into
78 the array (the first element of the array has index
79 \haddocktt{0}). The following equality holds,
80 \par
81 \begin{quote}
82 {\haddockverb\begin{verbatim}
83 peekElemOff addr idx = IOExts.fixIO $ \result ->
84 peek (addr `plusPtr` (idx * sizeOf result))
85 \end{verbatim}}
86 \end{quote}
87 Note that this is only a specification, not
88 necessarily the concrete implementation of the
89 function.
90 \par
91
92 \end{haddockdesc}
93 \begin{haddockdesc}
94 \item[\begin{tabular}{@{}l}
95 pokeElemOff\ ::\ Ptr\ a\ ->\ Int\ ->\ a\ ->\ IO\ ()
96 \end{tabular}]\haddockbegindoc
97 Write a value to a memory area regarded as an array of
98 values of the same kind. The following equality holds:
99 \par
100 \begin{quote}
101 {\haddockverb\begin{verbatim}
102 pokeElemOff addr idx x =
103 poke (addr `plusPtr` (idx * sizeOf x)) x
104 \end{verbatim}}
105 \end{quote}
106
107 \end{haddockdesc}
108 \begin{haddockdesc}
109 \item[\begin{tabular}{@{}l}
110 peekByteOff\ ::\ Ptr\ b\ ->\ Int\ ->\ IO\ a
111 \end{tabular}]\haddockbegindoc
112 Read a value from a memory location given by a base
113 address and offset. The following equality holds:
114 \par
115 \begin{quote}
116 {\haddockverb\begin{verbatim}
117 peekByteOff addr off = peek (addr `plusPtr` off)
118 \end{verbatim}}
119 \end{quote}
120
121 \end{haddockdesc}
122 \begin{haddockdesc}
123 \item[\begin{tabular}{@{}l}
124 pokeByteOff\ ::\ Ptr\ b\ ->\ Int\ ->\ a\ ->\ IO\ ()
125 \end{tabular}]\haddockbegindoc
126 Write a value to a memory location given by a base
127 address and offset. The following equality holds:
128 \par
129 \begin{quote}
130 {\haddockverb\begin{verbatim}
131 pokeByteOff addr off x = poke (addr `plusPtr` off) x
132 \end{verbatim}}
133 \end{quote}
134
135 \end{haddockdesc}
136 \begin{haddockdesc}
137 \item[\begin{tabular}{@{}l}
138 peek\ ::\ Ptr\ a\ ->\ IO\ a
139 \end{tabular}]\haddockbegindoc
140 Read a value from the given memory location.
141 \par
142 Note that the peek and poke functions might require properly
143 aligned addresses to function correctly. This is architecture
144 dependent; thus, portable code should ensure that when peeking or
145 poking values of some type \haddocktt{a}, the alignment
146 constraint for \haddocktt{a}, as given by the function
147 \haddockid{alignment} is fulfilled.
148 \par
149
150 \end{haddockdesc}
151 \begin{haddockdesc}
152 \item[\begin{tabular}{@{}l}
153 poke\ ::\ Ptr\ a\ ->\ a\ ->\ IO\ ()
154 \end{tabular}]\haddockbegindoc
155 Write the given value to the given memory location. Alignment
156 restrictions might apply; see \haddockid{peek}.
157 \par
158
159 \end{haddockdesc}
160 \end{haddockdesc}
161 \begin{haddockdesc}
162 \item[\begin{tabular}{@{}l}
163 instance\ Storable\ Bool\\instance\ Storable\ Char\\instance\ Storable\ Double\\instance\ Storable\ Float\\instance\ Storable\ Int\\instance\ Storable\ Int8\\instance\ Storable\ Int16\\instance\ Storable\ Int32\\instance\ Storable\ Int64\\instance\ Storable\ Word\\instance\ Storable\ Word8\\instance\ Storable\ Word16\\instance\ Storable\ Word32\\instance\ Storable\ Word64\\instance\ Storable\ CChar\\instance\ Storable\ CSChar\\instance\ Storable\ CUChar\\instance\ Storable\ CShort\\instance\ Storable\ CUShort\\instance\ Storable\ CInt\\instance\ Storable\ CUInt\\instance\ Storable\ CLong\\instance\ Storable\ CULong\\instance\ Storable\ CLLong\\instance\ Storable\ CULLong\\instance\ Storable\ CFloat\\instance\ Storable\ CDouble\\instance\ Storable\ CPtrdiff\\instance\ Storable\ CSize\\instance\ Storable\ CWchar\\instance\ Storable\ CSigAtomic\\instance\ Storable\ CClock\\instance\ Storable\ CTime\\instance\ Storable\ CIntPtr\\instance\ Storable\ CUIntPtr\\instance\ Storable\ CIntMax\\instance\ Storable\ CUIntMax\\instance\ Storable\ (StablePtr\ a)\\instance\ Storable\ (Ptr\ a)\\instance\ Storable\ (FunPtr\ a)
164 \end{tabular}]
165 \end{haddockdesc}