9af2f5e6f381fbf723c3836ad66a16dc53c1c6db
[haskell-report.git] / report / libs / Data-Bits.tex
1 \haddockmoduleheading{Data.Bits}
2 \label{module:Data.Bits}
3 \haddockbeginheader
4 {\haddockverb\begin{verbatim}
5 module Data.Bits (
6 Bits((.&.),
7 (.|.),
8 xor,
9 complement,
10 shift,
11 rotate,
12 bit,
13 setBit,
14 clearBit,
15 complementBit,
16 testBit,
17 bitSize,
18 isSigned,
19 shiftL,
20 shiftR,
21 rotateL,
22 rotateR)
23 ) where\end{verbatim}}
24 \haddockendheader
25
26 This module defines bitwise operations for signed and unsigned
27 integers.
28 \par
29
30 \begin{haddockdesc}
31 \item[\begin{tabular}{@{}l}
32 class\ Num\ a\ =>\ Bits\ a\ where
33 \end{tabular}]\haddockbegindoc
34 The \haddockid{Bits} class defines bitwise operations over integral types.
35 \par
36 \begin{itemize}
37 \item
38 Bits are numbered from 0 with bit 0 being the least
39 significant bit.
40 \par
41
42 \end{itemize}
43 Minimal complete definition: \haddockid{.{\char '46}.}, \haddockid{.|.}, \haddockid{xor}, \haddockid{complement},
44 (\haddockid{shift} or (\haddockid{shiftL} and \haddockid{shiftR})), (\haddockid{rotate} or (\haddockid{rotateL} and \haddockid{rotateR})),
45 \haddockid{bitSize} and \haddockid{isSigned}.
46 \par
47
48 \haddockpremethods{}\textbf{Methods}
49 \begin{haddockdesc}
50 \item[\begin{tabular}{@{}l}
51 (.{\char '46}.)\ ::\ a\ ->\ a\ ->\ a
52 \end{tabular}]\haddockbegindoc
53 Bitwise "and"
54 \par
55
56 \end{haddockdesc}
57 \begin{haddockdesc}
58 \item[\begin{tabular}{@{}l}
59 (.|.)\ ::\ a\ ->\ a\ ->\ a
60 \end{tabular}]\haddockbegindoc
61 Bitwise "or"
62 \par
63
64 \end{haddockdesc}
65 \begin{haddockdesc}
66 \item[\begin{tabular}{@{}l}
67 xor\ ::\ a\ ->\ a\ ->\ a
68 \end{tabular}]\haddockbegindoc
69 Bitwise "xor"
70 \par
71
72 \end{haddockdesc}
73 \begin{haddockdesc}
74 \item[\begin{tabular}{@{}l}
75 complement\ ::\ a\ ->\ a
76 \end{tabular}]\haddockbegindoc
77 Reverse all the bits in the argument
78 \par
79
80 \end{haddockdesc}
81 \begin{haddockdesc}
82 \item[\begin{tabular}{@{}l}
83 shift\ ::\ a\ ->\ Int\ ->\ a
84 \end{tabular}]\haddockbegindoc
85 \haddocktt{shift\ x\ i} shifts \haddocktt{x} left by \haddocktt{i} bits if \haddocktt{i} is positive,
86 or right by \haddocktt{-i} bits otherwise.
87 Right shifts perform sign extension on signed number types;
88 i.e. they fill the top bits with 1 if the \haddocktt{x} is negative
89 and with 0 otherwise.
90 \par
91 An instance can define either this unified \haddockid{shift} or \haddockid{shiftL} and
92 \haddockid{shiftR}, depending on which is more convenient for the type in
93 question.
94 \par
95
96 \end{haddockdesc}
97 \begin{haddockdesc}
98 \item[\begin{tabular}{@{}l}
99 rotate\ ::\ a\ ->\ Int\ ->\ a
100 \end{tabular}]\haddockbegindoc
101 \haddocktt{rotate\ x\ i} rotates \haddocktt{x} left by \haddocktt{i} bits if \haddocktt{i} is positive,
102 or right by \haddocktt{-i} bits otherwise.
103 \par
104 For unbounded types like \haddockid{Integer}, \haddockid{rotate} is equivalent to \haddockid{shift}.
105 \par
106 An instance can define either this unified \haddockid{rotate} or \haddockid{rotateL} and
107 \haddockid{rotateR}, depending on which is more convenient for the type in
108 question.
109 \par
110
111 \end{haddockdesc}
112 \begin{haddockdesc}
113 \item[\begin{tabular}{@{}l}
114 bit\ ::\ Int\ ->\ a
115 \end{tabular}]\haddockbegindoc
116 \haddocktt{bit\ i} is a value with the \haddocktt{i}th bit set
117 \par
118
119 \end{haddockdesc}
120 \begin{haddockdesc}
121 \item[\begin{tabular}{@{}l}
122 setBit\ ::\ a\ ->\ Int\ ->\ a
123 \end{tabular}]\haddockbegindoc
124 \haddocktt{x\ `setBit`\ i} is the same as \haddocktt{x\ .|.\ bit\ i}
125 \par
126
127 \end{haddockdesc}
128 \begin{haddockdesc}
129 \item[\begin{tabular}{@{}l}
130 clearBit\ ::\ a\ ->\ Int\ ->\ a
131 \end{tabular}]\haddockbegindoc
132 \haddocktt{x\ `clearBit`\ i} is the same as \haddocktt{x\ .{\char '46}.\ complement\ (bit\ i)}
133 \par
134
135 \end{haddockdesc}
136 \begin{haddockdesc}
137 \item[\begin{tabular}{@{}l}
138 complementBit\ ::\ a\ ->\ Int\ ->\ a
139 \end{tabular}]\haddockbegindoc
140 \haddocktt{x\ `complementBit`\ i} is the same as \haddocktt{x\ `xor`\ bit\ i}
141 \par
142
143 \end{haddockdesc}
144 \begin{haddockdesc}
145 \item[\begin{tabular}{@{}l}
146 testBit\ ::\ a\ ->\ Int\ ->\ Bool
147 \end{tabular}]\haddockbegindoc
148 Return \haddockid{True} if the \haddocktt{n}th bit of the argument is 1
149 \par
150
151 \end{haddockdesc}
152 \begin{haddockdesc}
153 \item[\begin{tabular}{@{}l}
154 bitSize\ ::\ a\ ->\ Int
155 \end{tabular}]\haddockbegindoc
156 Return the number of bits in the type of the argument. The actual
157 value of the argument is ignored. The function \haddockid{bitSize} is
158 undefined for types that do not have a fixed bitsize, like \haddockid{Integer}.
159 \par
160
161 \end{haddockdesc}
162 \begin{haddockdesc}
163 \item[\begin{tabular}{@{}l}
164 isSigned\ ::\ a\ ->\ Bool
165 \end{tabular}]\haddockbegindoc
166 Return \haddockid{True} if the argument is a signed type. The actual
167 value of the argument is ignored
168 \par
169
170 \end{haddockdesc}
171 \begin{haddockdesc}
172 \item[\begin{tabular}{@{}l}
173 shiftL\ ::\ a\ ->\ Int\ ->\ a
174 \end{tabular}]\haddockbegindoc
175 Shift the argument left by the specified number of bits
176 (which must be non-negative).
177 \par
178 An instance can define either this and \haddockid{shiftR} or the unified
179 \haddockid{shift}, depending on which is more convenient for the type in
180 question.
181 \par
182
183 \end{haddockdesc}
184 \begin{haddockdesc}
185 \item[\begin{tabular}{@{}l}
186 shiftR\ ::\ a\ ->\ Int\ ->\ a
187 \end{tabular}]\haddockbegindoc
188 Shift the first argument right by the specified number of bits
189 (which must be non-negative).
190 Right shifts perform sign extension on signed number types;
191 i.e. they fill the top bits with 1 if the \haddocktt{x} is negative
192 and with 0 otherwise.
193 \par
194 An instance can define either this and \haddockid{shiftL} or the unified
195 \haddockid{shift}, depending on which is more convenient for the type in
196 question.
197 \par
198
199 \end{haddockdesc}
200 \begin{haddockdesc}
201 \item[\begin{tabular}{@{}l}
202 rotateL\ ::\ a\ ->\ Int\ ->\ a
203 \end{tabular}]\haddockbegindoc
204 Rotate the argument left by the specified number of bits
205 (which must be non-negative).
206 \par
207 An instance can define either this and \haddockid{rotateR} or the unified
208 \haddockid{rotate}, depending on which is more convenient for the type in
209 question.
210 \par
211
212 \end{haddockdesc}
213 \begin{haddockdesc}
214 \item[\begin{tabular}{@{}l}
215 rotateR\ ::\ a\ ->\ Int\ ->\ a
216 \end{tabular}]\haddockbegindoc
217 Rotate the argument right by the specified number of bits
218 (which must be non-negative).
219 \par
220 An instance can define either this and \haddockid{rotateL} or the unified
221 \haddockid{rotate}, depending on which is more convenient for the type in
222 question.
223 \par
224
225 \end{haddockdesc}
226 \end{haddockdesc}
227 \begin{haddockdesc}
228 \item[\begin{tabular}{@{}l}
229 instance\ Bits\ Int\\instance\ Bits\ Int8\\instance\ Bits\ Int16\\instance\ Bits\ Int32\\instance\ Bits\ Int64\\instance\ Bits\ Integer\\instance\ Bits\ Word\\instance\ Bits\ Word8\\instance\ Bits\ Word16\\instance\ Bits\ Word32\\instance\ Bits\ Word64\\instance\ Bits\ WordPtr\\instance\ Bits\ IntPtr\\instance\ Bits\ CChar\\instance\ Bits\ CSChar\\instance\ Bits\ CUChar\\instance\ Bits\ CShort\\instance\ Bits\ CUShort\\instance\ Bits\ CInt\\instance\ Bits\ CUInt\\instance\ Bits\ CLong\\instance\ Bits\ CULong\\instance\ Bits\ CLLong\\instance\ Bits\ CULLong\\instance\ Bits\ CPtrdiff\\instance\ Bits\ CSize\\instance\ Bits\ CWchar\\instance\ Bits\ CSigAtomic\\instance\ Bits\ CIntPtr\\instance\ Bits\ CUIntPtr\\instance\ Bits\ CIntMax\\instance\ Bits\ CUIntMax
230 \end{tabular}]
231 \end{haddockdesc}