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

NAME

6       DateTime::Span - Datetime spans
7

SYNOPSIS

9           use DateTime;
10           use DateTime::Span;
11
12           $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
17           $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
22           if ( $set1->intersects( $set2 ) ) { ...  # like "touches", "interferes"
23           if ( $set1->contains( $set2 ) ) { ...    # like "is-fully-inside"
24
25           # data extraction
26           $date = $set1->start;           # first date of the span
27           $date = $set1->end;             # last date of the span
28

DESCRIPTION

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
34       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

METHODS

39       ·   from_datetimes
40
41           Creates a new span based on a starting and ending datetime.
42
43           A 'closed' span includes its end-dates:
44
45              $span = DateTime::Span->from_datetimes( start => $dt1, end => $dt2 );
46
47           An 'open' span does not include its end-dates:
48
49              $span = DateTime::Span->from_datetimes( after => $dt1, before => $dt2 );
50
51           A 'semi-open' span includes one of its end-dates:
52
53              $span = DateTime::Span->from_datetimes( start => $dt1, before => $dt2 );
54              $span = DateTime::Span->from_datetimes( after => $dt1, end => $dt2 );
55
56           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
59              $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
64           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
68           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
72       ·   from_datetime_and_duration
73
74           Creates a new span.
75
76              $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
81           The new "end of the set" is open by default.
82
83       ·   clone
84
85           This object method returns a replica of the given object.
86
87       ·   set_time_zone( $tz )
88
89           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
94           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
99       ·   duration
100
101           The total size of the set, as a "DateTime::Duration" object, or as
102           a scalar containing infinity.
103
104           Also available as "size()".
105
106       ·   start, min
107
108       ·   end, max
109
110           First or last dates in the span.
111
112           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
116           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
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       ·   start_is_closed
123
124       ·   end_is_closed
125
126           Returns true if the first or last dates belong to the span ( start
127           <= x <= end ).
128
129       ·   start_is_open
130
131       ·   end_is_open
132
133           Returns true if the first or last dates are excluded from the span
134           ( start < x < end ).
135
136       ·   union
137
138       ·   intersection
139
140       ·   complement
141
142           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
147               $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
152       ·   intersects
153
154       ·   contains
155
156           These set functions return a boolean value.
157
158               if ( $span->intersects( $set2 ) ) { ...  # like "touches", "interferes"
159               if ( $span->contains( $dt ) ) { ...    # like "is-fully-inside"
160
161           These methods can accept a "DateTime", "DateTime::Set",
162           "DateTime::Span", or "DateTime::SpanSet" object as an argument.
163

SUPPORT

165       Support is offered through the "datetime@perl.org" mailing list.
166
167       Please report bugs using rt.cpan.org
168

AUTHOR

170       Flavio Soibelmann Glock <fglock@gmail.com>
171
172       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
180       The full text of the license can be found in the LICENSE file included
181       with this module.
182

SEE ALSO

184       Set::Infinite
185
186       For details on the Perl DateTime Suite project please see
187       <http://datetime.perl.org>.
188
189
190
191perl v5.32.0                      2020-07-28                 DateTime::Span(3)
Impressum