[project @ 2003-03-08 23:03:47 by panne]
[packages/old-time.git] / 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