/ 
Set-Infinite-0.32
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);
print $a->union(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) and unions.

EXPORT

None by default.

USAGE

$a = Set::Infinite->new();
$a = Set::Infinite->new(1);
$a = Set::Infinite->new(1,2);
$a = Set::Infinite->new($b);
$a = Set::Infinite->new([1], [1,2], [$b]);

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;

Perl functions:

@b = sort @a;

print $a;

Global functions:

separators(@i)

	chooses the interval separators. 

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

null($i)		

	chooses 'null' name. default is ''

infinite($i)

	chooses 'infinite' name. default is 'inf'

infinite

	returns an 'infinite' number.

minus_infinite

	returns '-infinite' number.

null

	returns the 'null' object.

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

	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.

	In array context: returns a tied reference to the array of selected subsets.
	In set context: returns the set of selected subsets.

	Unselected subsets may show as null.

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

		freq     - default=1
		by       - default=[0]
		count    - dafault=infinite

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 { } )

	EXPERIMENTAL - may be removed in next release
	Iterates over a subroutine. 
	Returns the union of partial results.

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->add($b);  # Use $a = $a->union($b) instead.

$a->backtrack($b);

Notes on Dates

Set::Infinite::Date and Set::Infinite::ICal are Date "plugins" for sets.

** NOTE ** Set::Infinite::ICal is still experimental

use:

type('Set::Infinite::Date');  # 2001-05-02 10:00:00   
# or
type('Set::Infinite::ICal');  # 20010502T100000Z

Both require Time::Local. Set::Infinite::ICal requires Date::ICal.

They change quantize function behaviour to accept time units:

use Set::Infinite;
use Set::Infinite::Quantize_Date;
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: ", join (" ", $a->quantize(unit => 'weeks', quant => 1) );

$a = Set::Infinite->new('09:30', '10:35');
print "Quarters of hour in $a: ", join (" ", $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.

AUTHOR

Flavio Soibelmann Glock <fglock@pucrs.br>