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
"Date::Set"
The Reefknot project
AUTHOR
Flavio Soibelmann Glock