1Set::Infinite(3) User Contributed Perl Documentation Set::Infinite(3)
2
6 Set::Infinite - Sets of intervals
7
9 use Set::Infinite;
10 $set = Set::Infinite->new(1,2); # [1..2]
12 print $set->union(5,6); # [1..2],[5..6]
13
15 Set::Infinite is a Set Theory module for infinite sets.
16 A set is a collection of objects. The objects that belong to a set are
18 called its members, or "elements".
19 As objects we allow (almost) anything: reals, integers, and objects
21 (such as dates).
22 We allow sets to be infinite.
24 There is no account for the order of elements. For example, {1,2} =
26 {2,1}.
27 There is no account for repetition of elements. For example, {1,2,2} =
29 {1,1,1,2} = {1,2}.
30
32 new
33 Creates a new set object:
35 $set = Set::Infinite->new; # empty set
37 $set = Set::Infinite->new( 10 ); # single element
38 $set = Set::Infinite->new( 10, 20 ); # single range
39 $set = Set::Infinite->new(
40 [ 10, 20 ], [ 50, 70 ] ); # two ranges
41 empty set
43 $set = Set::Infinite->new;
44 set with a single element
46 $set = Set::Infinite->new( 10 );
47 $set = Set::Infinite->new( [ 10 ] );
49 set with a single span
51 $set = Set::Infinite->new( 10, 20 );
52 $set = Set::Infinite->new( [ 10, 20 ] );
54 # 10 <= x <= 20
55 set with a single, open span
57 $set = Set::Infinite->new(
58 {
59 a => 10, open_begin => 0,
60 b => 20, open_end => 1,
61 }
62 );
63 # 10 <= x < 20
64 set with multiple spans
66 $set = Set::Infinite->new( 10, 20, 100, 200 );
67 $set = Set::Infinite->new( [ 10, 20 ], [ 100, 200 ] );
69 $set = Set::Infinite->new(
71 {
72 a => 10, open_begin => 0,
73 b => 20, open_end => 0,
74 },
75 {
76 a => 100, open_begin => 0,
77 b => 200, open_end => 0,
78 }
79 );
80 The "new()" method expects ordered parameters.
82 If you have unordered ranges, you can build the set using "union":
84 @ranges = ( [ 10, 20 ], [ -10, 1 ] );
86 $set = Set::Infinite->new;
87 $set = $set->union( @$_ ) for @ranges;
88 The data structures passed to "new" must be immutable. So this is not
90 good practice:
91 $set = Set::Infinite->new( $object_a, $object_b );
93 $object_a->set_value( 10 );
94 This is the recommended way to do it:
96 $set = Set::Infinite->new( $object_a->clone, $object_b->clone );
98 $object_a->set_value( 10 );
99 clone / copy
101 Creates a new object, and copy the object data.
103 empty_set
105 Creates an empty set.
107 If called from an existing set, the empty set inherits the "type" and
109 "density" characteristics.
110 universal_set
112 Creates a set containing "all" possible elements.
114 If called from an existing set, the universal set inherits the "type"
116 and "density" characteristics.
117
119 union
120 $set = $set->union($b);
122 Returns the set of all elements from both sets.
124 This function behaves like an "OR" operation.
126 $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
128 $set2 = new Set::Infinite( [ 7, 20 ] );
129 print $set1->union( $set2 );
130 # output: [1..4],[7..20]
131 intersection
133 $set = $set->intersection($b);
135 Returns the set of elements common to both sets.
137 This function behaves like an "AND" operation.
139 $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
141 $set2 = new Set::Infinite( [ 7, 20 ] );
142 print $set1->intersection( $set2 );
143 # output: [8..12]
144 complement
146 minus
148 difference
150 $set = $set->complement;
152 Returns the set of all elements that don't belong to the set.
154 $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
156 print $set1->complement;
157 # output: (-inf..1),(4..8),(12..inf)
158 The complement function might take a parameter:
160 $set = $set->minus($b);
162 Returns the set-difference, that is, the elements that don't belong to
164 the given set.
165 $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
167 $set2 = new Set::Infinite( [ 7, 20 ] );
168 print $set1->minus( $set2 );
169 # output: [1..4]
170 simmetric_difference
172 Returns a set containing elements that are in either set, but not in
174 both. This is the "set" version of "XOR".
175
177 real
178 $set1 = $set->real;
180 Returns a set with density "0".
182 integer
184 $set1 = $set->integer;
186 Returns a set with density "1".
188
190 intersects
191 $logic = $set->intersects($b);
193 contains
195 $logic = $set->contains($b);
197 is_empty
199 is_null
201 $logic = $set->is_null;
203 is_nonempty
205 This set that has at least 1 element.
207 is_span
209 This set that has a single span or interval.
211 is_singleton
213 This set that has a single element.
215 is_subset( $set )
217 Every element of this set is a member of the given set.
219 is_proper_subset( $set )
221 Every element of this set is a member of the given set. Some members
223 of the given set are not elements of this set.
224 is_disjoint( $set )
226 The given set has no elements in common with this set.
228 is_too_complex
230 Sometimes a set might be too complex to enumerate or print.
232 This happens with sets that represent infinite recurrences, such as
234 when you ask for a quantization on a set bounded by -inf or inf.
235 See also: "count" method.
237
239 min
240 $i = $set->min;
242 max
244 $i = $set->max;
246 size
248 $i = $set->size;
250 count
252 $i = $set->count;
254
256 stringification
257 print $set;
259 $str = "$set";
261 See also: "as_string".
263 comparison
265 sort
267 > < == >= <= <=>
269 See also: "spaceship" method.
271
273 Set::Infinite->separators(@i)
274 chooses the interval separators for stringification.
276 default are [ ] ( ) '..' ','.
278 inf
280 returns an 'Infinity' number.
282 minus_inf
284 returns '-Infinity' number.
286 type
288 type( "My::Class::Name" )
290 Chooses a default object data type.
292 Default is none (a normal Perl SCALAR).
294
296 span
297 $set1 = $set->span;
299 Returns the set span.
301 until
303 Extends a set until another:
305 0,5,7 -> until 2,6,10
307 gives
309 [0..2), [5..6), [7..10)
311 start_set
313 end_set
315 These methods do the inverse of the "until" method.
317 Given:
319 [0..2), [5..6), [7..10)
321 start_set is:
323 0,5,7
325 end_set is:
327 2,6,10
329 intersected_spans
331 $set = $set1->intersected_spans( $set2 );
333 The method returns a new set, containing all spans that are intersected
335 by the given set.
336 Unlike the "intersection" method, the spans are not modified. See dia‐
338 gram below:
339 set1 [....] [....] [....] [....]
341 set2 [................]
342 intersection [.] [....] [.]
344 intersected_spans [....] [....] [....]
346 quantize
348 quantize( parameters )
350 Makes equal-sized subsets.
352 Returns an ordered set of equal-sized subsets.
354 Example:
356 $set = Set::Infinite->new([1,3]);
358 print join (" ", $set->quantize( quant => 1 ) );
359 Gives:
361 [1..2) [2..3) [3..4)
363 select
365 select( parameters )
367 Selects set spans based on their ordered positions
369 "select" has a behaviour similar to an array "slice".
371 by - default=All
373 count - default=Infinity
374 0 1 2 3 4 5 6 7 8 # original set
376 0 1 2 # count => 3
377 1 6 # by => [ -2, 1 ]
378 offset
380 offset ( parameters )
382 Offsets the subsets. Parameters:
384 value - default=[0,0]
386 mode - default='offset'. Possible values are: 'offset', 'begin', 'end'.
387 unit - type of value. Can be 'days', 'weeks', 'hours', 'minutes', 'seconds'.
388 iterate
390 iterate ( sub { } , @args )
392 Iterates on the set spans, over a callback subroutine. Returns the
394 union of all partial results.
395 The callback argument $_[0] is a span. If there are additional argu‐
397 ments they are passed to the callback.
398 The callback can return a span, a hashref (see "Set::Infinite::Basic"),
400 a scalar, an object, or "undef".
401 [EXPERIMENTAL] "iterate" accepts an optional "backtrack_callback" argu‐
403 ment. The purpose of the "backtrack_callback" is to reverse the iter‐
404 ate() function, overcoming the limitations of the internal backtracking
405 algorithm. The syntax is:
406 iterate ( sub { } , backtrack_callback => sub { }, @args )
408 The "backtrack_callback" can return a span, a hashref, a scalar, an
410 object, or "undef".
411 For example, the following snippet adds a constant to each element of
413 an unbounded set:
414 $set1 = $set->iterate(
416 sub { $_[0]->min + 54, $_[0]->max + 54 },
417 backtrack_callback =>
418 sub { $_[0]->min - 54, $_[0]->max - 54 },
419 );
420 first / last
422 first / last
424 In scalar context returns the first or last interval of a set.
426 In list context returns the first or last interval of a set, and the
428 remaining set (the 'tail').
429 See also: "min", "max", "min_a", "max_a" methods.
431 type
433 type( "My::Class::Name" )
435 Chooses a default object data type.
437 default is none (a normal perl SCALAR).
439
441 _backtrack
442 $set->_backtrack( 'intersection', $b );
444 Internal function to evaluate recurrences.
446 numeric
448 $set->numeric;
450 Internal function to ignore the set "type". It is used in some inter‐
452 nal optimizations, when it is possible to use scalar values instead of
453 objects.
454 fixtype
456 $set->fixtype;
458 Internal function to fix the result of operations that use the
460 numeric() function.
461 tolerance
463 $set = $set->tolerance(0) # defaults to real sets (default)
465 $set = $set->tolerance(1) # defaults to integer sets
466 Internal function for changing the set "density".
468 min_a
470 ($min, $min_is_open) = $set->min_a;
472 max_a
474 ($max, $max_is_open) = $set->max_a;
476 as_string
478 Implements the "stringification" operator.
480 Stringification of unbounded recurrences is not implemented.
482 Unbounded recurrences are stringified as "function descriptions", if
484 the class variable $PRETTY_PRINT is set.
485 spaceship
487 Implements the "comparison" operator.
489 Comparison of unbounded recurrences is not implemented.
491
493 * constructor "span" notation
494 $set = Set::Infinite->new(10,1);
495 Will be interpreted as [1..10]
497 * constructor "multiple-span" notation
499 $set = Set::Infinite->new(1,2,3,4);
500 Will be interpreted as [1..2],[3..4] instead of [1,2,3,4]. You
502 probably want ->new([1],[2],[3],[4]) instead, or maybe ->new(1,4)
503 * "range operator"
505 $set = Set::Infinite->new(1..3);
506 Will be interpreted as [1..2],3 instead of [1,2,3]. You probably
508 want ->new(1,3) instead.
509
511 The base set object, without recurrences, is a "Set::Infinite::Basic".
512 A recurrence-set is represented by a method name, one or two parent
514 objects, and extra arguments. The "list" key is set to an empty array,
515 and the "too_complex" key is set to 1.
516 This is a structure that holds the union of two "complex sets":
518 {
520 too_complex => 1, # "this is a recurrence"
521 list => [ ], # not used
522 method => 'union', # function name
523 parent => [ $set1, $set2 ], # "leaves" in the syntax-tree
524 param => [ ] # optional arguments for the function
525 }
526 This is a structure that holds the complement of a "complex set":
528 {
530 too_complex => 1, # "this is a recurrence"
531 list => [ ], # not used
532 method => 'complement', # function name
533 parent => $set, # "leaf" in the syntax-tree
534 param => [ ] # optional arguments for the function
535 }
536
538 See modules DateTime::Set, DateTime::Event::Recurrence, Date‐
539 Time::Event::ICal, DateTime::Event::Cron for up-to-date information on
540 date-sets.
541 The perl-date-time project <http://datetime.perl.org>
543
545 Flavio Soibelmann Glock <fglock@pucrs.br>
546
548 Copyright (c) 2003 Flavio Soibelmann Glock. All rights reserved. This
549 program is free software; you can redistribute it and/or modify it
550 under the same terms as Perl itself.
551 The full text of the license can be found in the LICENSE file included
553 with this module.
554perl v5.8.8 2004-11-03 Set::Infinite(3)