1DateTime::Span(3) User Contributed Perl Documentation DateTime::Span(3)
2
6 DateTime::Span - Datetime spans
7
9 use DateTime;
10 use DateTime::Span;
11 $date1 = DateTime->new( year => 2002, month => 3, day => 11 );
13 $date2 = DateTime->new( year => 2003, month => 4, day => 12 );
14 $set2 = DateTime::Span->from_datetimes( start => $date1, end => $date2 );
15 # set2 = 2002-03-11 until 2003-04-12
16 $set = $set1->union( $set2 ); # like "OR", "insert", "both"
18 $set = $set1->complement( $set2 ); # like "delete", "remove"
19 $set = $set1->intersection( $set2 ); # like "AND", "while"
20 $set = $set1->complement; # like "NOT", "negate", "invert"
21 if ( $set1->intersects( $set2 ) ) { ... # like "touches", "interferes"
23 if ( $set1->contains( $set2 ) ) { ... # like "is-fully-inside"
24 # data extraction
26 $date = $set1->start; # first date of the span
27 $date = $set1->end; # last date of the span
28
30 "DateTime::Span" is a module for handling datetime spans, otherwise
31 known as ranges or periods ("from X to Y, inclusive of all datetimes in
32 between").
33 This is different from a "DateTime::Set", which is made of individual
35 datetime points as opposed to a range. There is also a module
36 "DateTime::SpanSet" to handle sets of spans.
37
39 · from_datetimes
40 Creates a new span based on a starting and ending datetime.
42 A 'closed' span includes its end-dates:
44 $span = DateTime::Span->from_datetimes( start => $dt1, end => $dt2 );
46 An 'open' span does not include its end-dates:
48 $span = DateTime::Span->from_datetimes( after => $dt1, before => $dt2 );
50 A 'semi-open' span includes one of its end-dates:
52 $span = DateTime::Span->from_datetimes( start => $dt1, before => $dt2 );
54 $span = DateTime::Span->from_datetimes( after => $dt1, end => $dt2 );
55 A span might have just a starting date, or just an ending date.
57 These spans end, or start, in an imaginary 'forever' date:
58 $span = DateTime::Span->from_datetimes( start => $dt1 );
60 $span = DateTime::Span->from_datetimes( end => $dt2 );
61 $span = DateTime::Span->from_datetimes( after => $dt1 );
62 $span = DateTime::Span->from_datetimes( before => $dt2 );
63 You cannot give both a "start" and "after" argument, nor can you
65 give both an "end" and "before" argument. Either of these
66 conditions will cause the "from_datetimes()" method to die.
67 To summarize, a datetime passed as either "start" or "end" is
69 included in the span. A datetime passed as either "after" or
70 "before" is excluded from the span.
71 · from_datetime_and_duration
73 Creates a new span.
75 $span = DateTime::Span->from_datetime_and_duration(
77 start => $dt1, duration => $dt_dur1 );
78 $span = DateTime::Span->from_datetime_and_duration(
79 after => $dt1, hours => 12 );
80 The new "end of the set" is open by default.
82 · clone
84 This object method returns a replica of the given object.
86 · set_time_zone( $tz )
88 This method accepts either a time zone object or a string that can
90 be passed as the "name" parameter to "DateTime::TimeZone->new()".
91 If the new time zone's offset is different from the old time zone,
92 then the local time is adjusted accordingly.
93 If the old time zone was a floating time zone, then no adjustments
95 to the local time are made, except to account for leap seconds. If
96 the new time zone is floating, then the UTC time is adjusted in
97 order to leave the local time untouched.
98 · duration
100 The total size of the set, as a "DateTime::Duration" object, or as
102 a scalar containing infinity.
103 Also available as "size()".
105 · start, min
107 · end, max
109 First or last dates in the span.
111 It is possible that the return value from these methods may be a
113 "DateTime::Infinite::Future" or a "DateTime::Infinite::Past"xs
114 object.
115 If the set ends "before" a date $dt, it returns $dt. Note that in
117 this case $dt is not a set element - but it is a set boundary.
118 These methods return just a copy of the actual boundary value. If
120 you modify the result, the set will not be modified.
121 · start_is_closed
123 · end_is_closed
125 Returns true if the first or last dates belong to the span ( start
127 <= x <= end ).
128 · start_is_open
130 · end_is_open
132 Returns true if the first or last dates are excluded from the span
134 ( start < x < end ).
135 · union
137 · intersection
139 · complement
141 Set operations may be performed not only with "DateTime::Span"
143 objects, but also with "DateTime::Set" and "DateTime::SpanSet"
144 objects. These set operations always return a "DateTime::SpanSet"
145 object.
146 $set = $span->union( $set2 ); # like "OR", "insert", "both"
148 $set = $span->complement( $set2 ); # like "delete", "remove"
149 $set = $span->intersection( $set2 ); # like "AND", "while"
150 $set = $span->complement; # like "NOT", "negate", "invert"
151 · intersects
153 · contains
155 These set functions return a boolean value.
157 if ( $span->intersects( $set2 ) ) { ... # like "touches", "interferes"
159 if ( $span->contains( $dt ) ) { ... # like "is-fully-inside"
160 These methods can accept a "DateTime", "DateTime::Set",
162 "DateTime::Span", or "DateTime::SpanSet" object as an argument.
163
165 Support is offered through the "datetime@perl.org" mailing list.
166 Please report bugs using rt.cpan.org
168
170 Flavio Soibelmann Glock <fglock@gmail.com>
171 The API was developed together with Dave Rolsky and the DateTime
173 Community.
174
176 Copyright (c) 2003-2006 Flavio Soibelmann Glock. All rights reserved.
177 This program is free software; you can distribute it and/or modify it
178 under the same terms as Perl itself.
179 The full text of the license can be found in the LICENSE file included
181 with this module.
182
184 Set::Infinite
185 For details on the Perl DateTime Suite project please see
187 <http://datetime.perl.org>.
188perl v5.32.0 2020-07-28 DateTime::Span(3)