Overloaded Numeric Comparison Operators

 $mybday = Date::EzDate->new();
 $yourbday = Date::EzDate->new('tomorrow');

 if ($mybday < $yourbday) {
   ....
 }

Only one of the two items being compared needs be an EzDate object. The other can be a string representation of a date. For example, the following code correctly determines if the given EzDate object is before June 25, 2003:

 if ($date < 'June 25, 2003') {
    ...
 }

By default, the comparison is done on the "epochday" property, so two EzDate objects that have the same date but different times will be considered the same. If you want to compare based on some other property, set $Date::EzDate::overload to the name of the property to compare. For example, the following code sets the comparison property to "epoch hour", meaning that two date/times are considered the same only if they are identical down to the hour:

 my ($start, $finish);
 $start = Date::EzDate->new('Oct 18, 2006 4pm');
 $finish = Date::EzDate->new('Oct 18, 2006 6pm');

 # outputs false, because both epochdays are the same
 print 'finish is greater than start: ', $finish > $start, "\n";

 # change $Date::EzDate::overload to epochhour
 $Date::EzDate::overload = 'epochhour';

 # output true, because Oct 18, 2006 6pm is
 # greater than Oct 18, 2006 4pm
 print 'finish is greater than start: ', $finish > $start, "\n";

PLEASE NOTE: $Date::EzDate::overload used to be named $Date::EzDate::compare. I made a non-backwards compatible change to "overload" because the same variable for indicating default overload is now being used for non-comparison overloads like addition and subtraction.

Comparing Properties

 $date = Date::EzDate->new('January 3, 2001');
 $otherdate = Date::EzDate->new('January 10, 2001');

 if ($date->{'day of week'} eq $otherdate->{'day of week'}) {
    ...
 }

new([date string])

The following are valid ways to instantiate an EzDate object:

 # current date and time
 my $date = Date::EzDate->new();

 # a specific date and time
 my $date = Date::EzDate->new('Jan 31, 2001');

 # a date in DDMMMYYYY format
 my $date = Date::EzDate->new('14JAN2003');

 # a little forgiveness is built in (notice oddly place comma)
 my $date = Date::EzDate->new('14 January, 2003');

 # epoch second (23:27:39, Tue Apr 10, 2001 if you're curious)
 my $date = Date::EzDate->new(986959659);

 # yesterday
 my $date = Date::EzDate->new('yesterday');

 # tomorrow
 my $date = Date::EzDate->new('tomorrow');

$mydate->set_format($name, $format)

 $date->set_format('myformat', '{weekday long}, {month long} {day of month}, {year}');
 print $date->{'myformat'}, "\n";

You can also create a custom format by simply assigning the format to its name. If EzDate sees a "{" in the value being assigned, it knows that you are assigning a format, not a date. The set_format line above could be written like this:

 $date->{'myformat'} = '{weekday long}, {month long} {day of month}, {year}';

Note that it's not necessary to store a custom format if you're only going to use it once. If you wanted the format above, but just once, you could output it like this:

 print $date->{'{weekday long}, {month long} {day of month}, {year}'};

To delete a custom format, "$mydate-"del_format($name)>. To get the format string itself, use "$mydate-"get_format($name)>.

If you use the same custom format in a lot of different places in your project, you might find it easier to create your own customer super-class of Date::EzDate so that you can set the custom formats in one place. See "Super-classing Date::EzDate" below.

$mydate->clone()

$mydate->set_warnings($warning_level)

You can set which error handling you prefer with the "set_warnings" method. The first and only argument indicates how to handle errors. There are three possible values:

 0      Do not handle error in any way
 1      Output error to STDERR (default)
 2      Output to STDERR and exit program

So, for example, the following code sets the warnings to level 2:

 $date->set_warnings(2);

You can set the global default warning level by setting $Date::EzDate::default_warning. For example, the following code sets the global default level to 2:

 $Date::EzDate::default_warning = 2;

$mydate->next_month([integer])

The only argument, which defaults to 1, allows you to move backward or forward any number of months. For example, the following command moves the date forward two months:

 $mydate->next_month(2);

