DateTime::SpanSet(3pm)

1DateTime::SpanSet(3)  User Contributed Perl Documentation DateTime::SpanSet(3)
2
3
4

NAME

6       DateTime::SpanSet - set of DateTime spans
7

SYNOPSIS

9           $spanset = DateTime::SpanSet->from_spans( spans => [ $dt_span, $dt_span ] );
10
11           $set = $spanset->union( $set2 );         # like "OR", "insert", "both"
12           $set = $spanset->complement( $set2 );    # like "delete", "remove"
13           $set = $spanset->intersection( $set2 );  # like "AND", "while"
14           $set = $spanset->complement;             # like "NOT", "negate", "invert"
15
16           if ( $spanset->intersects( $set2 ) ) { ...  # like "touches", "interferes"
17           if ( $spanset->contains( $set2 ) ) { ...    # like "is-fully-inside"
18
19           # data extraction
20           $date = $spanset->min;           # first date of the set
21           $date = $spanset->max;           # last date of the set
22
23           $iter = $spanset->iterator;
24           while ( $dt = $iter->next ) {
25               # $dt is a DateTime::Span
26               print $dt->start->ymd;   # first date of span
27               print $dt->end->ymd;     # last date of span
28           };
29

DESCRIPTION

31       "DateTime::SpanSet" is a class that represents sets of datetime spans.
32       An example would be a recurring meeting that occurs from 13:00-15:00
33       every Friday.
34
35       This is different from a "DateTime::Set", which is made of individual
36       datetime points as opposed to ranges.
37

METHODS

39       •   from_spans
40
41           Creates a new span set from one or more "DateTime::Span" objects.
42
43              $spanset = DateTime::SpanSet->from_spans( spans => [ $dt_span ] );
44
45       •   from_set_and_duration
46
47           Creates a new span set from one or more "DateTime::Set" objects and
48           a duration.
49
50           The duration can be a "DateTime::Duration" object, or the
51           parameters to create a new "DateTime::Duration" object, such as
52           "days", "months", etc.
53
54              $spanset =
55                  DateTime::SpanSet->from_set_and_duration
56                      ( set => $dt_set, days => 1 );
57
58       •   from_sets
59
60           Creates a new span set from two "DateTime::Set" objects.
61
62           One set defines the starting dates, and the other defines the end
63           dates.
64
65              $spanset =
66                  DateTime::SpanSet->from_sets
67                      ( start_set => $dt_set1, end_set => $dt_set2 );
68
69           The spans have the starting date "closed", and the end date "open",
70           like in "[$dt1, $dt2)".
71
72           If an end date comes without a starting date before it, then it
73           defines a span like "(-inf, $dt)".
74
75           If a starting date comes without an end date after it, then it
76           defines a span like "[$dt, inf)".
77
78       •   empty_set
79
80           Creates a new empty set.
81
82       •   is_empty_set
83
84           Returns true is the set is empty; false otherwise.
85
86               print "nothing" if $set->is_empty_set;
87
88       •   clone
89
90           This object method returns a replica of the given object.
91
92       •   set_time_zone( $tz )
93
94           This method accepts either a time zone object or a string that can
95           be passed as the "name" parameter to "DateTime::TimeZone->new()".
96           If the new time zone's offset is different from the old time zone,
97           then the local time is adjusted accordingly.
98
99           If the old time zone was a floating time zone, then no adjustments
100           to the local time are made, except to account for leap seconds.  If
101           the new time zone is floating, then the UTC time is adjusted in
102           order to leave the local time untouched.
103
104       •   start, min
105
106       •   end, max
107
108           First or last dates in the set.
109
110           It is possible that the return value from these methods may be a
111           "DateTime::Infinite::Future" or a "DateTime::Infinite::Past"
112           object.
113
114           If the set ends "before" a date $dt, it returns $dt. Note that in
115           this case $dt is not a set element - but it is a set boundary.
116
117           These methods may return "undef" if the set is empty.
118
119           These methods return just a copy of the actual boundary value.  If
120           you modify the result, the set will not be modified.
121
122       •   duration
123
124           The total size of the set, as a "DateTime::Duration" object.
125
126           The duration may be infinite.
127
128           Also available as "size()".
129
130       •   span
131
132           The total span of the set, as a "DateTime::Span" object.
133
134       •   next
135
136             my $span = $set->next( $dt );
137
138           This method is used to find the next span in the set, after a given
139           datetime or span.
140
141           The return value is a "DateTime::Span", or "undef" if there is no
142           matching span in the set.
143
144       •   previous
145
146             my $span = $set->previous( $dt );
147
148           This method is used to find the previous span in the set, before a
149           given datetime or span.
150
151           The return value is a "DateTime::Span", or "undef" if there is no
152           matching span in the set.
153
154       •   current
155
156             my $span = $set->current( $dt );
157
158           This method is used to find the "current" span in the set, that
159           intersects a given datetime or span. If no current span is found,
160           then the "previous" span is returned.
161
162           The return value is a "DateTime::SpanSet", or "undef" if there is
163           no matching span in the set.
164
165           If a span parameter is given, it may happen that "current" returns
166           more than one span.
167
168           See also: "intersected_spans()" method.
169
170       •   closest
171
172             my $span = $set->closest( $dt );
173
174           This method is used to find the "closest" span in the set, given a
175           datetime or span.
176
177           The return value is a "DateTime::SpanSet", or "undef" if the set is
178           empty.
179
180           If a span parameter is given, it may happen that "closest" returns
181           more than one span.
182
183       •   as_list
184
185           Returns a list of "DateTime::Span" objects.
186
187             my @dt_span = $set->as_list( span => $span );
188
189           Just as with the "iterator()" method, the "as_list()" method can be
190           limited by a span.
191
192           Applying "as_list()" to a large recurring spanset is a very
193           expensive operation, both in CPU time and in the memory used.
194
195           For this reason, when "as_list()" operates on large recurrence
196           sets, it will return at most approximately 200 spans. For larger
197           sets, and for infinite sets, "as_list()" will return "undef".
198
199           Please note that this is explicitly not an empty list, since an
200           empty list is a valid return value for empty sets!
201
202           If you really need to extract spans from a large set, you can:
203
204           - limit the set with a shorter span:
205
206               my @short_list = $large_set->as_list( span => $short_span );
207
208           - use an iterator:
209
210               my @large_list;
211               my $iter = $large_set->iterator;
212               push @large_list, $dt while $dt = $iter->next;
213
214       •   union
215
216       •   intersection
217
218       •   complement
219
220           Set operations may be performed not only with "DateTime::SpanSet"
221           objects, but also with "DateTime", "DateTime::Set" and
222           "DateTime::Span" objects.  These set operations always return a
223           "DateTime::SpanSet" object.
224
225               $set = $spanset->union( $set2 );         # like "OR", "insert", "both"
226               $set = $spanset->complement( $set2 );    # like "delete", "remove"
227               $set = $spanset->intersection( $set2 );  # like "AND", "while"
228               $set = $spanset->complement;             # like "NOT", "negate", "invert"
229
230       •   intersected_spans
231
232           This method can accept a "DateTime" list, a "DateTime::Set", a
233           "DateTime::Span", or a "DateTime::SpanSet" object as an argument.
234
235               $set = $set1->intersected_spans( $set2 );
236
237           The method always returns a "DateTime::SpanSet" object, containing
238           all spans that are intersected by the given set.
239
240           Unlike the "intersection" method, the spans are not modified.  See
241           diagram below:
242
243                          set1   [....]   [....]   [....]   [....]
244                          set2      [................]
245
246                  intersection      [.]   [....]   [.]
247
248             intersected_spans   [....]   [....]   [....]
249
250       •   intersects
251
252       •   contains
253
254           These set functions return a boolean value.
255
256               if ( $spanset->intersects( $set2 ) ) { ...  # like "touches", "interferes"
257               if ( $spanset->contains( $dt ) ) { ...    # like "is-fully-inside"
258
259           These methods can accept a "DateTime", "DateTime::Set",
260           "DateTime::Span", or "DateTime::SpanSet" object as an argument.
261
262           intersects() returns 1 for true, and 0 for false. In a few cases
263           the algorithm can't decide if the sets intersect at all, and
264           intersects() will return "undef".
265
266       •   iterator / next / previous
267
268           This method can be used to iterate over the spans in a set.
269
270               $iter = $spanset->iterator;
271               while ( $dt = $iter->next ) {
272                   # $dt is a DateTime::Span
273                   print $dt->min->ymd;   # first date of span
274                   print $dt->max->ymd;   # last date of span
275               }
276
277           The boundaries of the iterator can be limited by passing it a
278           "span" parameter.  This should be a "DateTime::Span" object which
279           delimits the iterator's boundaries.  Optionally, instead of passing
280           an object, you can pass any parameters that would work for one of
281           the "DateTime::Span" class's constructors, and an object will be
282           created for you.
283
284           Obviously, if the span you specify does is not restricted both at
285           the start and end, then your iterator may iterate forever,
286           depending on the nature of your set.  User beware!
287
288           The "next()" or "previous()" methods will return "undef" when there
289           are no more spans in the iterator.
290
291       •   start_set
292
293       •   end_set
294
295           These methods do the inverse of the "from_sets" method:
296
297           "start_set" retrieves a DateTime::Set with the start datetime of
298           each span.
299
300           "end_set" retrieves a DateTime::Set with the end datetime of each
301           span.
302
303       •   map ( sub { ... } )
304
305               # example: enlarge the spans
306               $set = $set2->map(
307                   sub {
308                       my $start = $_->start;
309                       my $end = $_->end;
310                       return DateTime::Span->from_datetimes(
311                           start => $start,
312                           before => $end,
313                       );
314                   }
315               );
316
317           This method is the "set" version of Perl "map".
318
319           It evaluates a subroutine for each element of the set (locally
320           setting "$_" to each DateTime::Span) and returns the set composed
321           of the results of each such evaluation.
322
323           Like Perl "map", each element of the set may produce zero, one, or
324           more elements in the returned value.
325
326           Unlike Perl "map", changing "$_" does not change the original set.
327           This means that calling map in void context has no effect.
328
329           The callback subroutine may not be called immediately.  Don't count
330           on subroutine side-effects. For example, a "print" inside the
331           subroutine may happen later than you expect.
332
333           The callback return value is expected to be within the span of the
334           "previous" and the "next" element in the original set.
335
336           For example: given the set "[ 2001, 2010, 2015 ]", the callback
337           result for the value 2010 is expected to be within the span "[ 2001
338           .. 2015 ]".
339
340       •   grep ( sub { ... } )
341
342               # example: filter out all spans happening today
343               my $today = DateTime->today;
344               $set = $set2->grep(
345                   sub {
346                       return ( ! $_->contains( $today ) );
347                   }
348               );
349
350           This method is the "set" version of Perl "grep".
351
352           It evaluates a subroutine for each element of the set (locally
353           setting "$_" to each DateTime::Span) and returns the set consisting
354           of those elements for which the expression evaluated to true.
355
356           Unlike Perl "grep", changing "$_" does not change the original set.
357           This means that calling grep in void context has no effect.
358
359           Changing "$_" does change the resulting set.
360
361           The callback subroutine may not be called immediately.  Don't count
362           on subroutine side-effects. For example, a "print" inside the
363           subroutine may happen later than you expect.
364
365       •   iterate
366
367           Internal method - use "map" or "grep" instead.
368
369           This function apply a callback subroutine to all elements of a set
370           and returns the resulting set.
371
372           The parameter $_[0] to the callback subroutine is a
373           "DateTime::Span" object.
374
375           If the callback returns "undef", the datetime is removed from the
376           set:
377
378               sub remove_sundays {
379                   $_[0] unless $_[0]->start->day_of_week == 7;
380               }
381
382           The callback return value is expected to be within the span of the
383           "previous" and the "next" element in the original set.
384
385           For example: given the set "[ 2001, 2010, 2015 ]", the callback
386           result for the value 2010 is expected to be within the span "[ 2001
387           .. 2015 ]".
388
389           The callback subroutine may not be called immediately.  Don't count
390           on subroutine side-effects. For example, a "print" inside the
391           subroutine may happen later than you expect.
392

SUPPORT

394       Support is offered through the "datetime@perl.org" mailing list.
395
396       Please report bugs using rt.cpan.org
397

AUTHOR

399       Flavio Soibelmann Glock <fglock@gmail.com>
400
401       The API was developed together with Dave Rolsky and the DateTime
402       Community.
403

COPYRIGHT

405       Copyright (c) 2003 Flavio Soibelmann Glock. All rights reserved.  This
406       program is free software; you can distribute it and/or modify it under
407       the same terms as Perl itself.
408
409       The full text of the license can be found in the LICENSE file included
410       with this module.
411