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 use OO syntax
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

# "next month's last day"
$date{month}+=2;
$date{day} = 0;        # this is actually a "-1" since days start in "1"

# copy a date with timezone
tie my %newdate, 'Date::Tie', tz => $date{tz}, epoch => $date{epoch};

DESCRIPTION

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

Whenever a Date::Tie hash key receives a new value, 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 default value of a new hash will be the current value of gmtime(), with timezone +0000 and with fractional seconds set to zero.

HASH KEYS

Date::Tie manages a hash containing the keys: year, month, day, hour, minute, second, yearday, week, weekday, weekyear, epoch, tz, tzhour, tzminute, frac. All keys can be read or written directly.

year, month, day, hour, minute, second

These keys are just what they say.

You can use monthday instead of day if you want to make it clear it is not a yearday or a weekday.

yearday, week, weekday, weekyear

yearday is the day number in the year.

weekday is the day number in the week. weekday 1 is monday.

week is the week number in the year.

weekyear is the year number, when referring to a week of a year. 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, tz, tzhour, tzminute

epoch is the local epoch.

tz is the timezone as hundreds, like in -0030. It is not always the same as the expression $date{tzhour} . $date{tzminute}, which in this case would be -00-30.

Changing timezone (any of tz, tzhour, or tzminute) changes epoch.

frac

Fractional seconds. A value bigger or equal to 0 and less than 1.

$d{frac} =   0.5;
print $d{frac};              # '.5'

$d{frac} =   0;
print $d{frac};              # '.0'

second and epoch are integers. Setting frac does not change second or epoch, unless it overflows:

$d{second} = 6;
print $d{second};            # '06'
$d{frac} =   1.5;
print $d{second};            # '07'    - frac overflow
print $d{frac};              # '.5'

To obtain the fractional second or epoch:

print "$d{second}$d{frac}";  # '07.5'  - concatenation
print $d{second} + $d{frac}; # '7.5'   - addition
print $d{epoch} + $d{frac};  # '45673455.5'   - fractional epoch

ISO 8601

Markus Kuhn wrote a summary of ISO8601 International Standard Date and Time Notation in http://www.cl.cam.ac.uk/~mgk25/iso-time.html

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 $date{tzhour} . $date{tzminute} gives -00-30. Use tz to get -0030.

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

# copy all fields - may 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};

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

If you change month, then day will be adjusted to fit that month:

$date = (month=>10, day=>31);
$date{month}++;     #  month=>11, day=>30

If you need to know whether a hash is tied to Date::Tie use perl function tied()

SEE ALSO

Date::Calc, Date::Manip, Class::Date, and many other good date and time modules!

Date::Tie depends on Tie::Hash and Time::Local.

AUTHOR

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

cpanm Date::Tie

perl -MCPAN -e shell
install Date::Tie