NAME
    Set::Infinite - Sets of intervals

SYNOPSIS
      use Set::Infinite;

      $a = Set::Infinite->new(1,2);    # [1..2]
      print $a->union(5,6);            # [1..2],[5..6]

DESCRIPTION
    Set::Infinite is a Set Theory module for infinite sets.

    It works on reals or integers. You can provide your own objects or let
    it make them for you using the `type'.

    It works very well on dates, providing schedule checks (intersections),
    unions, and infinite recurrences.

METHODS
  is_too_complex

    Sometimes a set might be too complex to print. It will happen when you
    ask for a quantization on a set bounded by -inf or inf.

  until

    Extends a set until another:

        0,5,7 -> until 2,6,10

    gives

        [0..2), [5..6), [7..10)

  copy

    Makes a new object from the object's data.

  Mode functions:

        $a->real;

        $a->integer;

  Logic functions:

        $logic = $a->intersects($b);

        $logic = $a->contains($b);

        $logic = $a->is_null;

  Set functions:

        $i = $a->union($b);    

        $i = $a->intersection($b);

        $i = $a->complement;
        $i = $a->complement($b);

        $i = $a->span;   

            result is INTERVAL, (min .. max)

  Scalar functions:

        $i = $a->min;

        $i = $a->max;

        $i = $a->size;  

  Overloaded Perl functions:

        print    

        sort, <=> 

  Global functions:

        separators(@i)

            chooses the interval separators. 

            default are [ ] ( ) '..' ','.

        infinite($i)

            chooses 'infinite' name. default is 'inf'

        inf

            returns an 'Infinity' number.

        minus_inf

            returns '-Infinity' number.

        quantize( parameters )

            Makes equal-sized subsets.

            In array context: returns a tied reference to the subset list.
            In set context: returns an ordered set of equal-sized subsets.

            The quantization function is external to this module:
            Parameters may vary depending on implementation. 

            Positions for which a subset does not exist may show as undef.

            Example: 

                $a = Set::Infinite->new([1,3]);
                print join (" ", $a->quantize( quant => 1 ) );

            Gives: 

                [1..2) [2..3) [3..4)

        select( parameters )

            Selects set members based on their ordered positions
            (Selection is more useful after quantization).

                freq     - default=1
                by       - default=[0]
                count    - default=Infinity

     0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15    # [0..15] quantized by "1"

     0              5             10             15    # freq => 5

        1     3        6     8       11    13          # freq => 5, by => [ -2, 1 ]

        1     3        6     8                         # freq => 5, by => [ -2, 1 ], count => 2

        1                                     14       # by => [ -2, 1 ]

        offset ( parameters )

            Offsets the subsets. Parameters: 

                value   - default=[0,0]
                mode    - default='offset'. Possible values are: 'offset', 'begin', 'end'.
                unit    - type of value. Can be 'days', 'weeks', 'hours', 'minutes', 'seconds'.

        iterate ( sub { } )

            Iterates over a subroutine. 
            Returns the union of partial results.

        first

            In scalar context returns the first interval of a set.

            In list context returns the first interval of a set, and the
            'tail'.

            Works in unbounded sets

        type($i)

            chooses an object data type. 

            default is none (a normal perl SCALAR).

            examples: 

            type('Math::BigFloat');
            type('Math::BigInt');
            type('Set::Infinite::Date');
                See notes on Set::Infinite::Date below.

        tolerance(0)    defaults to real sets (default)
        tolerance(1)    defaults to integer sets

        real            defaults to real sets (default)

        integer         defaults to integer sets

  Internal functions:

        $a->cleanup;

        $a->backtrack($b);

        $a->fixtype; 

        $a->numeric;

Notes on Dates
    See module Date::Set for up-to-date information on date-sets.

    Set::Infinite::Date is a Date "plug-in" for sets.

    usage:

        type('Set::Infinite::Date');  # allows values like '2001-05-02 10:00:00'

    Set::Infinite::Date requires Time::Local.

        use Set::Infinite;
        Set::Infinite->type('Set::Infinite::Date');
        Set::Infinite::Date->date_format("year-month-day");

        $a = Set::Infinite->new('2001-05-02', '2001-05-13');
        print "Weeks in $a: ", $a->quantize(unit => 'weeks', quant => 1);

        $a = Set::Infinite->new('09:30', '10:35');
        print "Quarters of hour in $a: ", $a->quantize(unit => 'minutes', quant => 15);

    Quantize units can be years, months, days, weeks, hours, minutes, or
    seconds. To quantize the year to first-week-of-year until
    last-week-of-year, use 'weekyears':

            ->quantize( unit => weekyears, wkst => 1 )

    'wkst' parameter is '1' for monday (default), '7' for sunday.

    max and min functions will also show in date/time format.

CAVEATS
        $a = Set::Infinite->new(10,1);
            Will be interpreted as [1..10]

        $a = Set::Infinite->new(1,2,3,4);
            Will be interpreted as [1..2],[3..4] instead of [1,2,3,4].
            You probably want ->new([1],[2],[3],[4]) instead,
            or maybe ->new(1,4) 

        $a = Set::Infinite->new(1..3);
            Will be interpreted as [1..2],3 instead of [1,2,3].
            You probably want ->new(1,3) instead.

SEE ALSO
        Date::Set

        the Reefknot project <http://reefknot.sf.net>

AUTHOR
        Flavio Soibelmann Glock <fglock@pucrs.br>

