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:
34 $set = Set::Infinite->new; # empty set
36 $set = Set::Infinite->new( 10 ); # single element
37 $set = Set::Infinite->new( 10, 20 ); # single range
38 $set = Set::Infinite->new(
39 [ 10, 20 ], [ 50, 70 ] ); # two ranges
40 empty set
42 $set = Set::Infinite->new;
43 set with a single element
45 $set = Set::Infinite->new( 10 );
46 $set = Set::Infinite->new( [ 10 ] );
48 set with a single span
50 $set = Set::Infinite->new( 10, 20 );
51 $set = Set::Infinite->new( [ 10, 20 ] );
53 # 10 <= x <= 20
54 set with a single, open span
56 $set = Set::Infinite->new(
57 {
58 a => 10, open_begin => 0,
59 b => 20, open_end => 1,
60 }
61 );
62 # 10 <= x < 20
63 set with multiple spans
65 $set = Set::Infinite->new( 10, 20, 100, 200 );
66 $set = Set::Infinite->new( [ 10, 20 ], [ 100, 200 ] );
68 $set = Set::Infinite->new(
70 {
71 a => 10, open_begin => 0,
72 b => 20, open_end => 0,
73 },
74 {
75 a => 100, open_begin => 0,
76 b => 200, open_end => 0,
77 }
78 );
79 The "new()" method expects ordered parameters.
81 If you have unordered ranges, you can build the set using "union":
83 @ranges = ( [ 10, 20 ], [ -10, 1 ] );
85 $set = Set::Infinite->new;
86 $set = $set->union( @$_ ) for @ranges;
87 The data structures passed to "new" must be immutable. So this is not
89 good practice:
90 $set = Set::Infinite->new( $object_a, $object_b );
92 $object_a->set_value( 10 );
93 This is the recommended way to do it:
95 $set = Set::Infinite->new( $object_a->clone, $object_b->clone );
97 $object_a->set_value( 10 );
98 clone / copy
100 Creates a new object, and copy the object data.
101 empty_set
103 Creates an empty set.
104 If called from an existing set, the empty set inherits the "type" and
106 "density" characteristics.
107 universal_set
109 Creates a set containing "all" possible elements.
110 If called from an existing set, the universal set inherits the "type"
112 and "density" characteristics.
113
115 union
116 $set = $set->union($b);
117 Returns the set of all elements from both sets.
119 This function behaves like an "OR" operation.
121 $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
123 $set2 = new Set::Infinite( [ 7, 20 ] );
124 print $set1->union( $set2 );
125 # output: [1..4],[7..20]
126 intersection
128 $set = $set->intersection($b);
129 Returns the set of elements common to both sets.
131 This function behaves like an "AND" operation.
133 $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
135 $set2 = new Set::Infinite( [ 7, 20 ] );
136 print $set1->intersection( $set2 );
137 # output: [8..12]
138 complement
140 minus
141 difference
142 $set = $set->complement;
143 Returns the set of all elements that don't belong to the set.
145 $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
147 print $set1->complement;
148 # output: (-inf..1),(4..8),(12..inf)
149 The complement function might take a parameter:
151 $set = $set->minus($b);
153 Returns the set-difference, that is, the elements that don't belong to
155 the given set.
156 $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
158 $set2 = new Set::Infinite( [ 7, 20 ] );
159 print $set1->minus( $set2 );
160 # output: [1..4]
161 symmetric_difference
163 Returns a set containing elements that are in either set, but not in
164 both. This is the "set" version of "XOR".
165
167 real
168 $set1 = $set->real;
169 Returns a set with density "0".
171 integer
173 $set1 = $set->integer;
174 Returns a set with density "1".
176
178 intersects
179 $logic = $set->intersects($b);
180 contains
182 $logic = $set->contains($b);
183 is_empty
185 is_null
186 $logic = $set->is_null;
187 is_nonempty
189 This set that has at least 1 element.
190 is_span
192 This set that has a single span or interval.
193 is_singleton
195 This set that has a single element.
196 is_subset( $set )
198 Every element of this set is a member of the given set.
199 is_proper_subset( $set )
201 Every element of this set is a member of the given set. Some members
202 of the given set are not elements of this set.
203 is_disjoint( $set )
205 The given set has no elements in common with this set.
206 is_too_complex
208 Sometimes a set might be too complex to enumerate or print.
209 This happens with sets that represent infinite recurrences, such as
211 when you ask for a quantization on a set bounded by -inf or inf.
212 See also: "count" method.
214
216 min
217 $i = $set->min;
218 max
220 $i = $set->max;
221 size
223 $i = $set->size;
224 count
226 $i = $set->count;
227
229 stringification
230 print $set;
231 $str = "$set";
233 See also: "as_string".
235 comparison
237 sort
238 > < == >= <= <=>
240 See also: "spaceship" method.
242
244 Set::Infinite->separators(@i)
245 chooses the interval separators for stringification.
247 default are [ ] ( ) '..' ','.
249 inf
251 returns an 'Infinity' number.
253 minus_inf
255 returns '-Infinity' number.
257 type
259 type( "My::Class::Name" )
260 Chooses a default object data type.
262 Default is none (a normal Perl SCALAR).
264
266 span
267 $set1 = $set->span;
268 Returns the set span.
270 until
272 Extends a set until another:
273 0,5,7 -> until 2,6,10
275 gives
277 [0..2), [5..6), [7..10)
279 start_set
281 end_set
282 These methods do the inverse of the "until" method.
283 Given:
285 [0..2), [5..6), [7..10)
287 start_set is:
289 0,5,7
291 end_set is:
293 2,6,10
295 intersected_spans
297 $set = $set1->intersected_spans( $set2 );
298 The method returns a new set, containing all spans that are intersected
300 by the given set.
301 Unlike the "intersection" method, the spans are not modified. See
303 diagram below:
304 set1 [....] [....] [....] [....]
306 set2 [................]
307 intersection [.] [....] [.]
309 intersected_spans [....] [....] [....]
311 quantize
313 quantize( parameters )
314 Makes equal-sized subsets.
316 Returns an ordered set of equal-sized subsets.
318 Example:
320 $set = Set::Infinite->new([1,3]);
322 print join (" ", $set->quantize( quant => 1 ) );
323 Gives:
325 [1..2) [2..3) [3..4)
327 select
329 select( parameters )
330 Selects set spans based on their ordered positions
332 "select" has a behaviour similar to an array "slice".
334 by - default=All
336 count - default=Infinity
337 0 1 2 3 4 5 6 7 8 # original set
339 0 1 2 # count => 3
340 1 6 # by => [ -2, 1 ]
341 offset
343 offset ( parameters )
344 Offsets the subsets. Parameters:
346 value - default=[0,0]
348 mode - default='offset'. Possible values are: 'offset', 'begin', 'end'.
349 unit - type of value. Can be 'days', 'weeks', 'hours', 'minutes', 'seconds'.
350 iterate
352 iterate ( sub { } , @args )
353 Iterates on the set spans, over a callback subroutine. Returns the
355 union of all partial results.
356 The callback argument $_[0] is a span. If there are additional
358 arguments they are passed to the callback.
359 The callback can return a span, a hashref (see "Set::Infinite::Basic"),
361 a scalar, an object, or "undef".
362 [EXPERIMENTAL] "iterate" accepts an optional "backtrack_callback"
364 argument. The purpose of the "backtrack_callback" is to reverse the
365 iterate() function, overcoming the limitations of the internal
366 backtracking algorithm. The syntax is:
367 iterate ( sub { } , backtrack_callback => sub { }, @args )
369 The "backtrack_callback" can return a span, a hashref, a scalar, an
371 object, or "undef".
372 For example, the following snippet adds a constant to each element of
374 an unbounded set:
375 $set1 = $set->iterate(
377 sub { $_[0]->min + 54, $_[0]->max + 54 },
378 backtrack_callback =>
379 sub { $_[0]->min - 54, $_[0]->max - 54 },
380 );
381 first / last
383 first / last
384 In scalar context returns the first or last interval of a set.
386 In list context returns the first or last interval of a set, and the
388 remaining set (the 'tail').
389 See also: "min", "max", "min_a", "max_a" methods.
391 type
393 type( "My::Class::Name" )
394 Chooses a default object data type.
396 default is none (a normal perl SCALAR).
398
400 _backtrack
401 $set->_backtrack( 'intersection', $b );
402 Internal function to evaluate recurrences.
404 numeric
406 $set->numeric;
407 Internal function to ignore the set "type". It is used in some
409 internal optimizations, when it is possible to use scalar values
410 instead of objects.
411 fixtype
413 $set->fixtype;
414 Internal function to fix the result of operations that use the
416 numeric() function.
417 tolerance
419 $set = $set->tolerance(0) # defaults to real sets (default)
420 $set = $set->tolerance(1) # defaults to integer sets
421 Internal function for changing the set "density".
423 min_a
425 ($min, $min_is_open) = $set->min_a;
426 max_a
428 ($max, $max_is_open) = $set->max_a;
429 as_string
431 Implements the "stringification" operator.
432 Stringification of unbounded recurrences is not implemented.
434 Unbounded recurrences are stringified as "function descriptions", if
436 the class variable $PRETTY_PRINT is set.
437 spaceship
439 Implements the "comparison" operator.
440 Comparison of unbounded recurrences is not implemented.
442
444 • constructor "span" notation
445 $set = Set::Infinite->new(10,1);
447 Will be interpreted as [1..10]
449 • constructor "multiple-span" notation
451 $set = Set::Infinite->new(1,2,3,4);
453 Will be interpreted as [1..2],[3..4] instead of [1,2,3,4]. You
455 probably want ->new([1],[2],[3],[4]) instead, or maybe ->new(1,4)
456 • "range operator"
458 $set = Set::Infinite->new(1..3);
460 Will be interpreted as [1..2],3 instead of [1,2,3]. You probably
462 want ->new(1,3) instead.
463
465 The base set object, without recurrences, is a "Set::Infinite::Basic".
466 A recurrence-set is represented by a method name, one or two parent
468 objects, and extra arguments. The "list" key is set to an empty array,
469 and the "too_complex" key is set to 1.
470 This is a structure that holds the union of two "complex sets":
472 {
474 too_complex => 1, # "this is a recurrence"
475 list => [ ], # not used
476 method => 'union', # function name
477 parent => [ $set1, $set2 ], # "leaves" in the syntax-tree
478 param => [ ] # optional arguments for the function
479 }
480 This is a structure that holds the complement of a "complex set":
482 {
484 too_complex => 1, # "this is a recurrence"
485 list => [ ], # not used
486 method => 'complement', # function name
487 parent => $set, # "leaf" in the syntax-tree
488 param => [ ] # optional arguments for the function
489 }
490
492 See modules DateTime::Set, DateTime::Event::Recurrence,
493 DateTime::Event::ICal, DateTime::Event::Cron for up-to-date information
494 on date-sets.
495 The perl-date-time project <http://datetime.perl.org>
497
499 Flavio S. Glock <fglock@gmail.com>
500
502 Copyright (c) 2003 Flavio Soibelmann Glock. All rights reserved. This
503 program is free software; you can redistribute it and/or modify it
504 under the same terms as Perl itself.
505 The full text of the license can be found in the LICENSE file included
507 with this module.
508perl v5.36.0 2022-07-22 Set::Infinite(3)