Clarify the wording of the 'insert' haddock; fixes #7421
[packages/base.git] / Data / Word.hs
1 {-# LANGUAGE Safe #-}
2 {-# LANGUAGE CPP, NoImplicitPrelude #-}
3
4 -----------------------------------------------------------------------------
5 -- |
6 -- Module : Data.Word
7 -- Copyright : (c) The University of Glasgow 2001
8 -- License : BSD-style (see the file libraries/base/LICENSE)
9 --
10 -- Maintainer : libraries@haskell.org
11 -- Stability : experimental
12 -- Portability : portable
13 --
14 -- Unsigned integer types.
15 --
16 -----------------------------------------------------------------------------
17
18 module Data.Word
19 (
20 -- * Unsigned integral types
21
22 Word,
23 Word8, Word16, Word32, Word64,
24
25 -- * Notes
26
27 -- $notes
28 ) where
29
30 #ifdef __GLASGOW_HASKELL__
31 import GHC.Word
32 #endif
33
34 #ifdef __HUGS__
35 import Hugs.Word
36 #endif
37
38 #ifdef __NHC__
39 import NHC.FFI (Word8, Word16, Word32, Word64)
40 import NHC.SizedTypes (Word8, Word16, Word32, Word64) -- instances of Bits
41 type Word = Word32
42 #endif
43
44 {- $notes
45
46 * All arithmetic is performed modulo 2^n, where n is the number of
47 bits in the type. One non-obvious consequence of this is that 'Prelude.negate'
48 should /not/ raise an error on negative arguments.
49
50 * For coercing between any two integer types, use
51 'Prelude.fromIntegral', which is specialized for all the
52 common cases so should be fast enough. Coercing word types to and
53 from integer types preserves representation, not sign.
54
55 * It would be very natural to add a type @Natural@ providing an unbounded
56 size unsigned integer, just as 'Prelude.Integer' provides unbounded
57 size signed integers. We do not do that yet since there is no demand
58 for it.
59
60 * The rules that hold for 'Prelude.Enum' instances over a bounded type
61 such as 'Prelude.Int' (see the section of the Haskell report dealing
62 with arithmetic sequences) also hold for the 'Prelude.Enum' instances
63 over the various 'Word' types defined here.
64
65 * Right and left shifts by amounts greater than or equal to the width
66 of the type result in a zero result. This is contrary to the
67 behaviour in C, which is undefined; a common interpretation is to
68 truncate the shift count to the width of the type, for example @1 \<\<
69 32 == 1@ in some C implementations.
70 -}
71