This command moves the date backward three months:

 $mydate->next_month(-3);

"next_month()" handles year boundaries without problem. Calling "next_month()" for a date in December moves the date to January of the next year.

$mydate->zero_hour_ampm(1|0)

 $date = Date::EzDate->new('4 pm');

If you would prefer the old behavior where the time would be set to whatever the current minute and second are, then call "zero_hour_ampm" with an argument of zero:

 $date->zero_hour_ampm(0);

You can also pass "zero_hour_ampm" as an initial argument for "new":

 $date = Date::EzDate->new('January 31, 2002 1 am', zero_hour_ampm=>0);

after_create

$start_date->date_range_string($end_date)

 # same month and year
 # outputs Mar 5-7, 2004
 $start = Date::EzDate->new('Mar 5, 2004');
 $end = Date::EzDate->new('Mar 7, 2004');
 print $start->date_range_string($end);

 # same year, different months
 # outputs Feb 20-Mar 3, 2004
 $start = Date::EzDate->new('feb 20, 2004');
 $end = Date::EzDate->new('mar 3, 2004');
 print $start->date_range_string($end);

 # different years
 # outputs Dec 23, 2004-Jan 3, 2005
 $start = Date::EzDate->new('Dec 23, 2004');
 $end = Date::EzDate->new('Jan 3, 2005');
 print $start->date_range_string($end);

It does not matter if the EzDate object is earlier or later than the second date. The function will always return them with the earlier date first.

You can pass either an EzDate object or a string. So, for example, the following blocks of code output the same thing:

 # outputs Mar 5-7, 2004
 $start = Date::EzDate->new('Mar 5, 2004');
 $end = Date::EzDate->new('Mar 7, 2004');
 print $start->date_range_string($end);

 # outputs Mar 5-7, 2004
 $start = Date::EzDate->new('Mar 5, 2004');
 print $start->date_range_string('Mar 7, 2004');

If both dates are the same day, then just that date will be returned:

 # same day
 # outputs Dec 23, 2004
 $start = Date::EzDate->new('Dec 23, 2004');
 print $start->date_range_string('Dec 23, 2004');

"date_range_string" can also be called a static method, i.e., without ever explicitly defining an EzDate object:

 # outputs Mar 5-7, 2004
 print Date::EzDate::date_range_string('Mar 5, 2004', 'Mar 7, 2004');

If you load EzDate using the ':all' param, the function call is even simpler:

 # note use of ':all'
 use Date::EzDate ':all';

 # outputs Mar 5-7, 2004
 print date_range_string('Mar 5, 2004', 'Mar 7, 2004');

Array references in the argument list are expanded. So, for example, the following two lines of code produce the same thing:

 print date_range_string('May 3, 2005', 'May 5, 2005');
 print date_range_string( ['May 3, 2005', 'May 5, 2005'] );

This behavior was added to accomodate the output from "day_lumps". See the documentation of "day_lumps" for a practical example of this feature.

$start_time->time_range_string($end_time)

 # outputs 10:00am-2:00pm
 $start = Date::EzDate->new('10:00am');
 $end = Date::EzDate->new('2:00pm');
 print $start->time_range_string($end);

"time_range_string" always tries to return the string as concisely as possible, so if the two times have the same am/pm designation then am/pm is only output once:

 # outputs 10:00-11:00am
 $start = Date::EzDate->new('10:00am');
 $end = Date::EzDate->new('11:00am');
 print $start->time_range_string($end);

"time_range_string" can also be called as a static method, i.e. without actually creating any EzDate objects:

 # outputs 8:00-9:00pm
 print Date::EzDate::time_range_string('8pm', '9pm');

If you load EzDate using the ':all' param, the function call is even simpler:

 # note use of ':all'
 use Date::EzDate ':all';

 # outputs 8:00-9:00pm
 print time_range_string('8pm', '9pm');

The earlier time is always output first. If you only pass times, not dates, then EzDate assumes that both times are on the same day and outputs the earlier time first:

 # outputs 8:00-9:00pm
 print time_range_string('8pm', '9pm');

