1Set::Infinite(3)      User Contributed Perl Documentation     Set::Infinite(3)
2
3
4

NAME

6       Set::Infinite - Sets of intervals
7

SYNOPSIS

9         use Set::Infinite;
10
11         $set = Set::Infinite->new(1,2);    # [1..2]
12         print $set->union(5,6);            # [1..2],[5..6]
13

DESCRIPTION

15       Set::Infinite is a Set Theory module for infinite sets.
16
17       A set is a collection of objects.  The objects that belong to a set are
18       called its members, or "elements".
19
20       As objects we allow (almost) anything:  reals, integers, and objects
21       (such as dates).
22
23       We allow sets to be infinite.
24
25       There is no account for the order of elements. For example, {1,2} =
26       {2,1}.
27
28       There is no account for repetition of elements. For example, {1,2,2} =
29       {1,1,1,2} = {1,2}.
30

CONSTRUCTOR

32   new
33       Creates a new set object:
34
35           $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
41       empty set
42               $set = Set::Infinite->new;
43
44       set with a single element
45               $set = Set::Infinite->new( 10 );
46
47               $set = Set::Infinite->new( [ 10 ] );
48
49       set with a single span
50               $set = Set::Infinite->new( 10, 20 );
51
52               $set = Set::Infinite->new( [ 10, 20 ] );
53               # 10 <= x <= 20
54
55       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
64       set with multiple spans
65               $set = Set::Infinite->new( 10, 20,  100, 200 );
66
67               $set = Set::Infinite->new( [ 10, 20 ], [ 100, 200 ] );
68
69               $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
80       The "new()" method expects ordered parameters.
81
82       If you have unordered ranges, you can build the set using "union":
83
84           @ranges = ( [ 10, 20 ], [ -10, 1 ] );
85           $set = Set::Infinite->new;
86           $set = $set->union( @$_ ) for @ranges;
87
88       The data structures passed to "new" must be immutable.  So this is not
89       good practice:
90
91           $set = Set::Infinite->new( $object_a, $object_b );
92           $object_a->set_value( 10 );
93
94       This is the recommended way to do it:
95
96           $set = Set::Infinite->new( $object_a->clone, $object_b->clone );
97           $object_a->set_value( 10 );
98
99   clone / copy
100       Creates a new object, and copy the object data.
101
102   empty_set
103       Creates an empty set.
104
105       If called from an existing set, the empty set inherits the "type" and
106       "density" characteristics.
107
108   universal_set
109       Creates a set containing "all" possible elements.
110
111       If called from an existing set, the universal set inherits the "type"
112       and "density" characteristics.
113

SET FUNCTIONS

115   union
116           $set = $set->union($b);
117
118       Returns the set of all elements from both sets.
119
120       This function behaves like an "OR" operation.
121
122           $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
127   intersection
128           $set = $set->intersection($b);
129
130       Returns the set of elements common to both sets.
131
132       This function behaves like an "AND" operation.
133
134           $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
139   complement
140   minus
141   difference
142           $set = $set->complement;
143
144       Returns the set of all elements that don't belong to the set.
145
146           $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
147           print $set1->complement;
148           # output: (-inf..1),(4..8),(12..inf)
149
150       The complement function might take a parameter:
151
152           $set = $set->minus($b);
153
154       Returns the set-difference, that is, the elements that don't belong to
155       the given set.
156
157           $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
162   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

DENSITY METHODS

167   real
168           $set1 = $set->real;
169
170       Returns a set with density "0".
171
172   integer
173           $set1 = $set->integer;
174
175       Returns a set with density "1".
176

LOGIC FUNCTIONS

178   intersects
179           $logic = $set->intersects($b);
180
181   contains
182           $logic = $set->contains($b);
183
184   is_empty
185   is_null
186           $logic = $set->is_null;
187
188   is_nonempty
189       This set that has at least 1 element.
190
191   is_span
192       This set that has a single span or interval.
193
194   is_singleton
195       This set that has a single element.
196
197   is_subset( $set )
198       Every element of this set is a member of the given set.
199
200   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
204   is_disjoint( $set )
205       The given set has no elements in common with this set.
206
207   is_too_complex
208       Sometimes a set might be too complex to enumerate or print.
209
210       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
213       See also: "count" method.
214

SCALAR FUNCTIONS

216   min
217           $i = $set->min;
218
219   max
220           $i = $set->max;
221
222   size
223           $i = $set->size;
224
225   count
226           $i = $set->count;
227

OVERLOADED OPERATORS

229   stringification
230           print $set;
231
232           $str = "$set";
233
234       See also: "as_string".
235
236   comparison
237           sort
238
239           > < == >= <= <=>
240
241       See also: "spaceship" method.
242

CLASS METHODS

244           Set::Infinite->separators(@i)
245
246               chooses the interval separators for stringification.
247
248               default are [ ] ( ) '..' ','.
249
250           inf
251
252               returns an 'Infinity' number.
253
254           minus_inf
255
256               returns '-Infinity' number.
257
258   type
259           type( "My::Class::Name" )
260
261       Chooses a default object data type.
262
263       Default is none (a normal Perl SCALAR).
264

