NAME

Date::Tie - ISO dates made easy

SYNOPSIS

use Date::Tie;

tie my %date, 'Date::Tie', year => 2001, month => 11, day => 9;
$date{year}++;
$date{month} += 12;    # 2003-11-09

# you can also do this
my $date = Date::Tie->new( year => 2001, month => 11, day => 9 );
$date->{year}++;
$date->{month} += 12;  # 2003-11-09

$date{weekday} = 0;    # sunday at the start of this week
$date{weekday} = 7;    # sunday at the end of this week
$date{weekday} = 14;   # sunday next week 

$date{tz} = '-0300';   # change timezone
$date{tzhour}++;       # increment timezone

DESCRIPTION

Date::Tie is an attempt to simplify date operations syntax.

Date::Tie manages a hash containing the keys: epoch, year, month, day, hour, minute, second, yearday, week, weekday, weekyear, tz, tzhour, tzminute.

All keys have read/write access.

'week' is the week number in the year.

'day' and 'monthday' refer to the same entity.

'weekyear' is the year number when using week notation. It is often NOT EQUAL to 'year'. Changing 'weekyear' will leave you with the same week and weekday, while changing 'year' will leave you with the same month and monthday.

'epoch' is the local epoch. It changes when timezone ('tzhour', 'tzminute') changes.

'tz' is the timezone as hundreds (-0030). It is not always the same as (tzhour . tzminute), which in this case would be -00-30.

Whenever a new value is stored, it will change the other keys following the ISO date rules.

For example:

print $a{hour}, ":", $a{minute};     #  00 59
$a{minute}++;
print $a{hour}, ":", $a{minute};     #  01 00

The hash is created with the current value of gmtime, and timezone +0000.

ISO 8601 BASICS

Day of year starts with 001.

Day of week starts with 1 and is a monday.

Week starts with 01 and is the first week of the year that has a thursday. Week 01 often begins in the previous year.

CAVEATS

Reading time zone -0030 with ('tzhour' . 'tzminute') gives -00-30. Use 'tz' to get -0030.

The order of setting hash elements is important. This will NOT make %b equal to %d:

# copy all fields - will not work!
tie my %b, 'Date::Tie', %d;

This is one way to make a copy of %d:

# set timezone, then epoch
tie my %b, 'Date::Tie', tz => $d{tz}, epoch => $d{epoch};

If you change month, the day will be adjusted to fit that month. That is, "october 31" + "1 month" gives "december 30".

TODO

test fractions of seconds

access environment for timezone initialization

HISTORY

	0.05 POD format correction
	     tzhour,tzminute is -00-30 instead of +00-30
	     more tests

	0.04 yearday, weekday, week, weekyear
	     better storage
	     initializes to 'now'.
	     timezones
	     more tests
 
	0.03 STORE rewritten
	     examples work

	0.02 Make it a real module

	0.01 I started this when dLux said:
		> What about this kind of syntax:
		> my $mydate = new XXXX::Date "2001-11-07";
		> # somewhere later in the code
		> my $duedate = $mydate + 14 * XXX::Date::DAY;
		> my $duedate = $mydate + 14 * DAY;
		> my $duedate = $mydate->add(12, DAYS);
		> my $duedate = $mydate->add(day => 12);
		> my $duedate = $mydate + "12 days";
		> my $duedate = $mydate + "12 days and 4 hours and 3 seconds"; # :-)

SEE ALSO

Date::Calc, Date::Manip, Class::Date, and many others!

AUTHOR

Flávio Soibelmann Glock (fglock@pucrs.br)

cpanm Date::Tie

perl -MCPAN -e shell
install Date::Tie