If the time range crosses over midnight, you should explicitly indicate both dates:

 # output jan 21, 2005 8pm
 print time_range_string('jan 21, 2005 9pm', 'jan 22, 2005 5am');

day_lumps(@dates)

 Jan 3, 2005
 Jan 4, 2005
 Jan 5, 2005
 Jan 6, 2005
 Jan 10, 2005
 Jan 15, 2005
 Jan 16, 2005
 Jan 17, 2005

That list of dates could be more concisely expressed like this:

 Jan 3-6, 2005
 Jan 10, 2005
 Jan 15-17, 2005

"day_lumps" produces an array of day spans, each span containing the start and end date of a single "lump". Here's the code to produce the output from the example above:

# note use of ':all' use Date::EzDate ':all';

 my (@dates, @lumps);

 @dates = (
   'Jan 3, 2005',
   'Jan 4, 2005',
   'Jan 5, 2005',
   'Jan 6, 2005',
   'Jan 10, 2005',
   'Jan 15, 2005',
   'Jan 16, 2005',
   'Jan 17, 2005',
 );

 @lumps = day_lumps(@dates);

 foreach my $lump (@lumps)
    { print date_range_string($lump), "\n" }

Basic properties

hour

Hour in 24 hour clock, 00 to 23. Two digits, with a leading zero where necessary.

ampm hour

Hour in twelve hour clock, 0 to 12. Two digits, with a leading zero where necessary.

ampm

am or pm as appropriate. Returns lowercase. If you set this property the object will adjust to the same day and same hour but in am or pm as you set.

ampm uc, ampm lc

"ampm uc" returns AM or PM uppercased. "ampm lc" returns am or pm lowercased.

min, minute

Minute, 00 to 59. Two digits, with a leading zero where necessary.

sec, second

Second, 00 to 59. Two digits, with a leading zero where necessary.

weekday number

Number of the weekday. This number is zero-based, so Sunday is 0, Monday is 1, etc. If you assign to this property the object will reset the date to the assigned weekday of the same week. So, for example, if the object represents Saturday Apr 14, 2001, and you assign 1 (Monday) to weekdaynum:

 $mydate->{'weekday number'} = 1;
    

Then the object will adjust to Monday Apr 9, 2001.

weekday short

First three letters of the weekday. Sun, Mon, Tue, etc. If you assign to this property the object will adjust to that day in the same week. When you assign to this property EzDate actually only pays attention to the first three letters and ignores case, so SUNDAY would a valid assignment.

weekday long

Full name of the weekday. If you assign to this property the object will adjust to the day in the same week. When you assign to this property EzDate actually only pays attention to the first three letters and ignores case, so SUN would a valid assignment.

day of month

The day of the month. If you assign to this property the object adjusts to the day in the same month.

day of month ordinal word, day of month ordinal number

The day of month expressed as either an ordinal word (e.g. "Third") or as an ordinal number (e.g. "3rd").

month number

Zero-based number of the month. January is 0, February is 1, etc. If you assign to this property the object will adjust to the same month-day in the assigned month. If the current day is greater than allowed in the assigned month then the day will adjust to the maximum day of the assigned month. So, for example, if the object is set to 31 Dec 2001 and you assign the month to February (1):

 $mydate->{'month number'} = 1;
    

Then day of month will be set to 28.

month number base 1

1 based number of the month for those of us who are used to thinking of January as 1, February as 2, etc. Can be assigned to.

month short

First three letters of the month. Can be assigned to. This property is case insensitive, so "jAN" is as valid as "Jan". The assignment only looks at the first three letters of the input string, so "JANUARY" would be a valid assignment.

month long

Full name of the month. Can be assigned to. In the assignment, EzDate only pays attention to the first three letters and ignores case.

year

Year of the date the object represents.

year two digits

The last two digits of the year. If you assign to this property, EzDate assumes you mean to use the same first two digits. Therefore, if the current date of the object is 1994 and you assign '12' then the year will be 1912... quite possibly not what you intended.

day of year

Zero-based Number of days into the year of the date. "yearday" does the same thing.

day of year base1

