Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Date::Pcalc::Object(3)User Contributed Perl DocumentatioDate::Pcalc::Object(3)

NAME
       Date::Pcalc::Object - Object-oriented add-on for	Date::Pcalc with
       overloaded operators

MOTTO
       Make frequent things easy and infrequent	or hard	things possible

PREFACE
       Note that you do	NOT need to ""use Date::Pcalc qw(...);"" in addition
       to this module.

       Simply

	 use Date::Pcalc::Object qw(...);

       INSTEAD OF

	 use Date::Pcalc qw(...);

       with the	same ""qw(...)"" as you	would with the "Date::Pcalc" module,
       and then	forget about "Date::Pcalc::Object" altogether.

       The rest	of your	existing code doesn't change at	all.

       Note also that in order to create a new date object, you	do not need to
       use

	 $date_object =	Date::Pcalc::Object->new(...);

       (but you	may), and should use

	 $date_object =	Date::Pcalc->new(...);

       instead (saves you some typing and is a trifle faster).

SYNOPSIS
   Export tags
	 :all  -  all functions	from Date::Pcalc
	 :aux  -  auxiliary functions shift_*
	 :ALL  -  both :all and	:aux

   Functions
       See Date::Pcalc(3) for a	list of	available functions.

	 $year				= shift_year(\@_);
	 ($year,$mm,$dd)		= shift_date(\@_);
	 ($hrs,$min,$sec)		= shift_time(\@_);
	 ($year,$mm,$dd,$hrs,$min,$sec)	= shift_datetime(\@_);

   Methods
	 $old =	Date::Pcalc->accurate_mode([FLAG]);
	 $old =	Date::Pcalc->normalized_mode([FLAG]);
	 $old =	Date::Pcalc->number_format([NUMBER|CODEREF]);
	 $old =	Date::Pcalc->delta_format([NUMBER|CODEREF]);  #	global default
	 $old =	Date::Pcalc->date_format([NUMBER|CODEREF]);   #	global default
	 $old =	Date::Pcalc->language([LANGUAGE]);	      #	global default - DEPRECATED

	 $old =	$date->accurate_mode([FLAG]);		# is global nevertheless!
	 $old =	$date->normalized_mode([FLAG]);		# is global nevertheless!
	 $old =	$date->number_format([NUMBER|CODEREF]);	# is global nevertheless!
	 $old =	$date->delta_format([NUMBER|CODEREF]);	# individual override
	 $old =	$date->date_format([NUMBER|CODEREF]);	# individual override
	 $old =	$date->language([LANGUAGE]);		# individual override

	 $flag = $date->is_delta();
	 $flag = $date->is_date();
	 $flag = $date->is_short(); # i.e., has	no time	part
	 $flag = $date->is_long();  # i.e., has	time part
	 $flag = $date->is_valid();

	 $date = Date::Pcalc->new([TYPE]);
	 $date = Date::Pcalc->new([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
	 $date = Date::Pcalc->new($arrayref);
	 $newdate = $somedate->new([TYPE]);
	 $newdate = $somedate->new([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
	 $newdate = $somedate->new($arrayref);

	 $datecopy = $date->clone();
	 $targetdate->copy($sourcedate);
	 $targetdate->copy($arrayref);
	 $targetdate->copy(@list);

	 ($year,$month,$day) = $date->date([TYPE]);
	 ($year,$month,$day) = $date->date([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
	 ($year,$month,$day) = $date->date($arrayref);
	 ([$hrs,$min,$sec])  = $date->time([TYPE]);
	 ($hrs,$min,$sec)    = $date->time([TYPE,]HRS,MIN,SEC);
	 ([$hrs,$min,$sec])  = $date->time($arrayref);

	 ($year,$month,$day,$hrs,$min,$sec) =
	     $date->datetime([TYPE]);
	 ($year,$month,$day,$hrs,$min,$sec) =
	     $date->datetime([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);

	 $date	= Date::Pcalc->today([FLAG]);
	 $date	= Date::Pcalc->now([FLAG]); # shorthand	for --+
	 $date	= Date::Pcalc->today_and_now([FLAG]); #	<-----+
	 $date	= Date::Pcalc->gmtime([time]);	  # UTC/GMT
	 $date	= Date::Pcalc->localtime([time]); # local time
	 $delta	= Date::Pcalc->tzoffset([time]);
	 $date	= Date::Pcalc->time2date([time]); # UTC/GMT

	 $date->today([FLAG]);	       # updates the date part only
	 $date->now([FLAG]);	       # updates the time part only
	 $date->today_and_now([FLAG]); # updates both date and time
	 $date->gmtime([time]);	       # updates both date and time (UTC/GMT)
	 $date->localtime([time]);     # updates both date and time (local time)
	 $delta->tzoffset([time]);     # updates both date and time
	 $date->time2date([time]);     # updates both date and time (UTC/GMT)

	 $time = Date::Pcalc->mktime();	   # same as "$time = CORE::time();"
	 $time = Date::Pcalc->date2time(); # same as "$time = CORE::time();"

	 $time = $date->mktime();      # converts into Unix time (local	time)
	 $time = $date->date2time();   # converts into Unix time (UTC/GMT)

	 $year	  = $date->year([YEAR]);
	 $month	  = $date->month([MONTH]);
	 $day	  = $date->day([DAY]);
	 $hours	  = $date->hours([HRS]);
	 $minutes = $date->minutes([MIN]);
	 $seconds = $date->seconds([SEC]);

	 $number = $date->number([NUMBER|CODEREF]);
	 $string = $date->string([NUMBER|CODEREF][,LANGUAGE]);

	 $delta->normalize(); #	renormalizes a delta vector

   Overloaded Operators
	 #####################################################
	 # Scalar operands are always converted	into a delta #
	 # vector with that many days, i.e., [1,0,0,SCALAR]  #
	 #####################################################

   Comparison Operators:
	 if ($date1 <  $date2) { # compares date part only
	 if ($date1 <= $date2) { # compares date part only
	 if ($date1 >  $date2) { # compares date part only
	 if ($date1 >= $date2) { # compares date part only
	 if ($date1 == $date2) { # compares date part only
	 if ($date1 != $date2) { # compares date part only

	 $comp = $date1	<=> $date2; # compares date part only

	 if ($date1 lt $date2) { # compares both date and time
	 if ($date1 le $date2) { # compares both date and time
	 if ($date1 gt $date2) { # compares both date and time
	 if ($date1 ge $date2) { # compares both date and time
	 if ($date1 eq $date2) { # compares both date and time
	 if ($date1 ne $date2) { # compares both date and time

	 $comp = $date1	cmp $date2; # compares both date and time

       Note that you can of course also	compare	two deltas, but	not a date and
       a delta!

	 ##################################################
	 # Default TYPE	for array refs in comparisons is: #
	 # Same	as other operand			  #
	 ##################################################

	 if ([2000,4,1]	== $date) {
	 if ($today > [2000,4,1]) {

	 if ($now ge [2000,3,26,2,0,0])	{

	 if ($delta == [18,0,0]) {
	 if ($delta == -1) {

   Plus:
	 $date2	= $date1 + $delta;
	 $date2	= $delta + $date1;
	 $date += $delta;
	 $this = $date++;
	 $next = ++$date;

	 $delta3 = $delta1 + $delta2;
	 $delta1 += $delta2;
	 $delta	+= $date; # beware of implicit type change!
	 $delta++;
	 ++$delta;

	 #####################################################
	 # Default TYPE	for array refs in '+' operations is: #
	 # Opposite of other operand			     #
	 #####################################################

	 $date2	= [2000,3,26] +	$delta;
	 $date2	= $date1 + [+1,0,0];
	 $date2	= [0,0,-1] + $date1;
	 $date2	= $date1 + 1;
	 $date += [0,0,+1];
	 $date += 2;

	 $delta3 = [1,+1,0,-1] + $delta2;
	 $delta3 = $delta1 + [1,0,0,+1];
	 $delta3 = $delta1 + 1;
	 $delta	+= [1,0,+1,0];
	 $delta	+= [2000,3,26];	# beware of implicit type change!
	 $delta	+= 7;

   Unary Minus:
	 $delta2 = -$delta1;

   Minus:
	 $delta	= $date2 - $date1;
	 $date2	= $date1 - $delta;
	 $date -= $delta;
	 $date2	-= $date1; # beware of implicit	type change!
	 $this = $date--;
	 $prev = --$date;

	 $delta3 = $delta2 - $delta1;
	 $delta2 -= $delta1;
	 $delta--;
	 --$delta;

	 #####################################################
	 # Default TYPE	for array refs in '-' operations is: #
	 # Always a date				     #
	 #####################################################

	 $delta	= $today - [2000,3,26];
	 $delta	= [2000,4,1] - $date;
	 $date2	= [2000,3,26] -	$delta;
	 $date2	= $date1 - [1,0,0,+7];
	 $date2	= $date1 - 7;
	 $date -= [1,0,0,+1]; #	better add [0,0,-1] instead!
	 $date2	-= [2000,3,26];	# beware of implicit type change!
	 $date2	-= 1;

	 $delta3 = [1,0,+1,0] -	$delta1;
	 $delta3 = $delta2 - [1,0,0,-1];
	 $delta	-= [1,0,0,+1];
	 $delta	-= 7;

   Miscellaneous Operators:
	 $string = "$date";
	 $string = "$delta";

	 print "$date\n";
	 print "$delta\n";

	 if ($date) { #	date is	valid
	 if ($delta) { # delta is valid

	 $days = abs($date);
	 $diff = abs($delta); #	can be negative!

	 $diff = abs(abs($delta)); # always positive

DESCRIPTION
       o FLAG

	 "FLAG"	is either 0 (for "false") or 1 (for "true").

	 In the	case of	""accurate_mode()"" and	""normalized_mode()"", this
	 switches the corresponding mode on and	off (see further below for an
	 explanation of	what these are).

	 In the	case of	""today()"", ""now()"" and ""today_and_now()"",	a
	 "true"	value indicates	"GMT" (Greenwich Mean Time), as	opposed	to
	 local time, which is the default.

       o NUMBER

	 "NUMBER" is a number between 0	and 2 (for "number_format()" and
	 "number()") or	between	0 and 4	(for "delta_format()", "date_format()"
	 and "string()"), indicating which of the three/five predefined
	 formats, respectively,	should be used for converting a	date into
	 numeric representation	(needed	for comparing dates, for instance) or
	 string	representation.

	 Format	#0 is the default at startup and the simplest of all (and
	 should	be fastest to calculate, too).

	 The string representation of dates in format #0 also has the
	 advantage of being sortable in	chronological order (and of complying
	 with ISOA 8601).

	 (The numeric formats are (trivially) always sortable in chronological
	 order of course.)

	 The other formats are (mostly)	increasingly more sophisticated	(in
	 terms of esthetics and	computation time) with increasing number
	 (except for format #4):

	   Delta number	formats	(short):

	       0    13603
	       1    13603
	       2    13603

	   Delta string	formats	(short):

	       0    '+0+0+13603'
	       1    '+0	+0 +13603'
	       2    '+0Y +0M +13603D'
	       3    '+0	Y +0 M +13603 D'
	       4    '(0,0,13603)'

	   Date	number formats (short):

	       0    20010401
	       1    730576
	       2    730576

	   Date	string formats (short):

	       0    '20010401'
	       1    '01-Apr-2001'
	       2    'Sun 1-Apr-2001'
	       3    'Sunday, April 1st 2001'
	       4    '[2001,4,1]'

	   Delta number	formats	(long):

	       0    13603.012959
	       1    13603.012959
	       2    13603.0624884259

	   Delta string	formats	(long):

	       0    '+0+0+13603+1+29+59'
	       1    '+0	+0 +13603 +1 +29 +59'
	       2    '+0Y +0M +13603D +1h +29m +59s'
	       3    '+0	Y +0 M +13603 D	+1 h +29 m +59 s'
	       4    '(0,0,13603,1,29,59)'

	   Date	number formats (long):

	       0    20010401.082959
	       1    730576.082959
	       2    730576.354155093

	   Date	string formats (long):

	       0    '20010401082959'
	       1    '01-Apr-2001 08:29:59'
	       2    'Sun 1-Apr-2001 08:29:59'
	       3    'Sunday, April 1st 2001 08:29:59'
	       4    '[2001,4,1,8,29,59]'

	 If a number outside of	the permitted range is specified, or if	the
	 value is not a	code reference (see also the next section below	for
	 more details),	the default format #0 is used instead.

       o CODEREF

	 "CODEREF" is the reference of a subroutine which can be passed	to the
	 methods "number_format()", "delta_format()" and "date_format()" in
	 order to install a callback function which will be called
	 subsequently whenever a date (or delta) object	needs to be
	 (implicitly) converted	into a number or string.

	 This happens for instance when	you compare two	date objects, or when
	 you put a date	object reference in a string between double quotes.

	 Such a	"CODEREF" can also be passed to	the methods "number()" and
	 "string()" for	explicitly converting a	date object as desired.

       o LANGUAGE

	 "LANGUAGE" is either a	number in the range "[1..Languages()]",	or one
	 of the	strings	""Language_to_Text(1..Languages())"" (see also
	 Date::Pcalc(3)).

       o TYPE

	 "TYPE"	is 0 for a regular date	and 1 for a delta vector (a list of
	 year, month, day and optionally hours,	minutes	and seconds offsets).

       o Storage

	 "Date::Pcalc" objects are implemented as two nested arrays.

	 The "blessed" array (whose reference is the object reference you
	 receive when calling the "new()" method) contains an anonymous	array
	 at position zero and the object's data	in its remaining fields.

	 The embedded anonymous	array is used for storing the object's
	 attributes (flags).

	 Dates and delta vectors always	comprise either	3 or 6 data values:
	 Year, month, day plus (optionally) hours, minutes and seconds.

	 These values are stored in the	"blessed" array	at positions 1..3 or
	 1..6, respectively.

	 An object without the time values is therefore	called "short",	and an
	 object	having time values is called "long" throughout this manual.

	 Hint: Whenever	possible, if you do not	need the time values, omit
	 them, i.e., always use	the "short" form of the	object if possible,
	 this will speed up calculations a little (the short form uses
	 different (faster) functions for all calculations internally).

	 The embedded anonymous	array contains various flags:

	 At position zero, it contains the "TYPE" indicator which determines
	 whether the object is a date or a delta vector.

	 At position 1,	the object stores the "NUMBER" of one of the delta
	 vector	formats, or the	reference of a callback	function which
	 converts the contents of the object into string representation	if
	 it's a	delta vector, or "undef" if the	global settings	apply.

	 At position 2,	the object stores the "NUMBER" of one of the date
	 formats, or the reference of a	callback function which	converts the
	 contents of the object	into string representation if it's a date, or
	 "undef" if the	global settings	apply.

	 At position 3,	the object stores the "LANGUAGE" to be used for	all
	 conversions into strings (where applicable), or "undef" if the	global
	 language setting applies.

	 Note that your	callback functions (see	the section "Callback
	 Functions" further below for more details) should not pay attention
	 to this value at position 3, because they get a parameter which tells
	 them which language to	use (this is necessary in order	to allow
	 temporary overrides).

	 If your callback handlers use the "*_to_Text*"	functions (or any
	 other language-dependent function) from the "Date::Pcalc" module,
	 your handlers should pass on this language parameter to these
	 functions (and	not the	value from position 3).

	 Be reminded though that you should NEVER access the object's internal
	 data directly,	i.e., through their positional numbers,	but ALWAYS
	 through their respective accessor methods, e.g.:

		 year()
		 month()
		 day()
		 hours()
		 minutes()
		 seconds()
		 date()
		 time()
		 datetime()
		 is_delta()
		 is_date()
		 is_short()
		 is_long()
		 delta_format()
		 date_format()
		 language()

	 And although position 4 and onward in the embedded anonymous array is
	 currently unused, it might not	stay so	in future releases of this
	 module.

	 Therefore, in case you	need more attributes in	a subclass of the
	 "Date::Pcalc[::Object]" class,	I suggest using	values starting	at
	 positions a bit further up, e.g. 6, 8 or 10.

       o Invalid Dates

	 Only "new()" allows to	create objects containing possibly invalid
	 dates (needed for reading in and evaluating user input, for example).

       o Usage

	 The methods

		 accurate_mode()
		 normalized_mode()
		 number_format()
		 delta_format()
		 date_format()
		 language()
		 date()
		 time()
		 datetime()
		 year()
		 month()
		 day()
		 hours()
		 minutes()
		 seconds()

	 are used for reading as well as for setting attributes. They simply
	 return	the values in question if they are called without parameters.

	 The methods

		 accurate_mode()
		 normalized_mode()
		 number_format()
		 delta_format()
		 date_format()
		 language()

	 always	return the previous value if a new value is set. This allows
	 you to	change these values temporarily	and to restore their old value
	 afterwards more easily	(but you can also override the "format"	and
	 "language" settings directly when calling the "number()" or
	 "string()" method).

	 The methods

		 date()
		 time()
		 datetime()
		 year()
		 month()
		 day()
		 hours()
		 minutes()
		 seconds()

	 always	return the new values when the corresponding values have been
	 changed.

	 The method "date()" NEVER returns the time values (hours, minutes,
	 seconds) even if they have just been set using	this method (which the
	 method	optionally allows). Otherwise it would be very hard to predict
	 the exact number of values it returns,	which might lead to errors
	 (wrong	number of parameters) elsewhere	in your	program.

	 The method "datetime()" ALWAYS	returns	the time values	(hours,
	 minutes, seconds) even	if the object in question lacks	a time part.
	 In that case, zeros are returned for hours, minutes and seconds
	 instead (but the stored time part is left unchanged, whether it
	 exists	or not).

	 If you	do not provide values for hours, minutes and seconds when
	 using the method "date()" to set the values for year, month and day,
	 the time part will not	be changed (whether it exists or not).

	 If you	do not provide values for hours, minutes and seconds when
	 using the method "datetime()" to set the values for year, month and
	 day, the time part will be filled with	zeros (the time	part will be
	 created if necessary).

	 If the	object is short, i.e., if it does not have any time values,
	 the method "time()" returns an	empty list.

	 If the	object is short	and the	methods	"hours()", "minutes()" or
	 "seconds()" are used to set any of these time values, the object is
	 automatically promoted	to the "long" form, and	the other two time
	 values	are filled with	zeros.

	 The following methods can also	return "undef" under certain
	 circumstances:

		 delta_format()
		 date_format()
		 language()
		 is_delta()
		 is_date()
		 is_short()
		 is_long()
		 is_valid()
		 hours()
		 minutes()
		 seconds()
		 number()
		 string()

	 The methods "delta_format()", "date_format()" and "language()"	return
	 "undef" when they are called as object	methods	and no individual
	 override has been defined for the object in question.

	 The "is_*()" predicate	methods	return "undef" if the object in
	 question does not have	the expected internal structure. This can
	 happen	for instance when you create an	empty object with "new()".

	 When called without parameters, the methods "hours()",	"minutes()"
	 and "seconds()" return	"undef"	if the object in question does not
	 have a	time part.

	 The methods "number()"	and "string()" return "undef" if the object in
	 question is not valid (i.e., if "is_valid()" returns "undef" or
	 false).

	 And finally, the methods

		 copy()
		 today()
		 now()
		 today_and_now()
		 gmtime()
		 localtime()
		 tzoffset()
		 time2date()
		 normalize()

	 return	the object reference of	the (target) object in question	for
	 convenience.

       o Import/Export

	 Note that you can import and export Unix "time" values	using the
	 methods "gmtime()", "localtime()", "mktime()",	"date2time()" and
	 "time2date()",	both as	local time or as UTC/GMT.

       o Accurate Mode and Normalized Mode

	 The method "accurate_mode()" controls the internal flag which
	 determines which of two fundamental modes of operation	is used.

	 When set to true (the default at startup), delta vectors are
	 calculated to give the	exact difference in days between two dates.
	 The "year" and	"month"	entries	in the resulting delta vector are
	 always	zero in	that case.

	 If "accurate mode" is switched	off (when the corresponding flag is
	 set to	false),	delta vectors are calculated with year and month
	 differences.

	 E.g., the difference between "[1999,12,6]" and	"[2000,6,24]" is "[+0
	 +0 +201]" (plus 201 days) in accurate mode and	"[+1 -6	+18]" (plus
	 one year, minus 6 months, plus	18 days) when accurate mode is
	 switched off, and is "[+0 +6 +18]" (plus 6 months, plus 18 days) if
	 additionally, "normalized mode" is switched on.

	 The delta vector is calculated	by simply taking the difference	in
	 years,	the difference in months and the difference in days (if
	 "accurate mode" is switched off and if	"normalized mode" has not been
	 switched on). This is called "one-by-one" semantics or	"year-month-
	 day mode"; "YMD mode" for short.

	 When "normalized mode"	is switched on (while "accurate	mode" is
	 switched off),	the delta vector is calculated in a more complex way
	 involving the functions ""Add_Delta_YM()"" (for "truncation") and
	 ""Delta_Days()"".

	 Moreover, the result is normalized, i.e., the return values are
	 guaranteed to all have	the same sign (or to be	zero), and to all be
	 "minimal", i.e., not to exceed	the ranges "[-11..+11]"	for months,
	 "[-30..+30]" for days,	"[-23..+23]" for hours and "[-59..+59]"	for
	 minutes and seconds.

	 The rule is to	add these result values	to a date in a left-to-right
	 order,	and to truncate	invalid	intermediate dates, such as e.g.
	 "[2009,2,29]",	to the last valid day of that same month, e.g.
	 "[2009,2,28]".	This is	called "left-to-right with truncation"
	 semantics or "normalized mode"; "N_YMD	mode" for short.

	 The method "normalized_mode()"	controls the internal flag which
	 determines whether "YMD mode" is used (the default at startup,	for
	 reasons of backward compatibility) or "N_YMD mode".

	 Note that also	for reasons of backward	compatibility, this flag only
	 has effect when "accurate mode" is switched off.

	 Both flags can	be set and reset independently from each other,
	 however.

	 Therefore, at startup,	you can	for instance switch "normalized	mode"
	 on, without having any	immediate effect, and switch off "accurate
	 mode" later, which instantly also causes "normalized mode" to spring
	 into effect.

	 Because years and months have varying lengths in terms	of days, the
	 "YMD" and "N_YMD" modes are less accurate than	"accurate mode",
	 because these modes depend on the context of the two dates of which
	 the delta vector is the difference. Added to a	different date,	a
	 delta vector calculated in "YMD mode" or "N_YMD mode" may yield a
	 different offset in terms of days, i.e., the final result may
	 sometimes vary	seemingly unpredictably	(or in other situations	may
	 give you the expected result, at the expense of actually representing
	 a varying difference in days, determined exclusively by context).

	 Beware	also that - for	the same reason	- the absolute value
	 (""abs()"") of	a delta	vector returns a fictitious number of days if
	 the delta vector contains non-zero values for "year" and/or "month"
	 (see also the next section "Absolute Value" below for more details).

	 Example:

	 The difference	between	"[2000,1,1]" and "[2000,3,1]" is "[+0 +0 +60]"
	 in "accurate mode" and	"[+0 +2	+0]" in	"YMD mode" (in this "benign"
	 example, the result is	the same in "YMD mode" and in "N_YMD mode").

	 When added to the date	"[2000,4,1]", the "accurate" delta vector
	 yields	the date "[2000,5,31]",	whereas	the "YMD mode" delta vector
	 yields	the date "[2000,6,1]" (which is	actually a difference of 61
	 days).

	 Moreover, when	added to the date "[1999,1,1]",	the "accurate" delta
	 vector	yields the date	"[1999,3,2]", whereas the "inaccurate" "YMD
	 Mode" delta vector yields the date "[1999,3,1]" (which	is actually a
	 difference of 59 days).

	 Depending on what you want, either mode may suit you better.

       o Absolute Value

	 Note that ""abs($date)"" and ""abs($delta)"" are just shorthands for
	 ""$date->number()"" and ""$delta->number()"".

	 The operator ""abs()"", when applied to a date	or delta vector,
	 returns the corresponding number of days (see below for an exception
	 to this), with	the time part (if available) represented by a fraction
	 after the decimal point.

	 In the	case of	dates, the absolute value (to the left of the decimal
	 point)	is the number of days since the	1st of January 1A A.D. (by
	 extrapolating the Gregorian calendar back beyond its "natural"	limit
	 of 1582 A.D.) PLUS ONE.

	 (I.e.,	the absolute value of the 1st of January 1 A.D.	is 1.)

	 Exception:

	 If the	"NUMBER" or "number_format()" is set to	0 (the default
	 setting), the absolute	value of a date	to the left of the decimal
	 point is "yyyymmdd", i.e., the	number in which	the uppermost four
	 digits	correspond to the year,	the next lower two digits to the month
	 and the lowermost two digits to the day.

	 In the	case of	delta vectors, the absolute value (to the left of the
	 decimal point)	is simply the difference in days (but see also below).

	 Note that the absolute	value of a delta vector	can be negative!

	 If you	want a positive	value in all cases, apply the ""abs()""
	 operator again, i.e., ""$posdiff = abs(abs($delta));"".

	 If the	delta vector contains non-zero values for "year" and/or
	 "month" (see also the discussion of "Accurate Mode" in	the section
	 above), an exact representation in days cannot	be calculated, because
	 years and months do not have fixed equivalents	in days.

	 If nevertheless you attempt to	calculate the absolute value of	such a
	 delta vector, a fictitious value is returned, which is	calculated by
	 simply	multiplying the	year difference	with 12, adding	the month
	 difference, multiplying this sum with 31 and finally adding the day
	 difference.

	 Beware	that because of	this, the absolute values of delta vectors are
	 not necessarily contiguous.

	 Moreover, since there is more than one	way to express the difference
	 between two dates, comparisons	of delta vectors may not always	yield
	 the expected result.

	 Example:

	 The difference	between	the two	dates "[2000,4,30]" and	"[2001,5,1]"
	 can be	expressed as "[+1 +1 -29]", or as "[+1 +0 +1]".

	 The first delta vector	has an absolute	value of 374, whereas the
	 latter	delta vector has an absolute value of only 373 (while the true
	 difference in days between the	two dates is 366).

	 If the	date or	delta vector has a time	part, the time is returned as
	 a fraction of a full day after	the decimal point as follows:

	 If the	"NUMBER" or "number_format()" is set to	0 (the default
	 setting) or 1,	this fraction is simply	".hhmmss", i.e., the two
	 digits	after the decimal point	represent the hours, the next two
	 digits	the minutes and	the last two digits the	seconds.

	 Note that you cannot simply add and subtract these values to yield
	 meaningful dates or deltas again, you can only	use them for
	 comparisons (equal, not equal,	less than, greater than, etc.).	If you
	 want to add/subtract, read on:

	 Only when the "NUMBER"	or "number_format()" is	set to 2, this
	 fraction will be the equivalent number	of seconds (i.e., "(((hours *
	 60) + minutes)	* 60) +	seconds") divided by the number	of seconds in
	 a full	day (i.e., "24*60*60 = 86400"),	or "0/86400", "1/86400", ... ,
	 "86399/86400".

	 In other words, the (mathematically correct) fraction of a day.

	 You can safely	perform	arithmetics with these values as far as	the
	 internal precision of your vendor's implementation of the C run-time
	 library (on which Perl	depends) will permit.

       o Renormalizing Delta Vectors

	 When adding or	subtracting delta vectors to/from one another, the
	 addition or subtraction takes place component by component.

	 Example:

	   [+0 +0 +0 +3	+29 +50] + [+0 +0 +0 +0	+55 +5]	= [+0 +0 +0 +3 +84 +55]
	   [+0 +0 +0 +3	+29 +50] - [+0 +0 +0 +0	+55 +5]	= [+0 +0 +0 +3 -26 +45]

	 This may result in time values	outside	the usual ranges ("[-23..+23]"
	 for hours and "[-59..+59]" for	minutes	and seconds).

	 Note that even	though the delta value for days	will often become
	 quite large, it is impossible to renormalize this value because there
	 is no constant	conversion factor from days to months (should it be
	 28, 29, 30 or 31?).

	 If accurate mode (see further above for what that is) is switched
	 off, delta vectors can	also contain non-zero values for years and
	 months. If you	add or subtract	these, the value for months can	lie
	 outside the range "[-11..11]",	which isn't wrong, but may seem	funny.

	 Therefore, the	"normalize()" method will also renormalize the
	 "months" value, if and	only if	accurate mode has been switched	off.
	 (!)

	 (Hence, switch	accurate mode ON temporarily if	you DON'T want the
	 renormalization of the	"months" value to happen.)

	 If you	want to	force the time values from the example above back into
	 their proper ranges, use the "normalize()" method as follows:

	   print "[$delta]\n";
	   $delta->normalize();
	   print "[$delta]\n";

	 This will print

	   [+0 +0 +0 +3	+84 +55]
	   [+0 +0 +0 +4	+24 +55]

	 for the first and

	   [+0 +0 +0 +3	-26 +45]
	   [+0 +0 +0 +2	+34 +45]

	 for the second	delta vector from the example further above.

	 Note that the values for days,	hours, minutes and seconds are
	 guaranteed to have the	same sign after	the renormalization.

	 Under "normal"	circumstances, i.e., when accurate mode	is on (the
	 default), this	method only has	an effect on the time part of the
	 delta vector.

	 If the	delta vector in	question does not have a time part, nothing
	 happens.

	 If accurate mode is off, the "months" value is	also normalized, i.e.,
	 if it lies outside of the range "[-11..11]", integer multiples	of 12
	 are added to the "years" value	and subtracted from the	"months"
	 value.	Moreover, the "months" value is	guaranteed to have the same
	 sign as the values for	days, hours, minutes and seconds, unless the
	 "months" value	is zero	or the values for days,	hours, minutes and
	 seconds are all zero.

	 If the	object in question is a	date and if warnings are enabled, the
	 message "normalizing a	date is	a no-op" will be printed to STDERR.

	 If the	object in question is not a valid "Date::Pcalc"	object,
	 nothing happens.

	 The method returns its	object's reference, which allows chaining of
	 method	calls, as in the following example:

	   @time = $delta->normalize()->time();

       o Callback Functions

	 Note that you are not restricted to the built-in formats (numbered
	 from 0	to 2 for "number_format()" and "number()" and from 0 to	4 for
	 "delta_format()", "date_format()" and "string()") for converting a
	 date or delta object into a number or string.

	 You can also provide your own function(s) for doing so, in order to
	 suit your own taste or	needs, by passing a subroutine reference to
	 the appropriate method, i.e., "number_format()", "number()",
	 "delta_format()", "date_format()" and "string()".

	 You can pass a	handler	to only	one or more of these methods, or to
	 all of	them, as you like. You can use different callback functions,
	 or the	same for all.

	 In order to facilitate	the latter, and	in order to make the decoding
	 of the	various	cases easier for you, the callback function receives a
	 uniquely identifying function code as its second parameter:

	   0  =	 TO_NUMBER | IS_DATE  |	IS_SHORT  (number[_format])
	   1  =	 TO_NUMBER | IS_DATE  |	IS_LONG	  (number[_format])
	   2  =	 TO_NUMBER | IS_DELTA |	IS_SHORT  (number[_format])
	   3  =	 TO_NUMBER | IS_DELTA |	IS_LONG	  (number[_format])
	   4  =	 TO_STRING | IS_DATE  |	IS_SHORT  (string|date_format)
	   5  =	 TO_STRING | IS_DATE  |	IS_LONG	  (string|date_format)
	   6  =	 TO_STRING | IS_DELTA |	IS_SHORT  (string|delta_format)
	   7  =	 TO_STRING | IS_DELTA |	IS_LONG	  (string|delta_format)

	 The first parameter of	the callback function is of course the
	 reference of the object in question itself (therefore,	the callback
	 function can actually be an object method - but not a class method,
	 for obvious reasons).

	 The third parameter is	the number of the language (in the range
	 "[1..Languages()]") which you should always pass along	when using any
	 of the	following functions from the "Date::Pcalc" module in your
	 handler:

	 "Decode_Month()", "Decode_Day_of_Week()", "Compressed_to_Text()",
	 "Date_to_Text()", "Date_to_Text_Long()", "Calendar()",
	 "Month_to_Text()", "Day_of_Week_to_Text()",
	 "Day_of_Week_Abbreviation()", "Decode_Date_EU()", "Decode_Date_US()",
	 "Decode_Date_EU2()", "Decode_Date_US2()", "Parse_Date()".

	 The callback handler should return the	resulting number or string, as
	 requested.

	 BEWARE	that you should	NEVER rely upon	any knowledge of the object's
	 internal structure, as	this may be subject to change!

	 ALWAYS	use the	test and access	methods	provided by this module!

	 Example:

	   sub handler
	   {
	       my($self,$code,$lang) = @_;

	       if    ($code == 0) # TO_NUMBER |	IS_DATE	 | IS_SHORT
	       {
		   return Date_to_Days(	$self->date() );
	       }
	       elsif ($code == 1) # TO_NUMBER |	IS_DATE	 | IS_LONG
	       {
		   return Date_to_Days(	$self->date() )	+
				    ( (	$self->hours() * 60 +
					$self->minutes() ) * 60	+
					$self->seconds() ) / 86400;
	       }
	       elsif ($code == 2) # TO_NUMBER |	IS_DELTA | IS_SHORT
	       {
		   return ( $self->year() * 12 +
			    $self->month() ) * 31 +
			    $self->day();
	       }
	       elsif ($code == 3) # TO_NUMBER |	IS_DELTA | IS_LONG
	       {
		   return ( $self->year() * 12 +
			    $self->month() ) * 31 +
			    $self->day() +
			( ( $self->hours() * 60	+
			    $self->minutes() ) * 60 +
			    $self->seconds() ) / 86400;
	       }
	       elsif ($code == 4) # TO_STRING |	IS_DATE	 | IS_SHORT
	       {
		   return join(	"/", $self->date() );
	       }
	       elsif ($code == 5) # TO_STRING |	IS_DATE	 | IS_LONG
	       {
		   return join(	"/", $self->date() ) . " " .
			  join(	":", $self->time() );
	       }
	       elsif ($code == 6) # TO_STRING |	IS_DELTA | IS_SHORT
	       {
		   return join(	"|", $self->date() );
	       }
	       elsif ($code == 7) # TO_STRING |	IS_DELTA | IS_LONG
	       {
		   return join(	"|", $self->datetime() );
	       }
	       else
	       {
		   die "internal error";
	       }
	   }

	   Date::Pcalc->number_format(\&handler);
	   Date::Pcalc->delta_format(\&handler);
	   Date::Pcalc->date_format(\&handler);

	 This sets our handler to take care of all automatic conversions, such
	 as needed when	comparing dates	or when	interpolating a	string in
	 double	quotes which contains a	date object.

	 To deactivate a handler, simply pass a	valid format number to the
	 method	in question, e.g.:

	   Date::Pcalc->number_format(0);
	   Date::Pcalc->delta_format(2);
	   Date::Pcalc->date_format(3);

	 When calling the "number()" or	"string()" method explicitly, you can
	 pass a	different format number	(than the global setting), like	this:

	   $number = $date->number(2);
	   $string = $date->string(1);

	 You can also pass a handler's reference, like so:

	   $number = $date->number(\&handler);
	   $string = $date->string(\&handler);

	 This overrides	the global setting and the individual object's local
	 setting for the duration of the call of "number()" or "string()" (but
	 doesn't change	the global or local settings themselves).

	 Moreover, you can also	define individual overrides for	the date and
	 the delta vector formats (but not the number format) for individual
	 objects, e.g.:

	   $date->delta_format(1);
	   $date->date_format(2);

	   $date->delta_format(\&handler);
	   $date->date_format(\&handler);

	 In order to deactivate	an individual handler for an object, and/or in
	 order to deactivate any override altogether (so that the global
	 settings apply	again),	you have to pass "undef" explicitly to the
	 method	in question:

	   $date->delta_format(undef);
	   $date->date_format(undef);

	 You can also define a language	for individual objects (see the	next
	 section immediately below for more details).

	 If such an individual language	override has been set, it will be
	 passed	to your	callback handlers as the third parameter (in the case
	 of "string" conversions, but not in the case of "number"
	 conversions).

	 Otherwise, the	global settings	as defined by "Language($lang);" or
	 "Date::Pcalc-"language($lang);> will be passed	to your	handler.

       o Languages

	 Note that this	module is completely transparent to the	setting	of a
	 language in "Date::Pcalc". This means that you	can choose a language
	 in "Date::Pcalc" (with	the "Language()" function) and all dates
	 subsequently printed by this module will automatically	be in that
	 language - provided that you use the built-in formats of this module,
	 or that you pass the third parameter of the callback funtion to the
	 funtions of the "Date::Pcalc" module which accept it.

	 However, this global language setting can be overridden for
	 individual date (or delta) objects by using the OBJECT	method

	     $oldlang =	$date->language($newlang);

	 (The global setting is	not altered by this in any way.)

	 In order to deactivate	such an	individual language setting (so	that
	 the global setting applies again), simply pass	the value "undef"
	 explicitly to the "language()"	object method:

	   $date->language(undef);

	 The CLASS method

	     $oldlang =	Date::Pcalc->language($newlang);

	 is just a convenient wrapper around the "Language()" function,	which
	 allows	you to enter language numbers (as returned by the
	 "Decode_Language()" function) or strings (as returned by the
	 "Language_to_Text()" function), whatever you prefer.

	 The "language()" method (both class and object) always	returns	the
	 NAME (one of ""Language_to_Text(1..Languages())"") of the current
	 setting (and never its	number).

	 BEWARE	that in	order to avoid possible	conflicts between threads or
	 modules running concurrently, you should NEVER	use the	global
	 function "Language($lang);" or	the class method
	 "Date::Pcalc-"language($lang);> in this module!

	 The class method is retained only for backward	compatibility and for
	 convenience in	stand-alone applications when it is guaranteed that no
	 such conflicts	can arise.

	 But you should	probably avoid to use global settings anyway, because
	 it may	be especially troublesome to fix your code later when suddenly
	 the need arises to use	your code with threads or when your code needs
	 to use	other modules which also use "Date::Pcalc" (with different
	 settings!).

	 By exclusively	using local settings, you are making your code
	 invulnerable against other, concurrent	modules	also using
	 "Date::Pcalc" which still use global settings.

       o Exported Functions

	 The "Date::Pcalc::Object" package imports ":all" functions exported
	 by the	"Date::Pcalc" module and re-exports them, for conveniency.

	 This allows you to write

	   use Date::Pcalc::Object qw(...);

	 instead of

	   use Date::Pcalc qw(...);

	 but with exactly the same semantics. The difference is	that the
	 object-oriented frontend is loaded additionally in the	first case.

	 As with "Date::Pcalc" you can use the ":all" tag to import all	of
	 "Date::Pcalc"'s functions:

	   use Date::Pcalc::Object qw(:all);

	 In addition to	the functions exported by "Date::Pcalc", the
	 "Date::Pcalc::Object" package offers some utility functions of	its
	 own for export:

	     $year			    = shift_year(\@_);
	     ($year,$mm,$dd)		    = shift_date(\@_);
	     ($hrs,$min,$sec)		    = shift_time(\@_);
	     ($year,$mm,$dd,$hrs,$min,$sec) = shift_datetime(\@_);

	 These functions enable	your subroutines or methods to accept a
	 "Date::Pcalc" (or subclass) date object, an (anonymous) array or a
	 list (containing the necessary	values)	as parameters INTERCHANGEABLY.

	 You can import	all of these auxiliary functions by using an ":aux"
	 tag:

	   use Date::Pcalc::Object qw(:aux);

	 If you	want to	import both all	of the "Date::Pcalc" functions as well
	 as all	these auxiliary	functions, use the ":ALL" tag:

	   use Date::Pcalc::Object qw(:ALL);

       o Subclassing

	 In case you want to subclass "Date::Pcalc" objects and	to add new
	 attributes of your own, it is recommended that	you proceed as follows
	 (the following	will be	considered as a	part of	the module's "contract
	 of use" - which might be subject to change in the future, however):

	 Define	a constant for the index of each attribute you want to add,
	 currently starting no lower than "4", at the top of your subclass:

	     use constant ATTRIB1 => 4;
	     use constant ATTRIB2 => 5;
	     use constant ATTRIB3 => 6;
	     ...

	 It is recommended that	you use	constants (which are easy to change),
	 because I someday might want to require the element with index	"4"
	 for a new attribute of	my own... ":-)"

	 Then access your attributes like so (e.g. after calling ""$self =
	 SUPER->new();"" in your constructor method):

	     $self->[0][ATTRIB1] = 'value1';
	     $self->[0][ATTRIB2] = 'value2';
	     $self->[0][ATTRIB3] = 'value3';
	     ...

	 Beware	that if	you put	anything other than numbers or strings into
	 your attributes, the methods "clone()"	and "copy()" might not work as
	 expected anymore!

	 Especially if your attributes contain references to other data
	 structures, only the references will be copied, but not the data
	 structures themselves.

	 This may not be what you want.

	 (You will have	to override these two methods and write	some of	your
	 own if	not.)

	 In order for the overloaded operators and the "shift_*()" auxiliary
	 functions from	the "Date::Pcalc::Object" package to work properly
	 (the latter of	which are heavily used in the
	 "Date::Pcalendar[::Year]" modules, for	instance), the package name of
	 your subclass (= the one your objects will be blessed into) is
	 REQUIRED to contain a "::".

	 Note that you should ONLY subclass "Date::Pcalc", NEVER
	 "Date::Pcalc::Object",	since subclassing the latter is	less efficient
	 (because "Date::Pcalc::Object"	is just	an empty class which inherits
	 from "Date::Pcalc" - subclassing "Date::Pcalc::Object"	would thus
	 just introduce	an additional name space layer to search during	Perl's
	 runtime method	binding	process).

	 If you	give your subclass a package name below/inside the "Date::"
	 namespace, you	will also benefit from the fact	that all error
	 messages produced by the "Date::Pcalc[::Object]" module (and also the
	 "Date::Pcalendar[::Year]" modules, by the way)	will appear to have
	 originated from the place outside of all ""/^Date::/""	modules
	 (including yours) where one of	the "Date::" modules was first called
	 - i.e., all errors are	always blamed on the user, no matter how
	 deeply	nested inside the "Date::" modules they	occur, and do not
	 usually refer to places inside	any of the "Date::" modules (this
	 assumes that there are	no bugs	in the "Date::"	modules, and that all
	 errors	are always the user's fault ":-)").

	 Moreover, your	module's own error messages will behave	in the same
	 way if	you ""use Carp::Clan qw(^Date::);"" at the top of your module
	 and if	you produce all	error messages using "carp()" and "croak()"
	 (instead of "warn()" and "die()", respectively).

EXAMPLES
       1)
	    # Switch to	summer time:
	    $now = Date::Pcalc->now();
	    if (($now ge [2000,3,26,2,0,0]) and
		($now lt [2000,3,26,3,0,0]))
	    {
		$now +=	[0,0,0,1,0,0];
	    }

       2)
	    use	Date::Pcalc::Object qw(:all);

	    Date::Pcalc->date_format(3);

	    $date = 0;
	    while (!$date)
	    {
		print "Please enter the	date of	your birthday (day-month-year):	";
		$date =	Date::Pcalc->new( Decode_Date_EU( scalar(<STDIN>) ) );
		if ($date)
		{
		    $resp = 0;
		    while ($resp !~ /^\s*[YyNn]/)
		    {
			print "Your birthday is: $date\n";
			print "Is that correct?	(yes/no) ";
			$resp =	<STDIN>;
		    }
		    $date = 0 unless ($resp =~ /^\s*[Yy]/)
		}
		else
		{
		    print "Unable to parse your	birthday. Please try again.\n";
		}
	    }

	    if ($date +	[18,0,0] <= [Today()])
		{ print	"Ok, you are over 18.\n"; }
	    else
		{ print	"Sorry,	you are	under 18!\n"; }

       For more	examples, see the "examples" subdirectory in this
       distribution, and their descriptions in the file	"EXAMPLES.txt".

SEE ALSO
       Date::Pcalc(3), Date::Calc::Util(3), Date::Pcalendar(3),
       Date::Pcalendar::Year(3), Date::Pcalendar::Profiles(3).

VERSION
       This man	page documents "Date::Pcalc::Object" version 6.1.

AUTHOR
	 Steffen Beyer
	 mailto:STBEY@cpan.org
	 http://www.engelschall.com/u/sb/download/

COPYRIGHT
       Copyright (c) 2000 - 2009 by Steffen Beyer. All rights reserved.

LICENSE
       This package is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, i.e., under	the terms of the
       "Artistic License" or the "GNU General Public License".

       Please refer to the files "Artistic.txt"	and "GNU_GPL.txt" in this
       distribution for	details!

DISCLAIMER
       This package is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A	PARTICULAR PURPOSE.

       See the "GNU General Public License" for	more details.

perl v5.32.0			  2009-10-15		Date::Pcalc::Object(3)

NAME | MOTTO | PREFACE | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | VERSION | AUTHOR | COPYRIGHT | LICENSE | DISCLAIMER

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Date::Pcalc::Object&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help