NAME

       Set::Infinite::Basic - Sets of intervals 6 =head1 SYNOPSIS

         use Set::Infinite::Basic;

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

DESCRIPTION

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

       It works on reals, integers, and objects.

       This module does not support recurrences. Recurrences are implemented in Set::Infinite.

METHODS

   empty_set
       Creates an empty_set.

       If called from an existing set, the empty set inherits the "type" and "density"
       characteristics.

   universal_set
       Creates a set containing "all" possible elements.

       If called from an existing set, the universal set inherits the "type" and "density"
       characteristics.

   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.

   copy
   clone
       Makes a new object from the object's data.

   Mode functions:
           $set = $set->real;

           $set = $set->integer;

   Logic functions:
           $logic = $set->intersects($b);

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

           $logic = $set->is_null;  # also called "is_empty"

   Set functions:
           $set = $set->union($b);

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

           $set = $set->complement;
           $set = $set->complement($b);   # can also be called "minus" or "difference"

           $set = $set->simmetric_difference( $b );

           $set = $set->span;

               result is (min .. max)

   Scalar functions:
           $i = $set->min;

           $i = $set->max;

           $i = $set->size;

           $i = $set->count;  # number of spans

   Overloaded Perl functions:
           print

           sort, <=>

   Global functions:
           separators(@i)

               chooses the interval separators.

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

           INFINITY

               returns an 'Infinity' number.

           NEG_INFINITY

               returns a '-Infinity' number.

           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:
           $set->fixtype;

           $set->numeric;

CAVEATS

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

           $set = 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)

           $set = 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 internal representation of a span is a hash:

           { a =>   start of span,
             b =>   end of span,
             open_begin =>   '0' the span starts in 'a'
                             '1' the span starts after 'a'
             open_end =>     '0' the span ends in 'b'
                             '1' the span ends before 'b'
           }

       For example, this set:

           [100..200),300,(400..infinity)

       is represented by the array of hashes:

           list => [
               { a => 100, b => 200, open_begin => 0, open_end => 1 },
               { a => 300, b => 300, open_begin => 0, open_end => 0 },
               { a => 400, b => infinity, open_begin => 0, open_end => 1 },
           ]

       The density of a set is stored in the "tolerance" variable:

           tolerance => 0;  # the set is made of real numbers.

           tolerance => 1;  # the set is made of integers.

       The "type" variable stores the class of objects that will be stored in the set.

           type => 'DateTime';   # this is a set of DateTime objects

       The infinity value is generated by Perl, when it finds a numerical overflow:

           $inf = 100**100**100;

SEE ALSO

           Set::Infinite

AUTHOR

           Flavio S. Glock <fglock@gmail.com>