
=head1 NAME

EasyToolTimeFunc - the time operate related function part of EasyTool

=head1 SYNOPSIS

	use EasyTool;
	
	if(defined(&EasyTool::foo)){
		print "lib is included";
	}else{
		print "lib is not included";
	}
	
	print EasyTool::time_2_str('1983-03-07 01:02:03','%yyyy-%MM-%%dd');
	print EasyTool::time_2_str('1983-03-07 01:02:03');
	print EasyTool::time_2_str('1983-03-07');
	print EasyTool::time_2_str('2004-08-28T08:06:00');
	print EasyTool::time_2_str('946656000');
	print EasyTool::time_2_str(' 1983-03-07 ');
	print EasyTool::time_2_str('1983-03-07T01:02:03');


	print EasyTool::is_time('1983-03-07 01:02:03');
	print  EasyTool::time_2_timestamp('1983-03-07 01:02:03');
	print EasyTool::hash_2_timestamp({year=>1983,month=>3,day=>7,hour=>1,min=>2,sec=>3});
	$rh_time=EasyTool::time_2_hash('1983-03-07 01:02:03'); #{year=>1983,month=>3,day=>7,hour=>1,min=>2,sec=>3}
	
	print EasyTool::now();
	print EasyTool::time();
	print EasyTool::datetime_now();
	print EasyTool::date_now();

	print day_of_month(2000,2); #29

	print EasyTool::timestamp_set('1983-03-07 01:02:03',{year=>1984,month=>5,day=>10,hour=>5,min=>7,sec=>9});#maybe 453013629
	print EasyTool::datetime_set('1983-03-07 01:02:03',{year=>1984,day=>10,min=>7});#'1984-03-10 01:07:03'
	print EasyTool::date_set('1983-03-07 01:02:03'',{month=>5,hour=>5,sec=>9});#'1983-05-07'
	
	print EasyTool::timestamp_add('1983-03-07 01:02:03',{year=>1,month=>2,day=>3,hour=>4,min=>5,sec=>6});#maybe 453013629
	$datetime=EasyTool::datetime_add('1983-03-07 01:02:03',{year=>1,day=>3,min=>5});#'1984-03-10 01:07:03'
	$date=EasyTool::date_add('1983-03-07 01:02:03',{month=>2,hour=>4,sec=>6});#'1983-05-07'
	
I<The synopsis above only lists the major methods and parameters.>

=head1 DESCRIPTION 

The EasyTool module aims to provide a easy to use, easy to port function set

you can copy and paste some function to embed into your code as easy as possiable
youc can also make some modification on function as you need

this package inlcude the time operate related function part of EasyTool

=head2 Fisrt of All

	support time from 1971 to 2037
	if you want more function,please use EasyDateTime
	the time zone used in these function is server local time zone

=head2 Notation and Conventions 

=head3 function name

	the 'time' in function name means time_str, please read the description of $time_str

=head3 param and return value

	$time_str: $time_str is the string as be accept as a time 

		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'
		'946656000'

		Which string can be accepted?
		rule 0: Unix Timestamp, an int represent seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) can be accepted
		rule 1: there can be some blank in the begin or end of string 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
	
	
	$timestamp : unix timestamp, an integer like 946656000
	$datetime  : date time string, a string, like '2004-08-28 08:06:00'
	$date      : date string, a string like, like '2004-08-28'

	$rh_time   : a hash represent a time
	$rh_time is a struct like {year=>2000,month=>1,day=>1,hour=>0,min=>0,sec=>0}
	if some item in $rh_time is not set ,use default value instead
	default values: year=>2000,month=>1,day=>1,hour=>0,min=>0,sec=>0
	
	$rh_offset : a hash represent the offset in two times
	$rh_offset is a struct like {year=>0,month=>0,day=>0,hour=>0,min=>0,sec=>0}
	if some item in $rh_offset is not set ,use zero instead, integer can be negative
	one month: {month=>1} 
	one day  : {day=>1}
	one month and one day: {month=>1,day=>1}
	when you add a time with $rh_offset such as {year=>0,month=>0,day=>0,hour=>0,min=>0,sec=>0}, it will add second first,then
		miniute, hour, day, month, year
	
	$template option:
	#===FORMAT
	#%datetime   return string like '2004-08-28 08:06:00'
	#%date       return string like '2004-08-28'
	#%timestamp  return unix timestamp
	
	#===YEAR
	#%yyyy       A full numeric representation of a year, 4 digits(2004)
	#%yy         A two digit representation of a year(04)
	
	#===MONTH
	#%MM         Numeric representation of a month, with leading zeros (01..12)
	#%M          Numeric representation of a month, without leading zeros (1..12)
	
	#===DAY
	#%dd         Day of the month, 2 digits with leading zeros (01..31)
	#%d          Day of the month without leading zeros (1..31)
	
	#===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)
	
	$bool: 1 for true and '' for false

=head3 extra knowledge
	
	AM and PM - What is Noon and Midnight?
	AM and PM start immediately after Midnight and Noon (Midday) respectively.
	This means that 00:00 AM or 00:00 PM (or 12:00 AM and 12:00 PM) have no meaning.
	Every day starts precisely at midnight and AM starts immediately after that point in time e.g. 00:00:01 AM (see also leap seconds)
	To avoid confusion timetables, when scheduling around midnight, prefer to use either 23:59 or 00:01 to avoid confusion as to which day is being referred to.
	It is after Noon that PM starts e.g. 00:00:01 PM (12:00:01)

=head1 basic function

=head2 foo - check whether this module is be used

	if(defined(&EasyTool::foo)){
		print "lib is included";
	}else{
		print "lib is not included";
	}

=head2 time_2_str - format output time string

	$format_str=EasyTool::time_2_str($time_str[,$template])
	time_2_str($time_str) return str sush as '2000-01-01 00:00:00'
	time_2_str($time_str,'%yyyy-%MM-%dd') return str sush as '2000-01-01'

=head2 is_time - whether this is a valid time string

	$bool=EasyTool::is_time($time_str)

=head2 time_2_timestamp - input is $time_str output is unix timestamp

	$timestamp=EasyTool::time_2_timestamp($time_str)

=head2 hash_2_timestamp - input is hash output is unix timestamp

	$timestamp=EasyTool::hash_2_timestamp($rh_time)

=head2 time_2_hash

	$rh_time=EasyTool::time_2_hash($time_str)

=head2 get time of now

	$timestamp=EasyTool::now();
	$timestamp=EasyTool::time();
	$datetime=EasyTool::datetime_now();
	$date=EasyTool::date_now();

=head2 day_of_month - get day count of specified month

	$day_count=day_of_month($year,$month)

=head2 set time funcion
	
	$timestamp=EasyTool::timestamp_set($time_str,$rh_time);
	$date=EasyTool::date_set($time_str,$rh_time);
	$datetime=EasyTool::datetime_add($time_str,$rh_offset)

=head2 time operate funcion

	$timestamp=EasyTool::timestamp_add($time_str,$rh_offset);
	$datetime=EasyTool::datetime_add($time_str,$rh_offset);
	$date=EasyTool::date_add($time_str,$rh_offset)

=head1 COPYRIGHT

The EasyTool module is Copyright (c) 2003-2005 QIAN YU.
All rights reserved.

You may distribute under the terms of either the GNU General Public
License or the Artistic License, as specified in the Perl README file.
