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 type    | number of bits @
  10 <!-- <hline>  -->
  11 Word8    | 8  @
  12 Word16   | 16 @
  13 Word32   | 32 @
  14 Word64   | 64 @
  15 <!-- <hline>  -->
  16 </tabular>
  17
  18 For each type <it/W/ above, we provide the following functions and
  19 instances.  The type <it/I/ refers to the signed integer type of the
  20 same size.
  21
  22 <tscreen><verb>
  23 data W            -- Unsigned Ints
  24 instance Eq       W
  25 instance Ord      W
  26 instance Show     W
  27 instance Read     W
  28 instance Bounded  W
  29 instance Num      W
  30 instance Real     W
  31 instance Integral W
  32 instance Enum     W
  33 instance Ix       W
  34 instance Bits     W
  35 </verb></tscreen>
  36 Plus
  37 <tscreen><verb>
  38 word8ToWord32  :: Word8  -> Word32
  39 word32ToWord8  :: Word32 -> Word8
  40 word16ToWord32 :: Word16 -> Word32
  41 word32ToWord16 :: Word32 -> Word16
  42
  43 word8ToInt     :: Word8  -> Int
  44 intToWord8     :: Int    -> Word8
  45 word16ToInt    :: Word16 -> Int
  46 intToWord16    :: Int    -> Word16
  47 word32ToInt    :: Word32 -> Int
  48 intToWord32    :: Int    -> Word32
  49 </verb></tscreen>
  50
  51 Notes:
  52 <itemize>
  53 <item>
  54   All arithmetic is performed modulo 2^n
  55
  56   One non-obvious consequequence of this is that <tt/negate/
  57   should <em/not/ raise an error on negative arguments.
  58
  59 <item>
  60 The coercion <tt/wToI/ converts an unsigned n-bit value to the
  61 signed n-bit value with the same representation.  For example,
  62 <tt/word8ToInt8 0xff = -1/.
  63 Likewise, <tt/iToW/ converts signed n-bit values to the
  64 corresponding unsigned n-bit value.
  65
  66 <item>
  67 ToDo: complete the set of coercion functions.
  68
  69 <item>
  70 Use <tt/Prelude.fromIntegral :: (Integral a, Num b) => a -> b/ to
  71 coerce between different sizes or to preserve sign when converting
  72 between values of the same size.
  73
  74 <item>
  75 It would be very natural to add a type a type <tt/Natural/ providing
  76 an unbounded size unsigned integer --- just as <tt/Integer/ provides
  77 unbounded size signed integers.  We do not do that yet since there is
  78 no demand for it.  Doing so would require <tt/Bits.bitSize/ to return
  79 <tt/Maybe Int/.
  80
  81 <item>
  82 The <tt/Enum/ instances stop when they reach their upper or lower
  83 bound --- they don't overflow the way the <tt/Int/ and <tt/Float/
  84 instances do.
  85
  86 <item>
  87 It would be useful to provide a function (or a family of functions?)
  88 which coerced between any two Word types (without going through
  89 Integer).
  90
  91 </itemize>
  92
  93 Hugs only provides <tt/Eq/, <tt/Ord/, <tt/Read/ and <tt/Show/
  94 instances for <tt/Word64/ at the moment.
  95