NAME
    Date::ICal - Perl extension for ICalendar date objects.

SYNOPSIS
        use Date::ICal;

        $ical = Date::ICal->new( ical => '19971024T120000' );
        $ical = Date::ICal->new( epoch => time );
        $ical = Date::ICal->new( year => 1964,
            month => 10, day => 16, hour => 16,
            min => 12, sec => 47, tz => '0530' );

        $hour = $ical->hour;
        $year = $ical->year;

        $ical_string = $ical->ical;
        $epoch_time = $ical->epoch;

DESCRIPTION
    Date::ICal talks the ICal date format, and is intended to be a base
    class for other date/calendar modules that know about ICal time format
    also.

    See http://dates.rcbowen.com/unified.txt for details

METHODS
    Date::ICal has the following methods available:

  new

    A new Date::ICal object can be created with any valid ICal string:

        my $ical = Date::ICal->new( ical => '19971024T120000' );

    Or with any epoch time:

        my $ical = Date::ICal->new( epoch => time );

    Or, better still, create it with components

        my $date = Date::ICal->new( 
                               day => 25, 
                               month => 10, 
                               year => 1066,
                               hour => 7,
                               min => 15,
                               sec => 47
                               );

    If you call new without any arguments, you'll get a Date::ICal object
    that is set to the time right now.

        my $ical = Date::ICal->new();

    If you already have an object in Date::ICal, or some other subclass
    thereof, you can create a new Date::ICal (or subclass) object using that
    object to start with. This is particularly useful for converting from
    one calendar to another:

       # Direct conversion from Discordian to ISO dates
       my $disco = Date::Discordian->new( disco => '12 Chaos, YOLD 3177' );
       my $iso = Date::ISO->new( $disco );
       print $iso->iso;

  ical

        $ical_string = $ical->ical;

    Retrieves, or sets, the date on the object, using any valid ICal
    date/time string.

  epoch

        $epoch_time = $ical->epoch;
    
        $ical->epoch( 98687431 );

    Sets, or retrieves, the epoch time represented by the object, if it is
    representable as such. (Dates before 1971 or after 2038 will not have an
    epoch representation.)

    Internals note: The ICal representation of the date is considered the
    only authoritative one. This means that we may need to reconstruct the
    epoch time from the ICal representation if we are not sure that they are
    in synch. We'll need to do clever things to keep track of when the two
    may not be in synch. And, of course, the same will go for any subclasses
    of this class.

  offset

        $offset = $ical->offset;
    
        $ical->offset( '+1100' );

    Sets or retrieves the offset from UTC for this time. This allows
    timezone support, assuming you know what your local (or non-local) UTC
    offset is. Defaults to 0.

    Internals note: all times are internally stored in UTC, even though they
    may have some offset information. Offsets are internally stored in
    signed integer seconds.

  add

        $date->add( %hash ); # Hash of day, hour, min, etc, values
        $date->add( ical => $ical_duration_string );

    Adds a duration to a Date::ICal object.

    Duration should be passed in as either an ical string, or as a hash of
    date/time properties.

    The result will be normalized. That is, the output time will have
    meaningful values, rather than being 48:73 pm on the 34th of
    hexadecember.

       $self->add( month=>2 );
       $self->add( duration =>'P1W' );

  compare

        $cmp = $date1->compare($date2);

        @dates = sort {$a->compare($b)} @dates;

    Compare two Date::ICal objects. Semantics are compatible with sort;
    returns -1 if $a < $b, 0 if $a == $b, 1 if $a > $b.

  day

        my $day = $date->day;

    Returns the day of the month.

    Day is in the range 1..31

  month

        my $month = $date->month;

    Returns the month of the year.

    Month is returned as a number in the range 1..12

  year

        my $year = $date->year;

    Returns the year.

hour
        my $hour = $date->hour

    Returns the hour of the day.

    Hour is in the range 0..23

min
        my $min = $date->min;

    Returns the minute.

    Minute is in the range 0..59

sec
        my $sec = $date->sec;

    Returns the second.

    Second is in the range 0..60. The value of 60 is (maybe) needed for leap
    seconds. But I'm not sure if we're going to go there.

julian
      my $jd = $date->jd;

    Returns a listref, containing two elements. The date as a julian day,
    and the time as the number of seconds since midnight. This should not be
    thought of as a real julian day, because it's not. The module is
    internally consistent, and that's enough.

    This really should be considered an internal method.

    See the file INTERNALS for more information about this internal format.

TODO
    - add timezone support, including moving between timezones
    - add gmtime and localtime methods, perhaps?
    - Find a solution to the 1-second round-off errors. Perhaps move to two
    values (date and time) rather than one single value. This change can be
    made internally without affecting anything outside.
INTERNALS
        Please see the file INTERNALS for discussion on the internals.

AUTHOR
        Rich Bowen (DrBacchus) rbowen@rcbowen.com

        And the rest of the Reefknot team.

SEE ALSO
        datetime@perl.org mailing list

        http://reefknot.org/

        http://dates.rcbowen.com/

        Time::Local

        Net::ICal

        # CVS History #{{{

CVS History
          $Log: README,v $
          Revision 1.1  2001/10/15 01:56:25  rbowen
          coral says README is prefered to Readme, wrt CPAN. I had no opinions
          either way, so here it is.

          Revision 1.34  2001/09/12 03:26:23  rbowen
          There's no particular reason to have Date::ICal be 5.6 dependant.

          Revision 1.33  2001/08/25 12:20:30  rbowen
          Fixed bug reported by Chris Jones. In sub add, I was checking one
          attribute and using another. Added tests for this bug, and for adding
          durations by attribute.

          Revision 1.32  2001/08/10 03:27:47  srl
          Started adding timezone support by making an offset() method and an offset
          property. This still needs to be wired into the new() method and the
          output methods, but we have to resolve some interface details first.

          Revision 1.31  2001/08/07 02:41:11  rbowen
          Test::More gets angry if there are no tests.

          Revision 1.30  2001/08/07 02:30:01  rbowen
          Moved the inline tests into t/ for the sake of making the module more
          readable. Please don't let this discorage you from writing inline
          tests.

          Revision 1.29  2001/08/06 19:32:39  rbowen
          Creating an object without args was calling gmtime( $args{epoch} ).
          Fixed and added tests. Also added Time::HiRes to PREREQ list.

          Revision 1.28  2001/08/06 18:45:47  rbowen
          sub epoch was referencing another sub that has gone away. Fixed, and
          added tests.

          Revision 1.27  2001/08/02 04:38:16  srl
          Adjusted the add() method to return a copy of $self instead of the
          return value of $self->jd(). This was important to making
          the Net::ICal tests pass, but it's also the Right Way, I think.

          Revision 1.26  2001/08/02 03:47:59  rbowen
          Handle negative durations correctly.

          Revision 1.25  2001/08/01 02:19:03  rbowen
          Two main changes here.
          1) Split the internal date/time representation into date, time
          integers, so that we don't have any more roundoff error.
          2) Memoized the parsetime and parsedate methods, so that we're not
          doing that three times every time we want three components, which we
          were doing.

