/ 
Set-Infinite-0.44_04
River stage three • 4 direct dependents • 187 total dependents
/ Set::Infinite

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 with dates too, 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)

Note: this function is still experimental.

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 [ ] ( ) '..' ','.

inf

    returns an 'Infinity' number.

minus_inf

    returns '-Infinity' number.

Special set functions

   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 { } , @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

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($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

$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.

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 a reference to an empty array, and the too_complex key is set to 1.

too_complex => 1,   # "this is a recurrence"
list   => [ ],      # not used
method => 'union',  # function name
parent => [ $set1, $set2 ],   # leaves in 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>