NAME

EasyDateTime - A date and time object

SYNOPSIS

    use EasyDateTime;

    # Constructors
    $dt = EasyDateTime->new({year=>2000,month=>1,day=>1,hour=>0,min=>0,sec=>0,timezone=>8});
    $dt = EasyDateTime->new('2004-08-28 08:06:00'); #date can be seperate by . / or -
    $dt = EasyDateTime->new('2004-08-28T08:06:00',8);
    $dt = EasyDateTime->new('2004/08/28 08:06:00',8); #the second param is timezone
    $dt = EasyDateTime->new('2004/8/28'); #the time will be filled 00:00:00
    $dt = EasyDateTime->new('8:6:00 '); #the date will be filled 2000-01-01
    
    # getter and setter
    $dt->year();
    $dt->year(2004);
    $dt->month();
    $dt->month(3);
    $dt->day();
    $dt->day(24);
    $dt->hour();
    $dt->hour(8);
    $dt->min();
    $dt->min(20);
    $dt->sec();
    $dt->sec(30);
    $dt->timezone();
    $dt->timezone(8);
    
    # clone & lock
    $dt2=$dt->clone(); #create new instance copy from this instance
    $dt->lock(); #set $dt read only
    
    # now localtimezone validate
    $dt=EasyDateTime->now(); #use the time of now to create a instance
    $dt=EasyDateTime->now(8); #use timezone 8 and time of now to create a instance
    print $dt->localtimezone(); #print the localtimezone of server that run this script;
    EasyDateTime->validate('2004-08-28T08:06:00'); #check whether this string is a valid datetime_str
    EasyDateTime->validate({year=>2000,month=>1,day=>1});
    
    # other func
    $dt->to_end_of_month();

    # format output
    $dt->str(); #'2004-08-28 08:06:00'
    $dt->str('%yyyy%MM'); #'200408'

    # operator overload
    $dt2=$dt+3600; #$dt2=$dt + 3600 seconds
    $dt2=$dt+{day=>1};
    $dt2=$dt+{month=>1};
     #attention sometime this func will fail when for example $dt = '2004-10-31'
     #if you want to goto [next] end of month use to_end_of_month instead
    $dt2=$dt-3000;
    $sec_count=$dt2-$dt; #return interval of $dt2 and $dt by seconeds
    $dt2=$dt-{day=>1};
	
    $dt+={day=>1};
    $dt+=3600;
    $dt-={day=>1};
    $dt-=3600;
	
    print $dt2>$dt1; #overload operator <=> and cmp, and '2004-01-01 00:00:00' > '2003-01-01 00:00:00'

DESCRIPTION

EasyDateTime is a class for the representation of date/time combinations.
It's simple to use,and function is enough for daily use.
Only one file ,and don't denpend on external module,and system independent.

EXAMPLES

This example how to get the start of month

$dt->set{day=>1,hour=>0,min=>0,sec=>0}; #2004-08-01 00:00:00

This example how to get the end of month

$dt->to_end_of_month(); #2004-08-31 00:00:00

This example how to get the next of month

$dt->to_end_of_month(1); #2004-09-30 00:00:00

This example how to explore every day of month

$dt_start=EasyDateTime->new('2004-08-01 00:00:00');
$dt_end=$dt_start->clone();
$dt_end->to_end_of_month();
for($dt=$dt_start->clone();$dt<$dt_end;$dt+={day=>1}){
... ...
};

This example how to explore every month of year

$dt_start=EasyDateTime->new('2004-01-01 00:00:00');
$dt_end=$dt_start->clone();
$dt_end+={year=>1};
for($dt=$dt_start->clone();$dt<$dt_end;$dt+={month=>1}){
... ...
};

This example how to explore every last day of month of year

$dt_start=EasyDateTime->new('2004-01-01 00:00:00');
$dt_end=$dt_start->clone();
$dt_start->to_end_of_month();
$dt_end+={year=>1};
for($dt=$dt_start->clone();$dt<$dt_end;$dt->to_end_of_month(1)){
... ...
};

This example how to lock a EasyDateTime instance

