1DateTime::SpanSet(3) User Contributed Perl Documentation DateTime::SpanSet(3)
2
6 DateTime::SpanSet - set of DateTime spans
7
9 $spanset = DateTime::SpanSet->from_spans( spans => [ $dt_span, $dt_span ] );
10 $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 if ( $spanset->intersects( $set2 ) ) { ... # like "touches", "interferes"
17 if ( $spanset->contains( $set2 ) ) { ... # like "is-fully-inside"
18 # data extraction
20 $date = $spanset->min; # first date of the set
21 $date = $spanset->max; # last date of the set
22 $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
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
36 * from_spans
37 Creates a new span set from one or more "DateTime::Span" objects.
38 $spanset = DateTime::SpanSet->from_spans( spans => [ $dt_span ] );
40 * from_set_and_duration
42 Creates a new span set from one or more "DateTime::Set" objects and
43 a duration.
44 The duration can be a "DateTime::Duration" object, or the parame‐
46 ters to create a new "DateTime::Duration" object, such as "days",
47 "months", etc.
48 $spanset =
50 DateTime::SpanSet->from_set_and_duration
51 ( set => $dt_set, days => 1 );
52 * from_sets
54 Creates a new span set from two "DateTime::Set" objects.
55 One set defines the starting dates, and the other defines the end
57 dates.
58 $spanset =
60 DateTime::SpanSet->from_sets
61 ( start_set => $dt_set1, end_set => $dt_set2 );
62 The spans have the starting date "closed", and the end date "open",
64 like in "[$dt1, $dt2)".
65 If an end date comes without a starting date before it, then it
67 defines a span like "(-inf, $dt)".
68 If a starting date comes without an end date after it, then it
70 defines a span like "[$dt, inf)".
71 * empty_set
73 Creates a new empty set.
74 * clone
76 This object method returns a replica of the given object.
77 * set_time_zone( $tz )
79 This method accepts either a time zone object or a string that can
80 be passed as the "name" parameter to "DateTime::TimeZone->new()".
81 If the new time zone's offset is different from the old time zone,
82 then the local time is adjusted accordingly.
83 If the old time zone was a floating time zone, then no adjustments
85 to the local time are made, except to account for leap seconds. If
86 the new time zone is floating, then the UTC time is adjusted in
87 order to leave the local time untouched.
88 * min
90 * max
91 First or last dates in the set. These methods may return "undef"
92 if the set is empty. It is also possible that these methods may
93 return a scalar containing infinity or negative infinity.
94 * duration
96 The total size of the set, as a "DateTime::Duration" object.
97 The duration may be infinite.
99 Also available as "size()".
101 * span
103 The total span of the set, as a "DateTime::Span" object.
104 * next
106 my $span = $set->next( $dt );
107 This method is used to find the next span in the set, after a given
109 datetime or span.
110 The return value is a "DateTime::Span", or "undef" if there is no
112 matching span in the set.
113 * previous
115 my $span = $set->previous( $dt );
116 This method is used to find the previous span in the set, before a
118 given datetime or span.
119 The return value is a "DateTime::Span", or "undef" if there is no
121 matching span in the set.
122 * current
124 my $span = $set->current( $dt );
125 This method is used to find the "current" span in the set, that
127 intersects a given datetime or span. If no current span is found,
128 then the "previous" span is returned.
129 The return value is a "DateTime::SpanSet", or "undef" if there is
131 no matching span in the set.
132 If a span parameter is given, it may happen that "current" returns
134 more than one span.
135 See also: "intersected_spans()" method.
137 * closest
139 my $span = $set->closest( $dt );
140 This method is used to find the "closest" span in the set, given a
142 datetime or span.
143 The return value is a "DateTime::SpanSet", or "undef" if the set is
145 empty.
146 If a span parameter is given, it may happen that "closest" returns
148 more than one span.
149 * as_list
151 Returns a list of "DateTime::Span" objects.
152 my @dt_span = $set->as_list( span => $span );
154 Just as with the "iterator()" method, the "as_list()" method can be
156 limited by a span.
157 Applying "as_list()" to a large recurring spanset is a very expen‐
159 sive operation, both in CPU time and in the memory used.
160 For this reason, when "as_list()" operates on large recurrence
162 sets, it will return at most approximately 200 spans. For larger
163 sets, and for infinite sets, "as_list()" will return "undef".
164 Please note that this is explicitly not an empty list, since an
166 empty list is a valid return value for empty sets!
167 If you really need to extract spans from a large set, you can:
169 - limit the set with a shorter span:
171 my @short_list = $large_set->as_list( span => $short_span );
173 - use an iterator:
175 my @large_list;
177 my $iter = $large_set->iterator;
178 push @large_list, $dt while $dt = $iter->next;
179 * union
181 * intersection
182 * complement
183 Set operations may be performed not only with "DateTime::SpanSet"
184 objects, but also with "DateTime", "DateTime::Set" and "Date‐
185 Time::Span" objects. These set operations always return a "Date‐
186 Time::SpanSet" object.
187 $set = $spanset->union( $set2 ); # like "OR", "insert", "both"
189 $set = $spanset->complement( $set2 ); # like "delete", "remove"
190 $set = $spanset->intersection( $set2 ); # like "AND", "while"
191 $set = $spanset->complement; # like "NOT", "negate", "invert"
192 * intersected_spans
194 This method can accept a "DateTime" list, a "DateTime::Set", a
195 "DateTime::Span", or a "DateTime::SpanSet" object as an argument.
196 $set = $set1->intersected_spans( $set2 );
198 The method always returns a "DateTime::SpanSet" object, containing
200 all spans that are intersected by the given set.
201 Unlike the "intersection" method, the spans are not modified. See
203 diagram below:
204 set1 [....] [....] [....] [....]
206 set2 [................]
207 intersection [.] [....] [.]
209 intersected_spans [....] [....] [....]
211 * intersects
213 * contains
214 These set functions return a boolean value.
215 if ( $spanset->intersects( $set2 ) ) { ... # like "touches", "interferes"
217 if ( $spanset->contains( $dt ) ) { ... # like "is-fully-inside"
218 These methods can accept a "DateTime", "DateTime::Set", "Date‐
220 Time::Span", or "DateTime::SpanSet" object as an argument.
221 * iterator / next / previous
223 This method can be used to iterate over the spans in a set.
224 $iter = $spanset->iterator;
226 while ( $dt = $iter->next ) {
227 # $dt is a DateTime::Span
228 print $dt->min->ymd; # first date of span
229 print $dt->max->ymd; # last date of span
230 }
231 The boundaries of the iterator can be limited by passing it a
233 "span" parameter. This should be a "DateTime::Span" object which
234 delimits the iterator's boundaries. Optionally, instead of passing
235 an object, you can pass any parameters that would work for one of
236 the "DateTime::Span" class's constructors, and an object will be
237 created for you.
238 Obviously, if the span you specify does is not restricted both at
240 the start and end, then your iterator may iterate forever, depend‐
241 ing on the nature of your set. User beware!
242 The "next()" or "previous()" methods will return "undef" when there
244 are no more spans in the iterator.
245 * start_set
247 * end_set
248 These methods do the inverse of the "from_sets" method:
249 "start_set" retrieves a DateTime::Set with the start datetime of
251 each span.
252 "end_set" retrieves a DateTime::Set with the end datetime of each
254 span.
255 * map ( sub { ... } )
257 # example: enlarge the spans
258 $set = $set2->map(
259 sub {
260 my $start = $_->start;
261 my $end = $_->end;
262 return DateTime::Span->from_datetimes(
263 start => $start,
264 before => $end,
265 );
266 }
267 );
268 This method is the "set" version of Perl "map".
270 It evaluates a subroutine for each element of the set (locally set‐
272 ting "$_" to each DateTime::Span) and returns the set composed of
273 the results of each such evaluation.
274 Like Perl "map", each element of the set may produce zero, one, or
276 more elements in the returned value.
277 Unlike Perl "map", changing "$_" does not change the original set.
279 This means that calling map in void context has no effect.
280 The callback subroutine may not be called immediately. Don't count
282 on subroutine side-effects. For example, a "print" inside the sub‐
283 routine may happen later than you expect.
284 The callback return value is expected to be within the span of the
286 "previous" and the "next" element in the original set.
287 For example: given the set "[ 2001, 2010, 2015 ]", the callback
289 result for the value 2010 is expected to be within the span "[ 2001
290 .. 2015 ]".
291 * grep ( sub { ... } )
293 # example: filter out all spans happening today
294 my $today = DateTime->today;
295 $set = $set2->grep(
296 sub {
297 return ( ! $_->contains( $today ) );
298 }
299 );
300 This method is the "set" version of Perl "grep".
302 It evaluates a subroutine for each element of the set (locally set‐
304 ting "$_" to each DateTime::Span) and returns the set consisting of
305 those elements for which the expression evaluated to true.
306 Unlike Perl "grep", changing "$_" does not change the original set.
308 This means that calling grep in void context has no effect.
309 Changing "$_" does change the resulting set.
311 The callback subroutine may not be called immediately. Don't count
313 on subroutine side-effects. For example, a "print" inside the sub‐
314 routine may happen later than you expect.
315 * iterate
317 Internal method - use "map" or "grep" instead.
318 This function apply a callback subroutine to all elements of a set
320 and returns the resulting set.
321 The parameter $_[0] to the callback subroutine is a "Date‐
323 Time::Span" object.
324 If the callback returns "undef", the datetime is removed from the
326 set:
327 sub remove_sundays {
329 $_[0] unless $_[0]->start->day_of_week == 7;
330 }
331 The callback return value is expected to be within the span of the
333 "previous" and the "next" element in the original set.
334 For example: given the set "[ 2001, 2010, 2015 ]", the callback
336 result for the value 2010 is expected to be within the span "[ 2001
337 .. 2015 ]".
338 The callback subroutine may not be called immediately. Don't count
340 on subroutine side-effects. For example, a "print" inside the sub‐
341 routine may happen later than you expect.
342
344 Support is offered through the "datetime@perl.org" mailing list.
345 Please report bugs using rt.cpan.org
347
349 Flavio Soibelmann Glock <fglock@pucrs.br>
350 The API was developed together with Dave Rolsky and the DateTime Commu‐
352 nity.
353
355 Copyright (c) 2003 Flavio Soibelmann Glock. All rights reserved. This
356 program is free software; you can distribute it and/or modify it under
357 the same terms as Perl itself.
358 The full text of the license can be found in the LICENSE file included
360 with this module.
361
363 Set::Infinite
364 For details on the Perl DateTime Suite project please see <http://date‐
366 time.perl.org>.
367perl v5.8.8 2007-04-17 DateTime::SpanSet(3)