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 with reals, integers, and objects.

    When it is used dates, this module provides schedule checks
    (intersections), unions, and infinite recurrences.

SET FUNCTIONS
  union

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

    Returns the set of all elements from both sets.

    This function behaves like a "or" operation.

        $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
        $set2 = new Set::Infinite( [ 7, 20 ] );
        print $set1->union( $set2 );
        # output: [1..4],[7..20]

  intersection

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

    Returns the set of elements common to both sets.

    This function behaves like a "and" operation.

        $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
        $set2 = new Set::Infinite( [ 7, 20 ] );
        print $set1->intersection( $set2 );
        # output: [8..12]

  complement

        $set = $a->complement;

    Returns the set of all elements that don't belong to the set.

        $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
        print $set1->complement;
        # output: (-inf..1),(4..8),(12..inf)

    The complement function might take a parameter:

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

    Returns the set-difference, that is, the elements that don't belong to
    the given set.

        $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
        $set2 = new Set::Infinite( [ 7, 20 ] );
        print $set1->complement( $set2 );
        # output: [1..4]

DENSITY FUNCTIONS
  real

        $a->real;

    Returns a set with density "0".

  integer

        $a->integer;

    Returns a set with density "1".

LOGIC FUNCTIONS
  intersects

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

  contains

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

  is_null

        $logic = $a->is_null;

  is_too_complex

    Sometimes a set might be too complex to enumerate or print.

    This happens with sets that represent infinite recurrences, such as when
    you ask for a quantization on a set bounded by -inf or inf.

SCALAR FUNCTIONS
  min

        $i = $a->min;

  max

        $i = $a->max;

  size

        $i = $a->size;  

OVERLOADED LANGUAGE OPERATORS
  stringification

        print    

  comparison

        sort, <=> 

CLASS METHODS
        separators(@i)

            chooses the interval separators. 

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

        inf

            returns an 'Infinity' number.

        minus_inf

            returns '-Infinity' number.

SPECIAL SET FUNCTIONS (WIDGETS)
  span

        $i = $a->span;

            result is INTERVAL, (min .. max)

  until

    Extends a set until another:

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

    gives

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

    Note: this function is still experimental.

  quantize

        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

        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

        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

        iterate ( sub { } , @args )

    Iterates on the set spans, over a callback subroutine. Returns the union
    of all partial results.

    The callback argument "$_[0]" is a span. If there are additional
    arguments they are passed to the callback.

    The callback can return a span, a hashref (see "Set::Infinite::Basic"),
    a scalar, an object, or "undef".

  first / last

        first / last

    In scalar context returns the first interval of a set.

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

    Works even in unbounded sets

  type

        type($i)

    Chooses a default 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 modules DateTime::Set and 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
    * "span" notation
            $a = Set::Infinite->new(10,1);

        Will be interpreted as [1..10]

    * "multiple-span" notation
            $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)

    * "range operator"
            $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.

INTERNALS
    The base *set* object, without recurrences, is a "Set::Infinite::Basic".

    A *recurrence-set* is represented by a *method name*, one or two *parent
    objects*, and extra arguments. The "list" key is set to an empty array,
    and the "too_complex" key is set to "1".

    This is a structure that holds a union of two "complex sets":

      {
        too_complex => 1,             # "this is a recurrence"
        list   => [ ],                # not used
        method => 'union',            # function name
        parent => [ $set1, $set2 ],   # "leaves" in the syntax-tree
        param  => [ ]                 # optional arguments for the function
      }

    This is a structure that holds the complement of a "complex set":

      {
        too_complex => 1,             # "this is a recurrence"
        list   => [ ],                # not used
        method => 'complement',       # function name
        parent => $set,               # "leaf" in the syntax-tree
        param  => [ ]                 # optional arguments for the function
      }

SEE ALSO
    "DateTime::Set"

    The perl-date-time project <http://datetime.perl.org>

    "Date::Set"

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

AUTHOR
    Flavio Soibelmann Glock <fglock@pucrs.br>