$dt->lock();
$dt+={day=>1};#this will cause die for u cannot changed the value of a locked instance

Bad example

for($dt=$dt_start;$dt>$dt_end;$dt+={day=>1}){
... ...
}

because $dt and $dt_start is reference the same instance,
when u changed the value of $dt, $dt_start is also changed
so u use assignment without clone is DANGEROUS!!!!
and in case other won't change ur $dt, u can use lock() to set $dt read only

CONSTRUCTOR

new(RH_DATETIME)

Example:
    $dt = EasyDateTime->new({year=>2000,month=>1,day=>1,hour=>0,min=>0,sec=>0,timezone=>8});
    $dt = EasyDateTime->new({year=>2000,month=>1,day=>1});
    $dt = EasyDateTime->new({hour=>0,min=>0,sec=>0});

new(DATETIME_STR[,$TIMEZONE])

Example:
    $dt = EasyDateTime->new('2004-08-28 08:06:00',8);
    $dt = EasyDateTime->new('2004-08-28 08:06:00');
    $dt = EasyDateTime->new(' 2004-08-28 08:06:00 ');
    $dt = EasyDateTime->new('2004-08-28T08:06:00');
    $dt = EasyDateTime->new('2004/08/28 08:06:0');
    $dt = EasyDateTime->new('2004.08.28 08:06:00');
    $dt = EasyDateTime->new('2004-08-28 08.06.00');
    $dt = EasyDateTime->new('04-8-28 8:6:0');
    $dt = EasyDateTime->new('2004-08-28');
    $dt = EasyDateTime->new('08:06:00');

METHODS

year ([$YEAR])

get or set the year of EasyDateTime instance
month ([$MONTH])

get or set the month of EasyDateTime instance
day ([$DAY])

get or set the day of EasyDateTime instance
hour ([$HOUR])

get or set the hour of EasyDateTime instance
min ([$MINUTE])

get or set the minute of EasyDateTime instance
sec ([$SECOND])

get or set the second of EasyDateTime instance
timezone ([$TIMEZONE])

get or set the second of EasyDateTime instance
time ()

return a integer Suitable for feeding to gmtime and localtime. Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
set (RH_DATETIME)

set the specified item of EasyDateTime instance,if item was not list in RH_DATETIME,then the item will stay same
to_end_of_month ([$MONTH_OFFSET])

set the time to the end of (the $MONTH_OFFSET th) month, for example, if $MONTH_OFFSET was not set or $MONTH_OFFSET==0 then set the time to the start of last day of this month if $MONTH_OFFSET==1 then set the time to the start of last day of next month
clone ()

make a copy of this EasyDateTime instance
lock ()

make this EasyDateTime instance read only, if a EasyDateTime instance was locked, then any operation trying to modify it will cause die
str ([FORMAT_STR])

return a formated string use the template FORMAT_STR if no FORMAT_STR set ,then use format '%yyyy-%MM-%dd %hh:%mm:%ss'
localtimezone ()

return localtimezone
now ([$TIMEZONE])

return a EasyDateTime instance represent the time of now,if $TIMEZONE not set, use localtimezone
validate(RH_DATETIME)
validate(DATETIME_STR)

check whether a RH_DATETIME or a DATETIME_STR is valid

PARAMETER

RH_DATETIME

RH_DATETIME is a reference of hash like 
    {year=>2000,month=>1,day=>1,hour=>0,min=>0,sec=>0,timezone=>8}
it represent a datetime ,if some item is not set, will use default value instead
	default value of year is 2000
	default value of month is 1
	default value of day is 1
	default value of hour is 0
	default value of min is 0
	default value of sec is 0
	default value of timezone is the localtimezone of machine

RH_TIMEINTERVAL

    RH_DATETIME is a reference of hash like 
	    {year=>0,month=>0,day=>0,hour=>0,min=>0,sec=>0}
	it represent the interval between two datetime if some item is not set, will use default value instead
		default value of year is 0
		default value of month is 0
		default value of day is 0
		default value of hour is 0
		default value of min is 0
		default value of sec is 0

DATETIME_STR

Samples can be accepted

