ghc/docs/libraries/Word.sgml

   1 <sect> <idx/Word/
   2 <label id="sec:Word">
   3 <p>
   4
   5 This library provides unsigned integers of various sizes.
   6 The types supported are as follows:
   7
   8 <tabular ca="ll">
   9 <!-- ToDo: figure out why the ldoc DTD doesn't allow hline's - it looks as if -->
  10 <!-- it should. -->
  11 <!-- <hline> -->
  12 type     | number of bits @
  13 Word8    | 8  @
  14 Word16   | 16 @
  15 Word32   | 32 @
  16 Word64   | 64 @
  17 <!-- <hline> -->
  18 </tabular>
  19
  20
  21 For each type <it/W/ above, we provide the following functions and
  22 instances.  The type <it/I/ refers to the signed integer type of the
  23 same size.
  24
  25 <tscreen><verb>
  26 data W            -- Unsigned Ints
  27 instance Eq       W
  28 instance Ord      W
  29 instance Show     W
  30 instance Read     W
  31 instance Bounded  W
  32 instance Num      W
  33 instance Real     W
  34 instance Integral W
  35 instance Enum     W
  36 instance Ix       W
  37 instance Bits     W
  38 </verb></tscreen>
  39 Plus
  40 <tscreen><verb>
  41 word8ToWord16  :: Word8   -> Word16
  42 word8ToWord32  :: Word8   -> Word32
  43 word8ToWord64  :: Word8   -> Word64
  44
  45 word16ToWord8   :: Word16  -> Word8
  46 word16ToWord32  :: Word16  -> Word32
  47 word16ToWord64  :: Word16  -> Word64
  48
  49 word32ToWord8  :: Word32 -> Word8
  50 word32ToWord16 :: Word32 -> Word16
  51 word32ToWord64 :: Word32 -> Word64
  52
  53 word64ToWord8  :: Word64 -> Word8
  54 word64ToWord16 :: Word64 -> Word16
  55 word64ToWord32 :: Word64 -> Word32
  56
  57 word8ToInt     :: Word8  -> Int
  58 word16ToInt    :: Word16 -> Int
  59 word32ToInt    :: Word32 -> Int
  60 word64ToInt    :: Word64 -> Int
  61
  62 intToWord8     :: Int    -> Word8
  63 intToWord16    :: Int    -> Word16
  64 intToWord32    :: Int    -> Word32
  65 intToWord64    :: Int    -> Word64
  66
  67 word64ToInteger :: Word64  -> Integer
  68 integerToWord64 :: Integer -> Word64
  69
  70 </verb></tscreen>
  71
  72 Notes:
  73 <itemize>
  74 <item>
  75   All arithmetic is performed modulo 2^n
  76
  77   One non-obvious consequence of this is that <tt/negate/
  78   should <em/not/ raise an error on negative arguments.
  79
  80 <item>
  81 The coercion <tt/wToI/ converts an unsigned n-bit value to the
  82 signed n-bit value with the same representation.  For example,
  83 <tt/word8ToInt8 0xff = -1/.
  84 Likewise, <tt/iToW/ converts signed n-bit values to the
  85 corresponding unsigned n-bit value.
  86
  87 <item>
  88 Use <tt/Prelude.fromIntegral :: (Integral a, Num b) => a -> b/ to
  89 coerce between different sizes or to preserve sign when converting
  90 between values of the same size.
  91
  92 <item>
  93 It would be very natural to add a type a type <tt/Natural/ providing
  94 an unbounded size unsigned integer --- just as <tt/Integer/ provides
  95 unbounded size signed integers.  We do not do that yet since there is
  96 no demand for it.  Doing so would require <tt/Bits.bitSize/ to return
  97 <tt/Maybe Int/.
  98
  99 <item>
 100 The rules that hold for <tt/Enum/ instances over a bounded type
 101 such as <tt/Int/ (see the section of the Haskell report dealing
 102 with arithmetic sequences) also hold for the <tt/Enum/ instances
 103 over the various <tt/Word/ types defined here.
 104
 105 <item>
 106 Right and left shifts by amounts greater than or equal to the width of
 107 the type result in a zero result.  This is contrary to the behaviour
 108 in C, which is undefined; a common interpretation is to truncate
 109 the shift count to the width of the type, for example <tt>1 &lt;&lt;
 110 32 == 1</tt> in some C implementations.
 111
 112 </itemize>
 113
 114 <bf/Implementation notes:/
 115
 116 <itemize>
 117 <item> Hugs only provides <tt/Eq/, <tt/Ord/, <tt/Read/ and <tt/Show/
 118 instances for <tt/Word64/ at the moment.
 119 </itemize>