Ranged Sets for Haskell
=======================

Ranged sets allow programming with sets of values that are described
by a list of ranges.  A value is a member of the set if it lies within
one of the ranges.  The ranges in a set are ordered and
non-overlapping, so the standard set operations can be implemented by
merge algorithms in O(n) time.

License
-------

Currently the Ranged Set library is under the BSD 3 license.  This is
a very permissive license.  I am hoping that Ranged Sets will
eventually become part of the Base library, and at that point the
implementation will have to be issued under the same license as the
rest of the library (which in practice probably means different
licenses for different compiler versions).  As I understand it the BSD
3 license will allow this without me having to get either assignment
of copyright or explicit permission from everyone who submits
contributions.


Boundaries
----------

Module Data.Ranged.Boundaries defines the Boundary type.  A boundary
divides an ordered type into values above and below the boundary.  No
value can ever sit on a boundary.

Two boundaries are equal if they divide the values at the same point.
This definition of equality causes an implementation problem because
some types are "discrete".  For instance there is no value between the
characters 'a' and 'b', or between the integers 3 and 4.  However
there are values between 3.0 and 4.0.  Similarly for strings, there
are values between "a" and "b" such as "aa", "ab", and so on.  This is
important because "BoundaryAbove 3" is equal to "BoundaryBelow 4".  3
is below both boundaries, and 4 is above both.  Hence they divide the
integers at the same place.  But on the other hand "BoundaryAbove 3.0"
and "BoundaryBelow 4.0" are not equal because 3.5 is above the first
and below the second.

To solve this the DiscreteOrdered class is defined, which provides a
function "adjacent".  Two values x1 and x3 are adjacent if x1 < x3 and
there does not exist an x2 such that x1 < x2 < x3.  This provides the
distinction necessary for boundary equality to be defined for all
ordered types.  The ordered types from the prelude are instances of
DiscreteOrdered, and others can be added by defining "adjacent".  The
functions "enumAdjacent" and "boundedAdjacent" are provided for
instances of Enum and Bounded.  Lists and tuples of DiscreteOrdered
types are also instances of DiscreteOrdered.

This approach was suggested by Ben Rudiak-Gould on
comp.lang.functional.

In theory the Float and Double types should be treated as enumerated
because they are held in fixed-length data fields, and hence must have
pairs of values that are adjacent.  However they are treated as
continuous here for two reasons:

   * The Float and Double types are practical approximations to Real
     numbers, which are continuous.  Hence it makes sense for Float
     and Double to pretend to share this property.

   * There is no standard way to determine the adjacency of Float and
     Double values in Haskell.  "succ 3.0" returns 4.0, which is not
     appropriate here.


Ranges
------

Module Data.Ranged.Ranges defines the Range type.  A range has a lower and an
upper Boundary.

Set-like operations are defined on ranges, but they return variable
numbers of results, and hence return either Maybe Range or [Range].


RangedSet
---------

Module Data.Ranged.RangedSet defines the RSet type.  This is the
actual ranged set type.  It is constructed from a list of ranges.
There are two functions to do this:

   * makeRangedSet takes a finite list of ranges that may overlap or be
     out of order.  It sorts them and merges overlapping ranges using
     the normaliseRangeList function.
     
   * unsafeRangedSet takes a list of ranges that must be in order and not
     overlapping.  The behaviour of the resulting set is not defined if this
     precondition is not met.
     
In theory the standard QuickCheck generator for RSet could generate an
arbitrary list of ranges and then normalise them, but in practice this
tends to produce a very small number of ranges because of the high
probability of overlaps.  So instead an arbitrary list of boundaries
is generated and these are then sorted and paired off into
non-overlapping ranges.


Infinite Sets
-------------

In theory, thanks to lazy evaluation ranged sets can handle infinite
lists of ranges.  These are known as "infinite sets".  Note that this
is not the same as a set with a final upper bound of "AboveAll".

Unfortunately there is no simple way to guarantee that computations on
infinite sets will terminate.  So infinite sets are not supported.

QuickCheck and Tests
--------------------

All the types in the Ranged Set library are instances of Arbitrary from
the QuickCheck library, and the source code includes a number of
important properties for Ranges and RSets defined using QuickCheck.  These 
can be treated as a formal specification of the properties of these types.

The tests can be run by going into the "tests" directory and saying
"make all".  A coverage report is generated, and detailed HTML coverage will
be found in "tests/Report".  "make clean" to delete all the generated files.