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