NAME

Date::Object::DateTime - wrap date functions to allow date quantities to be treated as numbers.

SYNOPSIS

$date1 = Date::Object::DateTime->new();
$date1->set("1999-09-09");
$date2 = Date::Object::DateTime->new("2001-01-01");
$date3 = $date1 + 1;
$date4 = $date1 + "1y 2m 2d";
for (my $idx = $date1; $idx < $date2; $idx++) {
    print $idx . "\n";
}

DESCRIPTION

This object wraps calls to time and localtime to make date values usable as mathemagical objects. This allows you to perform date arithmetic and use dates where you would normally use a number (like a loop index).

Since this objects wraps perl's calls to ctime functions, it is limited in the same way. The same limitations and problems of using UNIX seconds from the epoch apply to these objects.

IMPLEMENTATION

Please note that "==" is VERY different from "eq". The first checks to see if they are the same referenced object, while the second checks if they are the same "value".

When setting via month or day, we "round" the date if it is too large for the month. Now, for the discussion:

Ok, there are two ways we could do this: 1) "Truncate" the days to fit the month 2) "Round" the date to the appropriate date next month

I am unsure which one to use. I'm going to go with #2 for now, until I hear a better reason.

Now if you are working with months, it doesn't seem to be a good idea, since when you set month to month - 1, you want the last month (e.g. under #2 "2001-07-31" month - 1 becomes "2001-07-01"). However, it preserves the weekday, mainly, you keep yourself in the same "place" in the week, moving back a month--well, kind of.

If you want to be "accurate" by weekday, always use weeks. If you want accurately iterate over months, set the date to the 1st and add away.

This becomes an issue if you want to get a date from the previous month or want the previous month. I provide both methods (round_month_day_vals and trunc_month_day_vals), so if you need the truncation, use it. But the reality is that if you want the previous month, you need to copy the date, set the day to 1, and the subtract a month via set_month or addition.

Again, if you want weekday accuracy, you need to stick to days and weeks. The gregorian calendar system is just insane, and it isn't my fault.

If you add a quantity to an existing date and cross a leap year, you might lose a day due to the leap day. I.e. adding days is accurate except when spanning multiple years. Use year quantities for moving years at a time, since this will preserve your place in the calendar.

This isn't necessarily a bug, but a "feature" of the gregorian calendar.

BUGS

This object currently wraps localtime. This is probably an issue.

Should probably use gmtime. Need to handle timezones and such, since plays havoc with seconds values. But it gets the job done.