.\" Automatically generated by Pod::Man 4.14 (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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 "Data::ICal::DateTime 3pm" .TH Data::ICal::DateTime 3pm "2022-11-19" "perl v5.36.0" "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" Data::ICal::DateTime \- convenience methods for using Data::ICal with DateTime .SH "SYNPOSIS" .IX Header "SYNPOSIS" .Vb 3 \& # performs mixin voodoo \& use Data::ICal::DateTime; \& my $cal = Data::ICal\->new( filename => \*(Aqexample.ics\*(Aq); \& \& \& my $date1 = DateTime\->new( year => 2005, month => 7, day => 01 ); \& my $date2 = DateTime\->new( year => 2005, month => 7, day => 07 ); \& my $span = DateTime::Span\->from_datetimes( start => $date1, end => $date2 ); \& \& my @events = $cal\->events(); # all VEVENTS \& my @week = $cal\->events($span); # just in that week \& my @week = $cal\->events($span,\*(Aqday\*(Aq);# explode long events into days \& \& my $event = Data::ICal::Entry::Event\->new(); \& \& $event\->start($start); # $start is a DateTime object \& $event\->end($end); # so is $end \& \& $event\->all_day # is this an all day event \& \& $event\->duration($duration); # $duration is DateTime::Duration \& $event\->recurrence($recurrence); # $reccurence is a DateTime list, \& # a DateTime::Span list, \& # a DateTime::Set, \& # or a DateTime::SpanSet \& \& $event\->start; # returns a DateTime object \& $event\->end; # ditto \& $event\->duration; # returns a DateTime::Duration \& $event\->recurrence; # returns a DateTime::Set \& $event\->period; # returns a DateTime::Span object \& $event\->rdate; # returns a DateTime::Set \& $event\->exrule; # returns a DateTime::Set \& $event\->exdate; # returns a DateTime::Set \& $event\->explode($span); # returns an array of sub events \& # (if this is recurring); \& $event\->explode($span,\*(Aqweek\*(Aq); # if any events are longer than a \& # week then split them up \& $event\->is_in($span); # whether this event falls within a \& # Set, Span, or SetSpan \& \& \& $cal\->add_entry($event); .Ve .PP methods .SH "DESCRIPTION" .IX Header "DESCRIPTION" .SH "METHODS" .IX Header "METHODS" .SS "events [span] [period]" .IX Subsection "events [span] [period]" Provides a Data::ICal object with a method to return all events. .PP If a DateTime::Set, DateTime::Span or DateTime::SpanSet object is passed then only the events that occur within that set will be returned including expansion of all recurring events. All events will be normalised to have a dtstart and dtend rather than any other method of determining their start and stop time. .PP Additionally you can pass a period string which can be one of the following .PP .Vb 1 \& year month week day hour minute second .Ve .PP This will explode an event into as many sub events as needed e.g a period of 'day' will explode a 2\-day event into 2 one day events with the second starting just after the first .SS "collapse " .IX Subsection "collapse " Provides a Data::ICal object with a method to collapse \f(CW\*(C`recurrence\-id\*(C'\fRs. .PP Given a list of events, some of which might have \f(CW\*(C`recurrence\-id\*(C'\fRs, return a list of events with all recurrences within \f(CW\*(C`span\*(C'\fR and all \&\f(CW\*(C`recurrence\-id\*(C'\fRs handled correctly. .PP Used internally by \f(CW\*(C`events\*(C'\fR. .SS "start [new]" .IX Subsection "start [new]" Returns a DateTime object representing the start time of this event. .PP May return undef. .PP If passed a DateTime object will set that to be the new start time. .SS "end" .IX Subsection "end" Returns a DateTime object representing the end time of this event. .PP May return undef. .PP If passed a DateTime object will set that to be the new end time. .SS "all_day" .IX Subsection "all_day" Returns 1 if event is all day or 0 if not. .PP If no end has been set and 1 is passed then will set end to be a nanosecond before midnight the next day. .PP The have multi-day all-day events simply set the end time to be nanosecond before midnight on the last day of the event. .SS "floating" .IX Subsection "floating" An event is considered floating if it has a start but no end. It is intended to represent an event that is associated with a given calendar date and time of day, such as an anniversary and should not be considered as taking up any amount of time. .PP Returns 1 if the evnt is floating and 0 if it isn't. .PP If passed a 1 then will set the event to be floating by deleting the end time. .PP If passed a 0 and no end is currently set then it will set end to be a nanosecond before midnight the next day. .SS "duration" .IX Subsection "duration" Returns a DateTime::Duration object representing the duration of this event. .PP May return undef. .PP If passed a DateTime::Duration object will set that to be the new duration. .SS "period" .IX Subsection "period" Returns a DateTime::Span object representing the period of this event. .PP May return undef. .PP If passed a DateTime::Span object will set that to be the new period. .SS "recurrence" .IX Subsection "recurrence" Returns a DateTime::Set object representing the union of all the \&\f(CW\*(C`RRULE\*(C'\fRs in this object. .PP May return undef. .PP If passed one or more DateTime lists, DateTime::Span lists, DateTime::Sets, or DateTime::SpanSets then set the recurrence rules to be those. .SS "rdate" .IX Subsection "rdate" Returns a DateTime::Set object representing the set of all \f(CW\*(C`RDATE\*(C'\fRs in the object. .PP May return undef. .SS "exrule" .IX Subsection "exrule" Returns a DateTime::Set object representing the union of all the \&\f(CW\*(C`EXRULE\*(C'\fRs in this object. .PP May return undef. .PP If passed one or more DateTime lists, DateTime::Span lists, DateTime::Sets, or DateTime::SpanSets then set the recurrence exclusion rules to be those. .SS "exdate" .IX Subsection "exdate" Returns a DateTime::Set object representing the set of all \f(CW\*(C`RDATE\*(C'\fRs in the object. .PP May return undef. .SS "recurrence_id" .IX Subsection "recurrence_id" Returns a DateTime object representing the recurrence-id of this event. .PP May return undef. .PP If passed a DateTime object will set that to be the new recurrence-id. .SS "uid" .IX Subsection "uid" Returns the uid of this event. .PP If passed a new value then sets that to be the new uid value. .SS "summary" .IX Subsection "summary" Returns a string representing the summary of this event. .PP May return undef. .PP If passed a new value then sets that to be the new summary (and will escape all relevant characters). .SS "description" .IX Subsection "description" Returns a string representing the description of this event. .PP May return undef. .PP If passed a new value then sets that to be the new description (and will escape all relevant characters). .SS "url" .IX Subsection "url" Returns a string representing the url of this event. .PP May return undef. .PP If passed a new value then sets that to be the new description (and will escape all relevant characters). .SS "explode [period]" .IX Subsection "explode [period]" Takes DateTime::Set, DateTime::Span or DateTime::SpanSet and returns an array of events. .PP If this is not a recurring event, and it falls with the span, then it will return one event with the dtstart and dtend properties set and no other time information. .PP If this is a recurring event then it will return all times that this recurs within the span. All returned events will have the dtstart and dtend properties set and no other time information. .PP If \f(CW\*(C`period\*(C'\fR is optionally passed then events longer than \f(CW\*(C`period\*(C'\fR will be exploded into multiple events. .PP \&\f(CW\*(C`period\*(C'\fR can be any of the following .PP .Vb 1 \& year month week day hour minute second .Ve .SS "original " .IX Subsection "original " Store or fetch a reference to the original event this was derived from. .SS "split_up " .IX Subsection "split_up " Split an n\-period event into n 1\-period events. .SS "is_in " .IX Subsection "is_in " Takes DateTime::Set, DateTime::Span or DateTime::SpanSet and returns whether this event can fall within that time frame. .SH "AUTHOR" .IX Header "AUTHOR" Simon Wistow .SH "COPYING" .IX Header "COPYING" Copyright, 2005 Simon Wistow .PP Distributed under the same terms as Perl itself. .SH "BUGS" .IX Header "BUGS" Potential timezone problems? .SH "SEE ALSO" .IX Header "SEE ALSO" DateTime, DateTime::Set, Data::ICal, Text::vFile::asData, iCal::Parser