SPECIAL SET FUNCTIONS

266   span
267           $set1 = $set->span;
268
269       Returns the set span.
270
271   until
272       Extends a set until another:
273
274           0,5,7 -> until 2,6,10
275
276       gives
277
278           [0..2), [5..6), [7..10)
279
280   start_set
281   end_set
282       These methods do the inverse of the "until" method.
283
284       Given:
285
286           [0..2), [5..6), [7..10)
287
288       start_set is:
289
290           0,5,7
291
292       end_set is:
293
294           2,6,10
295
296   intersected_spans
297           $set = $set1->intersected_spans( $set2 );
298
299       The method returns a new set, containing all spans that are intersected
300       by the given set.
301
302       Unlike the "intersection" method, the spans are not modified.  See
303       diagram below:
304
305                      set1   [....]   [....]   [....]   [....]
306                      set2      [................]
307
308              intersection      [.]   [....]   [.]
309
310         intersected_spans   [....]   [....]   [....]
311
312   quantize
313           quantize( parameters )
314
315               Makes equal-sized subsets.
316
317               Returns an ordered set of equal-sized subsets.
318
319               Example:
320
321                   $set = Set::Infinite->new([1,3]);
322                   print join (" ", $set->quantize( quant => 1 ) );
323
324               Gives:
325
326                   [1..2) [2..3) [3..4)
327
328   select
329           select( parameters )
330
331       Selects set spans based on their ordered positions
332
333       "select" has a behaviour similar to an array "slice".
334
335                   by       - default=All
336                   count    - default=Infinity
337
338        0  1  2  3  4  5  6  7  8      # original set
339        0  1  2                        # count => 3
340           1              6            # by => [ -2, 1 ]
341
342   offset
343           offset ( parameters )
344
345       Offsets the subsets. Parameters:
346
347           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
351   iterate
352           iterate ( sub { } , @args )
353
354       Iterates on the set spans, over a callback subroutine.  Returns the
355       union of all partial results.
356
357       The callback argument $_[0] is a span. If there are additional
358       arguments they are passed to the callback.
359
360       The callback can return a span, a hashref (see "Set::Infinite::Basic"),
361       a scalar, an object, or "undef".
362
363       [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
368           iterate ( sub { } , backtrack_callback => sub { }, @args )
369
370       The "backtrack_callback" can return a span, a hashref, a scalar, an
371       object, or "undef".
372
373       For example, the following snippet adds a constant to each element of
374       an unbounded set:
375
376           $set1 = $set->iterate(
377                        sub { $_[0]->min + 54, $_[0]->max + 54 },
378                     backtrack_callback =>
379                        sub { $_[0]->min - 54, $_[0]->max - 54 },
380                     );
381
382   first / last
383           first / last
384
385       In scalar context returns the first or last interval of a set.
386
387       In list context returns the first or last interval of a set, and the
388       remaining set (the 'tail').
389
390       See also: "min", "max", "min_a", "max_a" methods.
391
392   type
393           type( "My::Class::Name" )
394
395       Chooses a default object data type.
396
397       default is none (a normal perl SCALAR).
398

INTERNAL FUNCTIONS

400   _backtrack
401           $set->_backtrack( 'intersection', $b );
402
403       Internal function to evaluate recurrences.
404
405   numeric
406           $set->numeric;
407
408       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
412   fixtype
413           $set->fixtype;
414
415       Internal function to fix the result of operations that use the
416       numeric() function.
417
418   tolerance
419           $set = $set->tolerance(0)    # defaults to real sets (default)
420           $set = $set->tolerance(1)    # defaults to integer sets
421
422       Internal function for changing the set "density".
423
424   min_a
425           ($min, $min_is_open) = $set->min_a;
426
427   max_a
428           ($max, $max_is_open) = $set->max_a;
429
430   as_string
431       Implements the "stringification" operator.
432
433       Stringification of unbounded recurrences is not implemented.
434
435       Unbounded recurrences are stringified as "function descriptions", if
436       the class variable $PRETTY_PRINT is set.
437
438   spaceship
439       Implements the "comparison" operator.
440
441       Comparison of unbounded recurrences is not implemented.
442

CAVEATS

444       •   constructor "span" notation
445
446               $set = Set::Infinite->new(10,1);
447
448           Will be interpreted as [1..10]
449
450       •   constructor "multiple-span" notation
451
452               $set = Set::Infinite->new(1,2,3,4);
453
454           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
457       •   "range operator"
458
459               $set = Set::Infinite->new(1..3);
460
461           Will be interpreted as [1..2],3 instead of [1,2,3].  You probably
462           want ->new(1,3) instead.
463

INTERNALS

465       The base set object, without recurrences, is a "Set::Infinite::Basic".
466
467       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
471       This is a structure that holds the union of two "complex sets":
472
473         {
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
481       This is a structure that holds the complement of a "complex set":
482
483         {
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

SEE ALSO

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
496       The perl-date-time project <http://datetime.perl.org>
497

AUTHOR

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
506       The full text of the license can be found in the LICENSE file included
507       with this module.
508
509
510
511perl v5.36.0                      2022-07-22                  Set::Infinite(3)
Impressum