NAME

       Data::ICal::DateTime - convenience methods for using Data::ICal with DateTime

SYNPOSIS

           # performs mixin voodoo
           use Data::ICal::DateTime;
           my $cal = Data::ICal->new( filename => 'example.ics');

           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,'day');# 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,'week');         # 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);

       methods

DESCRIPTION

METHODS

   events [span] [period]
       Provides a Data::ICal object with a method to return all events.

       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.

       Additionally you can pass a period string which can be one of the following

           year month week day hour minute second

       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

   collapse <events>
       Provides a Data::ICal object with a method to collapse "recurrence-id"s.

       Given a list of events, some of which might have "recurrence-id"s, return a list of events
       with all recurrences within "span" and all "recurrence-id"s handled correctly.

       Used internally by "events".

   start [new]
       Returns a DateTime object representing the start time of this event.

       May return undef.

       If passed a DateTime object will set that to be the new start time.

   end
       Returns a DateTime object representing the end time of this event.

       May return undef.

       If passed a DateTime object will set that to be the new end time.

   all_day
       Returns 1 if event is all day or 0 if not.

       If no end has been set and 1 is passed then will set end to be a nanosecond before
       midnight the next day.

       The have multi-day all-day events simply set the end time to be nanosecond before midnight
       on the last day of the event.

   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.

       Returns 1 if the evnt is floating and 0 if it isn't.

       If passed a 1 then will set the event to be floating by deleting the end time.

       If passed a 0 and no end is currently set then it will set end to be a nanosecond before
       midnight the next day.

   duration
       Returns a DateTime::Duration object representing the duration of this event.

       May return undef.

       If passed a DateTime::Duration object will set that to be the new duration.

   period
       Returns a DateTime::Span object representing the period of this event.

       May return undef.

       If passed a DateTime::Span object will set that to be the new period.

   recurrence
       Returns a DateTime::Set object representing the union of all the "RRULE"s in this object.

       May return undef.

       If passed one or more DateTime lists, DateTime::Span lists, DateTime::Sets, or
       DateTime::SpanSets then set the recurrence rules to be those.

   rdate
       Returns a DateTime::Set object representing the set of all "RDATE"s in the object.

       May return undef.

   exrule
       Returns a DateTime::Set object representing the union of all the "EXRULE"s in this object.

       May return undef.

       If passed one or more DateTime lists, DateTime::Span lists, DateTime::Sets, or
       DateTime::SpanSets then set the recurrence exclusion rules to be those.

   exdate
       Returns a DateTime::Set object representing the set of all "RDATE"s in the object.

       May return undef.

   recurrence_id
       Returns a DateTime object representing the recurrence-id of this event.

       May return undef.

       If passed a DateTime object will set that to be the new recurrence-id.

   uid
       Returns the uid of this event.

       If passed a new value then sets that to be the new uid value.

   summary
       Returns a string representing the summary of this event.

       May return undef.

       If passed a new value then sets that to be the new summary (and will escape all relevant
       characters).

   description
       Returns a string representing the description of this event.

       May return undef.

       If passed a new value then sets that to be the new description (and will escape all
       relevant characters).

   url
       Returns a string representing the url of this event.

       May return undef.

       If passed a new value then sets that to be the new description (and will escape all
       relevant characters).

   explode <span> [period]
       Takes DateTime::Set, DateTime::Span or DateTime::SpanSet and returns an array of events.

       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.

       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.

       If "period" is optionally passed then events longer than "period" will be exploded into
       multiple events.

       "period" can be any of the following

           year month week day hour minute second

   original <event>
       Store or fetch a reference to the original event this was derived from.

   split_up <period>
       Split an n-period event into n 1-period events.

   is_in <span>
       Takes DateTime::Set, DateTime::Span or DateTime::SpanSet and returns whether this event
       can fall within that time frame.

AUTHOR

       Simon Wistow <simon@thegestalt.org>

COPYING

       Copyright, 2005 Simon Wistow

       Distributed under the same terms as Perl itself.

BUGS

       Potential timezone problems?

SEE ALSO

       DateTime, DateTime::Set, Data::ICal, Text::vFile::asData, iCal::Parser