'2004-08-28 08:06:00' ' 2004-08-28 08:06:00 '
'2004-08-28T08:06:00' '2004/08/28 08:06:00'
'2004.08.28 08:06:00' '2004-08-28 08.06.00'
'04-8-28 8:6:0' '2004-08-28' '08:06:00'

Which string can be accepted?

rule 1:there can be some blank in the begin or end of DATETIME_STR e.g. ' 2004-08-28 08:06:00 '
rule 2:date can be separate by . / or - e.g. '2004/08/28 08:06:00'
rule 3:time can be separate by . or : e.g. '2004-08-28 08.06.00'
rule 4:date and time can be join by white space or 'T' e.g. '2004-08-28T08:06:00'
rule 5:can be (date and time) or only date or only time e.g. '2004-08-28' or '08:06:00'
rule 6:year can be 2 digits or 4 digits,other field can be 2 digits or 1 digit e.g. '04-8-28 8:6:0'
rule 7:if only the date be set then the time will be set to 00:00:00
       if only the time be set then the date will be set to 2000-01-01

Regular Expression

^\s*(\d{4}|\d{2})([\-\.\/])(\d{1,2})\2(\d{1,2})(\x20+|T)(\d{1,2})([\:\.])(\d{1,2})\7(\d{1,2})\s*$
^\s*(\d{4}|\d{2})([\-\.\/])(\d{1,2})\2(\d{1,2})\s*$
^\s*(\d{1,2})([\:\.])(\d{1,2})\2(\d{1,2})\s*$

FORMAT_STR

YEAR

%yyyy

A full numeric representation of a year, 4 digits(2004)
%yy

A two digit representation of a year(04)
%is_leap

Whether it's a leap year(0 or 1)

MONTH

%MM

Numeric representation of a month, with leading zeros (01..12)
%M

Numeric representation of a month, without leading zeros (1..12)
%MN

A full textual representation of a month (January through December)
%MA

A short textual representation of a month, three letters (Jan through Dec)
%DM

Number of days in the given month (28..31)

DAY

%dd

Day of the month, 2 digits with leading zeros (01..31)
%d

Day of the month without leading zeros (1..31)
%yday

The day of the year (starting from 0)
%wday

Numeric representation of the day of the week(start from 0, sunday=0)
%dn

A full textual representation of the day of the week (Sunday through Saturday)
%da

A textual representation of a day, three letters (Mon through Sun)

HOUR

%h12

12-hour format of an hour without leading zeros (1..12)
%h

24-hour format of an hour without leading zeros (0..23)
%hh12

12-hour format of an hour with leading zeros (01..12)
%hh

24-hour format of an hour with leading zeros (00..23)
%ap

a Lowercase Ante meridiem and Post meridiem (am or pm)
%AP

Uppercase Ante meridiem and Post meridiem (AM or PM)

MINUTE

%mm

Minutes with leading zeros (00..59)
%m

Minutes without leading zeros (0..59)

SECOND

%ss

Seconds, with leading zeros (00..59)
%s

Seconds, without leading zeros (0..59)

TIMEZONE

%tz

Difference to Greenwich time (GMT) in hours
%ts

Timezone offset in seconds
%lt

Timezone setting of this machine
%tn1

A textual representation of the timezone (GMT+02:00)
%tn2

A textual representation of the timezone (+0200)
%tn3

A textual representation of the timezone (+02:00)

FULL DATETIME

%date

string like '2004-08-06'
%time

A textual representation of the timezone (+02:00)
%iso1861

string like '2004-02-12T15:19:21+00:00'
%rfc2822

string like 'Thu, 21 Dec 2000 16:01:07 +0200'
%datetime

string like '2004-08-06 03:02:01'

OTHER

%%

%

LIMITATION

the datetime is limited in the year 1900 to 2037

AUTHOR

Qian Yu <foolfish@cpan.org>

COPYRIGHT

The full text of the license can be found in the LICENSE file included with this module.

To install EasyDateTime, copy and paste the appropriate command in to your terminal.

cpanm

cpanm EasyDateTime

CPAN shell

perl -MCPAN -e shell
install EasyDateTime

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)