One-based number of days into the year of the date. "yeardaybase1" does the same thing.

full

A full string representation of the date, e.g. "04:48:01 pm, Tue Apr 10, 2001". You can assign just about any common date and/or time format to this property.

Please take the previous statement as a challenge. I've aggressively tried to find formats that EzDate can't understand. When I've found one, I've modified the code to accomodate it. If you have some reasonably unambiguous date format that EzDate is unable to parse correctly, please send it to me. -Miko

When assigning a full date/time string, you can use 'noon' and 'midnight' to indicate specific times. So, for example, this string indicates July 25, 2003 and noon:

 $mydate = Date::EzDate->new('July 23 2003 noon');
 print $mydate->{'full'}; # outputs Wed Jul 23, 2003 12:00:00
    

dayandtime

Outputs the date and the time (to minute granularity).

 $mydate = Date::EzDate->new('December 23 2003 17:45');
 print $mydate->{'dayandtime'}; # outputs Dec 23 2003, 5:45pm
    

"dayandtime" is the default output format.

dmy

The day, month and year representation of the date, e.g. "03JUN2004".

dayparam

Returns the day of the month, the short month name (lowercased), and the full year. "dayparam" is a convenient string for passing as a parameter to scripts. It consists of just alphanumerics (so it need not be escaped in any way), it is easily human readable, and is completely unambiguous.

Actually, dayparam looks about the same as dmy, but it lowercased.

 $date = Date::EzDate->new('Dec 1, 2004 12:54:15');
 print $date->{'dayparam'}; # outputs 01dec2004
    

military time, miltime

The time formatted as HHMM on a 24 hour clock. For example, 2:20 PM is 1420.

clocktime

The time formatted as HH::MM AM/PM.

minute of day

How many minutes since midnight. Useful for doing math with times in a day.

iso8601

Returns the date in the format YYYY-MM-DD HH:MM:SS.

Epoch properties

epoch second

The basic Perl epoch integer.

epoch hour

How many hours since the epoch.

epoch minute

How many minutes since the epoch.

epoch day

How many days since the epoch.

Read-only properties

is leap year

True if the year is a leap year. The "is" part is optional.

days in month

How many days in the month.

Storing custom formats

 $date->set_format('myformat', '{weekday long}, {month long} {day of month}, {year}');
 print $date->{'myformat'}, "\n";

You can also create a custom format by simply assigning the format to its name. If EzDate sees a "{" in the value being assigned, it knows that you are assigning a format, not a date. The set_format line above could be written like this:

 $date->{'myformat'} = '{weekday long}, {month long} {day of month}, {year}';

Un*x-style date formatting

 print $mydate->{'%h %d, %Y %k:%M %p'}, "\n";

which would give you something like this:

 Oct 31, 2001 02:43 pm

Following is a list of codes. "*" indicates that the code acts differently than standard Unix codes. "x" indicates that the code does not exists in standard Unix codes.

 %a   weekday, short                               Mon
 %A   weekday, long                                Monday
 %b * hour, 12 hour format, no leading zero        2
 %B * hour, 24 hour format, no leading zero        2
 %c   full date                                    Mon Aug 10 14:40:38
 %d   numeric day of the month                     10
 %D   date as month/date/year                      08/10/98
 %e x numeric month, 1 to 12, no leading zero      8
 %f x numeric day of month, no leading zero        3
 %h   short month                                  Aug
 %H   hour 00 to 23                                14
 %j   day of the year, 001 to 366                  222
 %k   hour, 12 hour format                         14
 %m   numeric month, 01 to 12                      08
 %M   minutes                                      40
 %n   newline
 %P x AM/PM                                        PM
 %p * am/pm                                        pm
 %r   hour:minute:second AM/PM                     02:40:38 PM
 %s   number of seconds since start of 1970        902774438
 %S   seconds                                      38
 %t   tab
 %T   hour:minute:second (24 hour format)          14:40:38
 %w   numeric day of the week, 0 to 6, Sun is 0    1
 %y   last two digits of the year                  98
 %Y   four digit year                              1998
 %%   percent sign                                 %