ExSite::Time

Utilities for handling dates and times in various formats.

We support the following time formats

    sql_date            yyyy-mm-dd
    iso_date            yyyy-mm-dd
    sql_datetime        yyyy-mm-dd hh:mm:ss
    time                hh:mm AM/PM
    time24              hh:mm (24-hour clock)
    hms                 hh:mm:ss (24-hour clock)
    sql_timestamp       yyyymmddhhmmss OR yyyy-mm-dd hh:mm:ss *
    unix_timestamp      nnnnnnnnnnn
    date                mmm dd, yyyy
    date_long           Month dd, yyyy
    datetime            wday Mon dd hh:mm yyyy
    datetime_long       Weekday Month dd hh:mm yyyy
    datetime2           hh:mm AM/PM, Month dd, yyyy
    arpa                wday, dd Mon yy hh:mm:ss ZONE
    cookie              Wdy, dd-mmm-yyyy hh:mm:ss GMT
    full                Weekday, Month dd, yyyy at hh:mm AM/PM
    dd-mmm-yy           dd-Mon-yy
    weekday             wday
    weekday_long        Weekday
    year                yyyy
    month               Mon
    month_long          Month
    raw                 [y,m,d,h,m,s]
    raw_year            yyyy
    raw_month           mm
    raw_day             dd
    raw_hour            hh
    raw_minute          mm
    raw_second          ss

* depends on $config{timestamp_format}, which normally depends on which which version of MySQL you are running.

Internally, we convert all dates/times to a 6-element time array: y, m, d, h, m, s. The time array is initialized to the current datetime, so if you only set a partial datetime (eg. only the time), the remaining values are unchanged, and the full array still represents a complete datetime.

Usage

Make a time object (initialized to current time):

    my $t = new ExSite::Time;

Make a time object (initialized to some other time/format):

    my $t = new ExSite::Time("2001-12-25 09:00:00","sql_datetime");

Set the time to the current time:


$t->set;

Set the time to some time/format:

    $t->set('Feb 1, 1968','date');
    $t->set('6:30 pm','time');
    $t->set('Fri Aug 26 12:14:43 2005','datetime');

Validation

Times can be correctly formatted, but still meaningless or even just questionable. For example:

    Feb 30, 2008       # obviously illegal day
    Feb 29, 2000       # not-so-obviously illegal day
    Feb 28, 1008       # strange, but legal, year

Time validation can catch these and other cases. To validate the date/time value:

    my $error = $t->validate();

The return value, $error, will be set to a message explaining the formatting problems, if there are any. Otherwise, it returns undef. To validate, date values must fall in the following ranges:

    year    within 100 years of current date (configurable)
    month   1 - 12
    day     1 - number of days in month
    hour    0 - 23
    min     0 - 59
    sec     0 - 59

Adjusting Times

To adjust the time by some amount:

    $t->add(30,'days');
    $t->add(-3,'months');

NB: some time units are not precisely defined, so we must approximate. What we do is define 1 month as 1/12 of a year, and 1 year as 365 days. These may not give expected results. For example, adding 1 month will not leave you at the same time of day, nor on the same day of the following month. (To understand why this is correct, consider what the date should be if we start from Jan 31, and add 1 month.)

Displaying Times

Output the time in some format:

    print $t->write('date');
    print $t->write('unix_timestamp');
    print $t->write('weekday');

Comparing Times

Compare another time to the currently-set time (returns 1 if the compared time is in the future, -1 if it is in the past, and 0 if it is the same as the current time):

    $t->compare('20050826091500','sql_timestamp');

If directly comparing two instances of this class, the format string is not needed:

    $t->compare($t2);

Compare two Time instances using operator overloading:


$t <=> $t2
    $t > $t2
    # etc...

Note that the <=> operator and all other comparison operators only compare the date portion of an object. To compare the entire date and time, use the subtraction operator, eg:

    sort { $a - $b }   # time-sensitive sort
    sort { $a <=> $b } # time-insensitive sort

Convenience call to compare two times in same format:

    $t->compare2('Aug 26, 2005','Aug 28, 2005','datetime');