.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "DateTime::Span 3" .TH DateTime::Span 3 2024-07-13 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME DateTime::Span \- Datetime spans .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 2 \& use DateTime; \& use DateTime::Span; \& \& $date1 = DateTime\->new( year => 2002, month => 3, day => 11 ); \& $date2 = DateTime\->new( year => 2003, month => 4, day => 12 ); \& $set2 = DateTime::Span\->from_datetimes( start => $date1, end => $date2 ); \& # set2 = 2002\-03\-11 until 2003\-04\-12 \& \& $set = $set1\->union( $set2 ); # like "OR", "insert", "both" \& $set = $set1\->complement( $set2 ); # like "delete", "remove" \& $set = $set1\->intersection( $set2 ); # like "AND", "while" \& $set = $set1\->complement; # like "NOT", "negate", "invert" \& \& if ( $set1\->intersects( $set2 ) ) { ... # like "touches", "interferes" \& if ( $set1\->contains( $set2 ) ) { ... # like "is\-fully\-inside" \& \& # data extraction \& $date = $set1\->start; # first date of the span \& $date = $set1\->end; # last date of the span .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" \&\f(CW\*(C`DateTime::Span\*(C'\fR is a module for handling datetime spans, otherwise known as ranges or periods ("from X to Y, inclusive of all datetimes in between"). .PP This is different from a \f(CW\*(C`DateTime::Set\*(C'\fR, which is made of individual datetime points as opposed to a range. There is also a module \&\f(CW\*(C`DateTime::SpanSet\*(C'\fR to handle sets of spans. .SH METHODS .IX Header "METHODS" .IP \(bu 4 from_datetimes .Sp Creates a new span based on a starting and ending datetime. .Sp A 'closed' span includes its end-dates: .Sp .Vb 1 \& $span = DateTime::Span\->from_datetimes( start => $dt1, end => $dt2 ); .Ve .Sp An 'open' span does not include its end-dates: .Sp .Vb 1 \& $span = DateTime::Span\->from_datetimes( after => $dt1, before => $dt2 ); .Ve .Sp A 'semi\-open' span includes one of its end-dates: .Sp .Vb 2 \& $span = DateTime::Span\->from_datetimes( start => $dt1, before => $dt2 ); \& $span = DateTime::Span\->from_datetimes( after => $dt1, end => $dt2 ); .Ve .Sp A span might have just a starting date, or just an ending date. These spans end, or start, in an imaginary 'forever' date: .Sp .Vb 4 \& $span = DateTime::Span\->from_datetimes( start => $dt1 ); \& $span = DateTime::Span\->from_datetimes( end => $dt2 ); \& $span = DateTime::Span\->from_datetimes( after => $dt1 ); \& $span = DateTime::Span\->from_datetimes( before => $dt2 ); .Ve .Sp You cannot give both a "start" and "after" argument, nor can you give both an "end" and "before" argument. Either of these conditions will cause the \f(CWfrom_datetimes()\fR method to die. .Sp To summarize, a datetime passed as either "start" or "end" is included in the span. A datetime passed as either "after" or "before" is excluded from the span. .IP \(bu 4 from_datetime_and_duration .Sp Creates a new span. .Sp .Vb 4 \& $span = DateTime::Span\->from_datetime_and_duration( \& start => $dt1, duration => $dt_dur1 ); \& $span = DateTime::Span\->from_datetime_and_duration( \& after => $dt1, hours => 12 ); .Ve .Sp The new "end of the set" is \fIopen\fR by default. .IP \(bu 4 clone .Sp This object method returns a replica of the given object. .IP \(bu 4 set_time_zone( \f(CW$tz\fR ) .Sp This method accepts either a time zone object or a string that can be passed as the "name" parameter to \f(CW\*(C`DateTime::TimeZone\->new()\*(C'\fR. If the new time zone's offset is different from the old time zone, then the \fIlocal\fR time is adjusted accordingly. .Sp If the old time zone was a floating time zone, then no adjustments to the local time are made, except to account for leap seconds. If the new time zone is floating, then the \fIUTC\fR time is adjusted in order to leave the local time untouched. .IP \(bu 4 duration .Sp The total size of the set, as a \f(CW\*(C`DateTime::Duration\*(C'\fR object, or as a scalar containing infinity. .Sp Also available as \f(CWsize()\fR. .IP \(bu 4 start, min .IP \(bu 4 end, max .Sp First or last dates in the span. .Sp It is possible that the return value from these methods may be a \&\f(CW\*(C`DateTime::Infinite::Future\*(C'\fR or a \f(CW\*(C`DateTime::Infinite::Past\*(C'\fRxs object. .Sp If the set ends \f(CW\*(C`before\*(C'\fR a date \f(CW$dt\fR, it returns \f(CW$dt\fR. Note that in this case \f(CW$dt\fR is not a set element \- but it is a set boundary. .Sp These methods return just a \fIcopy\fR of the actual boundary value. If you modify the result, the set will not be modified. .IP \(bu 4 start_is_closed .IP \(bu 4 end_is_closed .Sp Returns true if the first or last dates belong to the span ( start <= x <= end ). .IP \(bu 4 start_is_open .IP \(bu 4 end_is_open .Sp Returns true if the first or last dates are excluded from the span ( start < x < end ). .IP \(bu 4 union .IP \(bu 4 intersection .IP \(bu 4 complement .Sp Set operations may be performed not only with \f(CW\*(C`DateTime::Span\*(C'\fR objects, but also with \f(CW\*(C`DateTime::Set\*(C'\fR and \f(CW\*(C`DateTime::SpanSet\*(C'\fR objects. These set operations always return a \f(CW\*(C`DateTime::SpanSet\*(C'\fR object. .Sp .Vb 4 \& $set = $span\->union( $set2 ); # like "OR", "insert", "both" \& $set = $span\->complement( $set2 ); # like "delete", "remove" \& $set = $span\->intersection( $set2 ); # like "AND", "while" \& $set = $span\->complement; # like "NOT", "negate", "invert" .Ve .IP \(bu 4 intersects .IP \(bu 4 contains .Sp These set functions return a boolean value. .Sp .Vb 2 \& if ( $span\->intersects( $set2 ) ) { ... # like "touches", "interferes" \& if ( $span\->contains( $dt ) ) { ... # like "is\-fully\-inside" .Ve .Sp These methods can accept a \f(CW\*(C`DateTime\*(C'\fR, \f(CW\*(C`DateTime::Set\*(C'\fR, \&\f(CW\*(C`DateTime::Span\*(C'\fR, or \f(CW\*(C`DateTime::SpanSet\*(C'\fR object as an argument. .SH SUPPORT .IX Header "SUPPORT" Support is offered through the \f(CW\*(C`datetime@perl.org\*(C'\fR mailing list. .PP Please report bugs using rt.cpan.org .SH AUTHOR .IX Header "AUTHOR" Flavio Soibelmann Glock .PP The API was developed together with Dave Rolsky and the DateTime Community. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright (c) 2003\-2006 Flavio Soibelmann Glock. All rights reserved. This program is free software; you can distribute it and/or modify it under the same terms as Perl itself. .PP The full text of the license can be found in the LICENSE file included with this module. .SH "SEE ALSO" .IX Header "SEE ALSO" Set::Infinite .PP For details on the Perl DateTime Suite project please see .