NAME
Date::Handler - Easy Date Object
SYNOPSIS
use Date::Handler;
my $date = new Date::Handler({ date => time, time_zone => 'Europe/Paris', });
my $date = new Date::Handler({ date => [2001,04,12,03,01,55], time_zone => 'EST', });
my $date = new Date::Handler({ date => {
year => 2001,
month => 4,
day => 12,
hour => 3,
min => 1,
sec => 55,
}, time_zone => 'America/Montreal', });
print $date;
print "$date";
print $date->AllInfo();
$date->new() Constructor
$date->Year() 2001
$date->Month() 1..12
$date->Day() 1..31
$date->Hour() 0..23
$date->Min() 0..59
$date->Sec() 0..59
$date->Epoch($epoch) Seconds since epoch (GMT)
$date->TimeZone() America/Montreal
$date->TimeZoneName() EST
$date->LocalTime() localtime of the object's epoch
$date->TimeFormat($format_string) strftime
$date->GmtTime() gmtime of object's epoch
$date->UtcTime() same as GmtTime()
$date->GmtOffset() Offset of object's TZ in seconds
$date->MonthName() April
$date->WeekDay() 1..7 (1 monday)
$date->WeekDayName() Wednesday
$date->FirstWeekDayOfMonth() 1..7
$date->WeekOfMonth() 1..4
$date->DaysInMonth() 31,30,29,28 depending on month and year.
$date->IsLeapYear() 1 if true, 0 if false
$date->DayLightSavings() 1 if true, 0 if false
$date->DayOfYear() Return the day of the year
$date->DaysInYear() Returns the number of days in the year.
$date->DaysLeftInYear() Returns the number of days remaining in the year
$date->Array2Epoch([]) Transfer [y,m,d,h,mm,ss] to epoch time
$date->AsScalar () Same as TimeFormat("%A, %B%e %Y %R (%Z)")
$date->AsNumber() same as Epoch()
$date->AsArray() Returns [y,m,d,h,mm,ss]
$date->AsHash() Returns { year => y, month => m, day => d, hour => h, min => mm, sec => ss }
$date->AllInfo() Returns a string containing all of the Object's related information.
my $delta = new Date::Handler::Delta([3,1,10,2,5,5]);
my $delta = new Date::Handler::Delta({
years => 3,
months => 1,
days => 10,
hours => 2,
minutes => 5,
seconds => 5,
});
$delta->new (More information in perldoc Date::Handler::Delta)
$delta->Months() Number of months in delta
$delta->Seconds() Number of seconds in delta
$delta->AsScalar() "%d months and %d seconds"
$delta->AsNumber() "%d-%d-%d"
$delta->AsArray() [y,m,ss]
$delta->AsHash() { months => m, seconds => ss }
$date + $delta = Date::Handler
$date - $delta = Date::Handler
$date - $date2 = Date::Handler::Delta
$date + n = (+n seconds)
$date - n = (-n seconds)
$delta + $delta = Date::Handler::Delta
$delta - $delta = Date::Handler::Delta
$delta * n = Date::Handler::Delta
$delta / n = Date::Handler::Delta
$delta + n = (+n seconds)
$delta - n = (-n seconds)
my $range = Date::Handler::Range->new({
date => $date,
delta => $delta,
});
my $range = Date::Handler::Range->new({
date => [2001,06,08,2,00,00],
delta => [0,0,1,0,0],
});
$range->new (More info in perldoc Date::Handler::Range)
$range->Direction() Specifies the direction of a range ('FORWARDS' || 'BACKWARDS')
$range->StartDate() Start Date::Handler object for this range and direction
$range->EndDate() End Date::Handler object for this range and direction
$range->Overlaps($range2) Returns true if range overlaps range2. undef otherwise.DESCRIPTION
Date::Handler is a container for dates that holds all the methods to transform itself from Timezone to Timezone and format itself. This module idea comes from an original version written by dLux (Szabó, Balázs) <dlux@kapu.hu> in his module Class::Date.
Date::Handler is implemented in pure Perl using POSIX modules, it encapsulates the environnement variable TZ for it's time zone management so you don't have to play with it externally in the implementation.
It uses operator overloading and Delta date objects to calculates time differences.
This code is still in it's alpha stage(v0.05) and should not be used on production systems without reviewing the actual test cases provided with this module in the Date::Handler::Test package.
IMPLEMENTATION
Using the Date::Handler is simple.
Creating the absolute Date::Handler
The new() constructor receives only one argument as a hashref:
my $date = new Date::Handler({
date => time,
time_zone => 'Asia/Hong_Kong',
});The 'date' key of this argument can be either:
Epoch time
Anonymous array of the form: [y,m,d,h,mm,ss]
A hashref of the form : { year => y,month => m, day => d, hour => h, min => mm, sec => ss }
The items in the array (or hash) of the 'date' key should follow these rules:
year - The year number
mon - The number of months since January, in the range 1 to 12.
day - The day of the month, in the range 1 to 31.
hour - The number of hours past midnight, in the range 0 to 23.
min - The number of minutes after the hour, in the range 0 to 59.
sec - The number of seconds after the minute, normally in the range 0 to 59.
The 'time_zone' key represents the time zone name this date is considered in. i.e. Africa/Dakar, EST, PST, EDT
Accessors
You can access the data inside the object using any of the provided methods. These methods are detailed in the SYNOPSIS up above.
Modifying the object
A created Date::Handler can be modified on the fly by many ways:
Changing the time_zone of the object using TimeZone()
Changing the internal date of the object using Epoch()
By using operators in combination with Date::Handler::Delta objects
Example:
my $date = new Date::Handler({ date => time });
$date->TimeZone('Asia/Tokyo');
print "Time in tokyo: ".$date->LocalTime()."\n";
$date->Epoch(time);
$date->TimeZone('America/Montreal');
print "Time in Montreal: ".$date->LocalTime()."\n";
$date->TimeZone('GMT');
print "Greenwich Mean Time: ".$date->LocalTime()."\n";Using Date::Handler::Delta objects
To go forward or backward in time with a date object, you can use the Date::Handler::Delta objects. These objects represent a time lapse represented in months and seconds. Since Date::Handler uses operator overloading, you can 'apply' a Delta object on an absolute date simply by using '+' and '-'.
Example:
#A Delta of 1 year.
my $delta = new Date::Handler::Delta([1,0,0,0,0,0]);
my $date = new Date::Handler({ date => time } );
#$newdate is now one year in the furure.
my $newdate = $date+$delta;Refer to the Date::Handler::Delta(1) documentation for more on Deltas.
Using Date::Handler::Range objects
Range objects are used to specify moments in time between 2 dates. For the moment, this functionnality is very primitive but will evolve in future versions. Each range object is constructed by a base Date::Handler object. Then combined to that is a Date::Handler::Delta will specify the length of the range. Then thirdly, the range is given a direction, either 'FORWARDS' or 'BACKWARDS' in time. From these three values are calculated a start date and an end date.
Example:
#Creation of the range starting now, ending in 2 days.
my $range = Date::Handler::Range->new({
date => time(),
delta => [0,0,2,0,0],
});
#This is already set to 'FORWARDS' by default.
$range->Direction('FORWARDS');
print "This range start ".$range->StartDate()." and ends ". $range->EndDate()."\n";
#Another range, starting at the end date of range 1, going backwards in time 7 days.
my $range2 = Date::Handler::Range->new({
date => $range->StartDate(),
delta => [0,0,7,0,0],
});
$range2->Direction('BACKWARDS');
#This returns true if range overlaps range2.
$range->Overlaps($range2);As I said earlier, the range functionnality is still very primitive, and the interface might change.
Operator overload special cases
The Date::Handler overloaded operator have special cases. Refer to the SYNOPSIS to get a description of each overloaded operator's behaviour.
One special case of the overload is when adding an integer 'n' to a Date::Handler's reference. This is treated as if 'n' was in seconds. Same thing for substraction.
Example Uses of the overload:
my $date = new Date::Handler({ date =>
{
year => 2001,
month => 5,
day => 14,
hour => 5,
min => 0,
sec => 0,
}});
#Quoted string overload
print "Current date is $date\n";
my $delta = new Date::Handler::Delta({ days => 5, });
#'+' overload, now, $date is 5 days in the future.
$date += $delta;
#Small clock. Not too accurate, but still ;)
while(1)
{
#Add one second to the date. (same as $date + 1)
$date++;
print "$date\n";
sleep(1);
}INHERITANCE
A useful way of using Date::Handler in your code is to implement that a class that ISA Date::Handler. This way you can overload methods through the inheritance tree and change the object's behaviour to your needs.
Here is a small example of an overloaded class that specifies a default timezone different than the machine's timezone.
#!/usr/bin/perl
package My::Date::Handler;
use strict;
use vars qw(@ISA $VERSION);
use Date::Handler;
@ISA = qw(Date::Handler);
use constant DEFAULT_TIMEZONE => 'Europe/Moscow';
sub TimeZone
{
my ($self) = @_;
my $time_zone = $self->SUPER::TimeZone(@_);
return $time_zoneif defined $time_zone;
return $self->DEFAULT_TIMEZONE();
}
1;
__END__
BUGS (known)
Dates after 2038 are not handled by this module yet. (POSIX)
Dates before 1970 are not handled by this module. (POSIX)
If you find bugs with this module, do not hesitate to contact the author. Your comments and rants are welcomed :)
CVS AND BLEEDING VERSIONS
The latest developments and changes history for this module are available through cvsweb at:
http://cvs.flatlineconstruct.com/
The bleeding edge code is also available through anonymous CVS access via:
cvs -d:pserver:anoncvs@cvs.flatlineconstruct.com:/home/cvs/anon checkout Date-Handler
TODO
Add support for dynamic locale using perllocales functions. This will plugin directly with the use of strftime in the Date::Handler and provide locales.
Add a list of supported timezones in the Constants class.Just didnt around to do it yet :) Feel free :) If you have patches, recommendations or suggestions on this module, please come forward :)
COPYRIGHT
Copyright(c) 2001 Benoit Beausejour <bbeausej@pobox.com>
All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Portions Copyright (c) Philippe M. Chiasson <gozer@cpan.org>
Portions Copyright (c) Szabó, Balázs <dlux@kapu.hu>
Portions Copyright (c) Larry Rosler
AUTHOR
Benoit Beausejour <bbeausej@pobox.com>
SEE ALSO
Class::Date(1). Time::Object(1). Date::Calc(1). perl(1).
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 111:
Non-ASCII character seen before =encoding in '(Szabó,'. Assuming CP1252