- NAME
- SYNOPSIS
- DESCRIPTION

- date_is_valid
- date_is_greater
- date_is_smaller
- date_get date_get_gm
- date_comp
- date_diff
- date_add date_add_gm
- date_sub date_sub_gm
- timegm
- timlocal
- parse_format
- format_date
- Setting date format
- Transforming between date formats.
- Getting the GM offset.

- EXAMPLES
- COPYRIGHT
- VERSION

# NAME

GT::Date - Common date parsing and manipulation routines

# SYNOPSIS

        use GT::Date qw/:all/;
        my $date = date_get();
        my $next_week = date_add($date, 7);
        my $is_bigger = date_is_greater($date, $next_week);

# DESCRIPTION

GT::Date provides several functions useful in parsing dates, and doing date manipulation. Under the hood, it uses Time::Local code to transform a date into seconds for comparison and mathematical operations. It also uses the GT::Cache manpage to store most of the complex work.

No functions are exported by default. You can either specify the functions you need in use, or use the tags ':all' or ':timelocal'. All will give you all functions, and timelocal will give you functions found in Time::Local.

GT::Date uses a package global $DATE_FMT which specifies the format that dates should be returned in. You can change this using the `date_set_format()` function.

## date_is_valid

Returns 1 if the argument passed in is a valid date. It must first be in the current date format, and then be a valid date.

## date_is_greater

Returns 1 if argument 1 is greater then argument 2, otherwise 0.

## date_is_smaller

Returns 1 if argument 1 is smaller then argument 2, otherwise 0.

## date_get date_get_gm

Called with no arguments, returns the current date based on system time. You can specify the date you want by passing in the seconds since epoch (output of time()).

## date_comp

Equivalent to arg1 <=> arg2.

## date_diff

Returns number of days difference between arg1 - arg2.

## date_add date_add_gm

Returns date derived from arg1 + arg2, where the second argument can be either a date or number of days.

## date_sub date_sub_gm

Returns date derived from arg1 - arg2, where the second argument can be either a date or number of days.

## timegm

Takes the returned array from `gmtime()` and returns a unix time stamp.

## timlocal

Takes the array returned by `localtime()` and returns a unix time stamp.

## parse_format

Takes a string and a date format and returns an array ref of the first 7 arguments returned by localtime().

## format_date

Takes a localtime array, and a format string and returns a string of the parsed format.

## Setting date format

You can use date_set_format to change the format. You pass in a format string. It is made up of:

        %yyyy%      four digit year as in 1999
        %yy%        two digit year as in 99
        %y%         two digit year without leading 0
        %mmmm%      long month name as in January
        %mmm%       short month name as in Jan
        %mm%        numerical month name as in 01
        %m%         numerical month name without leading 0 as in 1
        %dddd%      long day name as in Sunday
        %ddd%       short day name as in Sun
        %dd%        numerical date
        %d%         numerical date without leading 0
        %HH%        two digit hour, 24 hour time
        %H%         one or two digit hour, 24 hour time
        %hh%        two digit hour, 12 hour time. 0 becomes 12.
        %h%         one or two digit hour, 12 hour time. 0 becomes 12.
        %MM%        two digit minute
        %M%         one or two digit minute (when would someone ever WANT this?)
        %ss%        two digit second
        %s%         one ot two digit second (when would someone ever WANT this?)
        %tt%        AM or PM (use with 12 hour time)
        %o%         + or - GMT offset

Common formats include:

        %yyyy%-%mm%-%dd%            1999-12-25
        %dd%-%mmm%-%yyyy%           12-Dec-1999
        %ddd% %mmm% %dd% %yyyy%     Sat Dec 12 1999
        %ddd% %mmm% %dd% %yyyy%     Sat Dec 12 1999

or RFC822 mime mail format:

         %ddd%, %dd% %mmm% %yyyy% %HH%:%MM%:%ss% %o%   Sat, 12, Dec 1999 21:32:02 -0800

or MySQL format:

        %yyyy%-%mm%-%dd% %HH%:%MM%:%ss%  1999-03-25 21:32:02

The language used for month names and day names can be changed with date_set_month(), date_set_days(), `date_set_days_short()` and date_set_month_short().

## Transforming between date formats.

You can transform a date from one format to another with:

        date_transform ($date, $orig_fmt, $new_fmt);

where $orig_fmt and $new_fmt are date format strings described above.

## Getting the GM offset.

You can get the number of seconds between the system time and GM time using:

        my $time = date_gmt_offset();

So if you are in Pacific time, it would return 25200 seconds (-0700 time zone).

# EXAMPLES

Get todays date, the default format unless specified is yyyy-mm-dd.

        print date_get();                 2000-12-31

Get todays date in a different format:

        date_set_format('%ddd% %mmm% %dd% %yyyy%');
        print date_get();                               Sat Dec 31 2000

Get the date from 1 week ago.

        # Long way
        my $date1 = date_get();
        my $date2 = date_sub($date1, 7);

            or

        # Can pass in unix timestamp of date we want.
        my $date = date_get (time - (7 * 86400));

Compare two dates.

        my $halloween = '2000-10-31';
        my $christmas = '2000-12-25';
        if (date_is_smaller($halloween, $christmas)) {
            print "Halloween comes before christmas!";
        }
        if (date_is_greater($christmas, $halloween)) {
            print "Yup, christmas comes after halloween.";
        }
        my @dates = ($halloween, $christmas);
        print "Dates in order: ", sort date_comp @dates;

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: Date.pm,v 1.75 2005/04/04 22:21:23 brewt Exp $