Data/Ix.hs

   1 -----------------------------------------------------------------------------
   2 -- |
   3 -- Module      :  Data.Ix
   4 -- Copyright   :  (c) The University of Glasgow 2001
   5 -- License     :  BSD-style (see the file libraries/base/LICENSE)
   6 --
   7 -- Maintainer  :  libraries@haskell.org
   8 -- Stability   :  provisional
   9 -- Portability :  portable
  10 --
  11 -- Class of index types.
  12 --
  13 -- The 'Ix' class is used to map a continuous subrange of values in a type onto
  14 -- integers. It is used primarily for array indexing (see Section 6
  15 -- <http://www.haskell.org/onlinelibrary/array.html#arrays>). The 'Ix'
  16 -- class contains the methods range, index, and inRange. The 'index' operation
  17 -- maps a bounding pair, which defines the lower and upper bounds of the range,
  18 -- and a subscript, to an integer. The 'range' operation enumerates all
  19 -- subscripts; the 'inRange' operation tells whether a particular subscript
  20 -- lies in the range defined by a bounding pair.
  21 --
  22 -- An implementation is entitled to assume the following laws about these
  23 -- operations:
  24 --
  25 -- >        range (l,u) !! index (l,u) i == i   -- when i is in range
  26 --
  27 -- >        inRange (l,u) i == i `elem` range (l,u)
  28 --
  29 -----------------------------------------------------------------------------
  30 module Data.Ix
  31     (
  32         Ix
  33           ( range       -- :: (Ix a) => (a,a) -> [a]
  34           , index       -- :: (Ix a) => (a,a) -> a   -> Int
  35           , inRange     -- :: (Ix a) => (a,a) -> a   -> Bool
  36           , rangeSize   -- :: (Ix a) => (a,a) -> Int
  37           )
  38     -- Ix instances:
  39     --
  40     --  Ix Char
  41     --  Ix Int
  42     --  Ix Integer
  43     --  Ix Bool
  44     --  Ix Ordering
  45     --  Ix ()
  46     --  (Ix a, Ix b) => Ix (a, b)
  47     --  ...
  48
  49     -- Implementation checked wrt. Haskell 98 lib report, 1/99.
  50
  51     -- * Deriving Instances of Ix
  52     -- | Derived instance declarations for the class 'Ix' are only possible
  53     -- for enumerations (i.e. datatypes having only nullary constructors)
  54     -- and single-constructor datatypes, including arbitrarily large tuples,
  55     -- whose constituent types are instances of 'Ix'.
  56     --
  57     -- * For an enumeration, the nullary constructors are assumed to be
  58     -- numbered left-to-right with the indices being 0 to n-1 inclusive. This
  59     -- is the same numbering defined by the 'Enum' class. For example, given
  60     -- the datatype:
  61     --
  62     -- >        data Colour = Red | Orange | Yellow | Green | Blue | Indigo | Violet
  63     --
  64     -- we would have:
  65     --
  66     -- >        range   (Yellow,Blue)        ==  [Yellow,Green,Blue]
  67     -- >        index   (Yellow,Blue) Green  ==  1
  68     -- >        inRange (Yellow,Blue) Red    ==  False
  69     --
  70     -- * For single-constructor datatypes, the derived instance declarations
  71     -- are as shown for tuples in Figure 1
  72     -- <http://www.haskell.org/onlinelibrary/ix.html#prelude-index>.
  73
  74     ) where
  75
  76 import Prelude
  77
  78 #ifdef __GLASGOW_HASKELL__
  79 import GHC.Arr
  80 #endif
  81
  82 #ifdef __HUGS__
  83 import Hugs.Prelude( Ix(..) )
  84 #endif
  85
  86 #ifdef __NHC__
  87 import Ix (Ix(..))
  88 #endif
  89