@@ -3,38 +3,54 @@ module Bits where
33
44{-| Library for [bitwise operations](http://en.wikipedia.org/wiki/Bitwise_operation).
55
6−@docs and, or, xor, complement, shiftLeft, shiftRight, shiftRightLogical
6+# Basic Operations
7+
8+@docs and, or, xor, complement
9+
10+# Bit Shifts
11+
12+@docs shiftLeft, shiftRight, shiftRightLogical
713-}
814
915import Native.Bits
1016
11−{-| Performs the AND operation on each pair of bits.
17+{-| Bitwise “and”
1218-}
1319and : Int -> Int -> Int
1420and = Native.Bits.and
1521
16−{-| Performs the OR operation on each pair of bits.
22+{-| Bitwise “or”
1723-}
1824or : Int -> Int -> Int
1925or = Native.Bits.or
2026
21−{-| Performs the XOR operation on each pair of bits.
27+{-| Bitwise “xor”
2228-}
2329xor : Int -> Int -> Int
2430xor = Native.Bits.xor
2531
26−{-| Performs the NOT operation on each bit.
32+{-| Flip each bit individually, often called “bitwise not”
2733-}
2834complement : Int -> Int
2935complement = Native.Bits.complement
3036
3137{-| Shift bits to the left by a given offset, filling new bits with zeros.
38+This can be used to multiply numbers by powers of two.
39+
40+ 8 `shiftLeft` 1 == 16
41+ 8 `shiftLeft` 2 == 32
3242-}
3343shiftLeft : Int -> Int -> Int
3444shiftLeft = Native.Bits.shiftLeft
3545
3646{-| Shift bits to the right by a given offset, filling new bits with
37−whatever is the topmost bit. This is an [arithmatic right
47+whatever is the topmost bit. This can be used to divide numbers by powers of two.
48+
49+ 32 `shiftRight` 1 == 16
50+ 32 `shiftRight` 2 == 8
51+ -32 `shiftRight` 1 == -16
52+
53+This is called an [arithmatic right
3854shift](http://en.wikipedia.org/wiki/Bitwise_operation#Arithmetic_shift),
3955often written (>>), and sometimes called a “sign-propagating”
4056right shift because it fills empty spots with copies of the highest bit.
@@ -43,7 +59,13 @@ shiftRight : Int -> Int -> Int
4359shiftRight = Native.Bits.shiftRightArithmatic
4460
4561{-| Shift bits to the right by a given offset, filling new bits with
46−zeros. This is an [logical right
62+zeros.
63+
64+ 32 `shiftRightLogical` 1 == 16
65+ 32 `shiftRightLogical` 2 == 8
66+ -32 `shiftRightLogical` 1 == 2147483632
67+
68+This is called an [logical right
4769shift](http://en.wikipedia.org/wiki/Bitwise_operation#Logical_shift), often written (>>>),
4870and sometimes called a “zero-fill” right shift because it fills empty spots
4971with zeros.