NAME
Date::Object - Handles dates/calendars/timezones and it's representation/convertions using a single Date::Object.
DESCRIPTION
Date::Object is an alternative to the DateTime modules, with the main pourpose to handle dates using a single object or make multiple Date::Objects work together to calculate and handle dates.
Other main poupose of Date::Object is to find a simple way to store dates in a persistent enverioment (any database) using a simple INTEGER field. The use of a INTEGER field for that make possible searches in the DB by ranges, what is impossible with normal storages of dates, specially if they are saved as STRING, generally in the comon format of "YYYY-MM-DD". Also an INTEGER field have all the informations of a date, including year, month, day, hour, minute, second and timezone. Other good thing is that any DB supports INTEGER fields, what doesn't make our Perl code dependent of the SQL nuances of each different way to handle dates of each DB.
See the method serail() for DB usage.
USAGE
use Date::Object ;
...
my $date = new Date::Object( time() ) ;
my $date2 = new Date::Object( $date ) ;
...
my $date = new Date::Object( 2004 , 2 , 29 , 12 , 30 , 10 ) ;
print $date->date ; ## 2004-02-29 12:30:10
$date->set_local ;
...
$date->set_zone(-3) ;
print $date->date ; ## 2004-02-29 09:30:10
...
print $date->year ;
print $date->month ;
print $date->day ;
...
print "$date->{year}\n" ;
print "$date->{month}\n" ;
print "$date->{hour}\n" ;
...
print $date->hour ; ## hh:mm:ss
...
print $date->ymd ; ## yyyy-mm-dd
print $date->mdy ; ## mm-dd-yyyy
print $date->dmy ; ## dd-mm-yyyy
print $date->hms ; ## hh:mm:ss
...
if ( $date_0 == $date_1 ) {...}
if ( $date_0 > $date_1 ) {...}NEW
To create a Date::Object you can use different types of arguments:
- TIME
-
Date::Object->new( time() ) ; - YEAR , MONTH , DAY , HOUR , MIN , SEC , ZONE
-
Date::Object->new( 2004 , 12 , 25 , 15 , 30 , 59 ) ; - Date::Object
-
Date::Object->new( $another_date_object ) ; - NULL
-
When arguments are not sent the actual time() will be used.
You also can use this extra contructors to handle the timezone and the serial:
new_gmt
Create a new Date::Object in the GMT timezone.
my $d_gmt = Date::Object::new_gmt() ;new_local
Create a new Date::Object in the local timezone.
my $d_gmt = Date::Object::new_local() ;new_zone(ZONE , ...)
Create a new Date::Object in the given ZONE (timezone).
Examples:
my $d0 = Date::Object::new_zone(-3) ;
my $d1 = Date::Object::new_zone(-3 , 2004 , 1 , 1 , 12 , 30 , 00) ;
...
my $d_gmt = Date::Object::new_gmt() ;
my $d_local = Date::Object::new_zone(-3 , $d_gmt) ;new_serial(SERIAL)
Create a new Date::Object using a serial INTEGER. See serial() for more.
METHODS
add_day (N)
Add N days in the date. By default N is 1.
add_hour
Add N hours in the date. By default N is 1.
add_min
Add N minutes in the date. By default N is 1.
add_month
Add N months in the date. By default N is 1.
Note that this is not the same to add 30 days! The function will make a plus only in the month, and will incremente automatically the year and also will handle the month days if needed, like Feb-29.
add_sec
Add N seconds in the date. By default N is 1.
add_week
Add N weeks in the date. By default N is 1.
add_year
Add N years in the date. By default N is 1.
check (YEAR , MONTH , DAY)
Check if a given date exists. Returns BOOLEAN.
Also can be used as a static method/function.
clone
Return a copy of the previous object.
date
Return the date in the format:
YYYY-MM-DD HH:MM:SSExample:
2004-03-20 23:20:34date_zone
Return the date in the format:
YYYY-MM-DD HH:MM:SS ZONEExample:
2004-03-20 23:20:34 -0300day
Return the day of the date.
days_between (DATEOBJECT | DATE )
Return the number of days between 2 date objects.
Example of use:
my $d0 = Date::O(2004 , 1 , 1) ;
my $d1 = Date::O(2005 , 1 , 1) ;
if ( $d0->days_between($d1) == 366 ) {...}days_from
Return the number of days from a given date.
days_until
Return the number of days until a given date.
dmy
Return the date in the format:
DD-MM-YYYYgmtime(TIME)
Return the same values of the core function gmtime(), but the values will be formated, soo, in the year 1900 will be added, to month 1 is added, and numbers less than 10 0 will be added in the begin:
my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = Date::O()->gmtime ;
print "$sec,$min,$hour , $mday,$mon,$year , $wday,$yday,$isdst\n" ;The output:
21,05,00 , 21,03,2004 , 0,80,0hms
Return the date in the format:
HH:MM:SShour
The hour of the date.
hours_between
See days_between().
hours_from
See days_from().
hours_until
See days_until().
isdst
Is true if the specified time occurs during daylight savings time.
localtime
Same as gmtime(), but fot the local timezone.
See gmtime().
mdy
Return the date in the format:
MM-DD-YYYYmin
The minutes of the date.
min_between
See days_between().
min_from
See days_from().
min_until
See days_until().
month
The month of the date.
months_between
See days_between().
months_from
See days_from().
months_until
See days_until().
sec
The seconds of the date.
secs_between
See days_between().
secs_from
See days_from().
secs_until
See days_until().
serial
Return a serial number that can be used to serialize this date object.
Useful to save in some database, and to realod it in the future.
The serial is an INTEGER based in the time() of the date and the zone in the end. Soo, you can make searches in the DB by ranges of dates:
my $d_init = Date::Object::new(2004 , 1 , 1) ;
my $d_end = Date::Object::new(2004 , 2 , 1) ;
...
my $init = $d_init->serial ;
my $end = $d_end->serial ;
"SELECT * FROM foo WHERE (date >= $init && date <= $end)"To save it in the DB:
my $d_serial = $d_init->serial ;
...
"INSERT INTO foo(date) values($d_serial)"To load:
my $d_serial = "SELECT date FROM foo WHERE (id == 1)" ;
my $date = Date::Object::new_serial($d_serial) ;set_gmt
Set the date to the GMT timezone (0).
set_local
Set the date to the local timezone.
set_zone (ZONE)
Set the date to a ginve ZONE (timezone).
sub_day
See add_day().
sub_hour
See add_hour().
sub_min
See add_min().
sub_month
See add_month().
sub_sec
See add_sec().
sub_week
See add_week().
sub_year
See add_year().
time
The time of the date, with all the seconds from 1970-1-1 until the date, same format of the core function time().
timelocal (YEAR , MONTH , DAY , HOUR , MIN , SEC , ZONE)
Create a time() integer with the given arguments.
wday
The week day of the date, in the range of 0..6, where 0 is Sunday.
weeks_between
See days_between().
weeks_from
See days_from().
weeks_until
See days_until().
yday
The year day of the date, in the range of 0..364 (or 0..365).
year
The year day of the date. Example: 2004
years_between
See days_between().
years_from
See days_from().
years_until
See days_until().
ymd
Return the date in the format:
YYYY-MM-DDzone
Return the zone of the date. The format is a floating number. Soo, for the timzone -0300, the number is -3, and for -0330 is -3.3
zone_gmt
The timezone from the GMT as a full string.
Format:
[+-]HHMMExamples:
-0300
+0000ALIASES
Date::O
Date::Object->new
Date::O_gmt
Date::Object->new_gmt
Date::O_local
Date::Object->new_local
Date::O_zone
Date::Object->new_zone
Date::check
Date::Object::check
Date::timelocal
Date::Object::timelocal
y
$date->year
mo
$date->month
d
$date->day
h
$date->hour
m
$date->min
s
$date->sec
z
$date->zone
SEE ALSO
The Perl DateTime Project: http://datetime.perl.org
Class::HPLOO
This module was built with Class::HPLOO, that make Classes definition easier and smaller in Perl.
When sending patches or any type of code for this module take a look in the sources in the .hploo files, and not in the .pm, since the .pm files are generated automatically from the .hploo files.
AUTHOR
Graciliano M. P. <gm@virtuasites.com.br>
I will appreciate any type of feedback (include your opinions and/or suggestions). ;-P
COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.