DateTime::Span(3pm)

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 date/time spans or time-ranges.
31

METHODS

33       * from_datetimes
34           Creates a new span based on a starting and ending datetime.
35
36           A 'closed' span includes its end-dates:
37
38              $span = DateTime::Span->from_datetimes( start => $dt1, end => $dt2 );
39
40           An 'open' span does not include its end-dates:
41
42              $span = DateTime::Span->from_datetimes( after => $dt1, before => $dt2 );
43
44           A 'semi-open' span includes one of its end-dates:
45
46              $span = DateTime::Span->from_datetimes( start => $dt1, before => $dt2 );
47              $span = DateTime::Span->from_datetimes( after => $dt1, end => $dt2 );
48
49           A span might have just a beginning date, or just an ending date.
50           These spans end, or start, in an imaginary 'forever' date:
51
52              $span = DateTime::Span->from_datetimes( start => $dt1 );
53              $span = DateTime::Span->from_datetimes( end => $dt2 );
54              $span = DateTime::Span->from_datetimes( after => $dt1 );
55              $span = DateTime::Span->from_datetimes( before => $dt2 );
56
57           You cannot give both a "start" and "after" argument, nor can you
58           give both an "end" and "before" argument.  Either of these condi‐
59           tions will cause the "from_datetimes()" method to die.
60
61       * from_datetime_and_duration
62           Creates a new span.
63
64              $span = DateTime::Span->from_datetime_and_duration(
65                  start => $dt1, duration => $dt_dur1 );
66              $span = DateTime::Span->from_datetime_and_duration(
67                  after => $dt1, hours => 12 );
68
69           The new "end of the set" is open by default.
70
71       * clone
72           This object method returns a replica of the given object.
73
74       * set_time_zone( $tz )
75           This method accepts either a time zone object or a string that can
76           be passed as the "name" parameter to "DateTime::TimeZone->new()".
77           If the new time zone's offset is different from the old time zone,
78           then the local time is adjusted accordingly.
79
80           If the old time zone was a floating time zone, then no adjustments
81           to the local time are made, except to account for leap seconds.  If
82           the new time zone is floating, then the UTC time is adjusted in
83           order to leave the local time untouched.
84
85       * duration
86           The total size of the set, as a "DateTime::Duration" object, or as
87           a scalar containing infinity.
88
89           Also available as "size()".
90
91       * start
92       * end
93           First or last dates in the span.
94
95           It is possible that the return value from these methods may be a
96           DateTime::Infinite::Future or a DateTime::Infinite::Past object.
97
98           If the set ends "before" a date $dt, it returns $dt. Note that in
99           this case $dt is not a set element - but it is a set boundary.
100
101       * start_is_closed
102       * end_is_closed
103           Returns true if the first or last dates belong to the span ( begin
104           <= x <= end ).
105
106       * start_is_open
107       * end_is_open
108           Returns true if the first or last dates are excluded from the span
109           ( begin < x < end ).
110
111       * union
112       * intersection
113       * complement
114           Set operations may be performed not only with "DateTime::Span"
115           objects, but also with "DateTime::Set" and "DateTime::SpanSet"
116           objects.  These set operations always return a "DateTime::SpanSet"
117           object.
118
119               $set = $span->union( $set2 );         # like "OR", "insert", "both"
120               $set = $span->complement( $set2 );    # like "delete", "remove"
121               $set = $span->intersection( $set2 );  # like "AND", "while"
122               $set = $span->complement;             # like "NOT", "negate", "invert"
123
124       * intersects
125       * contains
126           These set functions return a boolean value.
127
128               if ( $span->intersects( $set2 ) ) { ...  # like "touches", "interferes"
129               if ( $span->contains( $dt ) ) { ...    # like "is-fully-inside"
130
131           These methods can accept a "DateTime", "DateTime::Set", "Date‐
132           Time::Span", or "DateTime::SpanSet" object as an argument.
133

SUPPORT

135       Support is offered through the "datetime@perl.org" mailing list.
136
137       Please report bugs using rt.cpan.org
138

AUTHOR

140       Flavio Soibelmann Glock <fglock@pucrs.br>
141
142       The API was developed together with Dave Rolsky and the DateTime Commu‐
143       nity.
144

COPYRIGHT

146       Copyright (c) 2003 Flavio Soibelmann Glock. All rights reserved.  This
147       program is free software; you can distribute it and/or modify it under
148       the same terms as Perl itself.
149
150       The full text of the license can be found in the LICENSE file included
151       with this module.
152