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

SUPPORT

374       Support is offered through the "datetime@perl.org" mailing list.
375
376       Please report bugs using rt.cpan.org
377

AUTHOR

379       Flavio Soibelmann Glock <fglock@pucrs.br>
380
381       The API was developed together with Dave Rolsky and the DateTime
382       Community.
383

COPYRIGHT

385       Copyright (c) 2003 Flavio Soibelmann Glock. All rights reserved.  This
386       program is free software; you can distribute it and/or modify it under
387       the same terms as Perl itself.
388
389       The full text of the license can be found in the LICENSE file included
390       with this module.
391