1Date::Calc::Object(3) User Contributed Perl DocumentationDate::Calc::Object(3)
2
6 Date::Calc::Object - Object-oriented add-on for Date::Calc with over‐
7 loaded operators
8
10 Make frequent things easy and infrequent or hard things possible
11
13 Note that you do NOT need to ""use Date::Calc qw(...);"" in addition to
14 this module.
15 Simply
17 use Date::Calc::Object qw(...);
19 INSTEAD OF
21 use Date::Calc qw(...);
23 with the same ""qw(...)"" as you would with the "Date::Calc" module,
25 and then forget about "Date::Calc::Object" altogether.
26 The rest of your existing code doesn't change at all.
28 Note also that in order to create a new date object, you do not need to
30 use
31 $date_object = Date::Calc::Object->new(...);
33 (but you may), and should use
35 $date_object = Date::Calc->new(...);
37 instead (saves you some typing and is a trifle faster).
39
41 Export tags
42 :all - all functions from Date::Calc
44 :aux - auxiliary functions shift_*
45 :ALL - both :all and :aux
46 Functions
48 See Date::Calc(3) for a list of available functions.
50 $year = shift_year(\@_);
52 ($year,$mm,$dd) = shift_date(\@_);
53 ($hrs,$min,$sec) = shift_time(\@_);
54 ($year,$mm,$dd,$hrs,$min,$sec) = shift_datetime(\@_);
55 Methods
57 $old = Date::Calc->accurate_mode([FLAG]);
59 $old = Date::Calc->number_format([NUMBER⎪CODEREF]);
60 $old = Date::Calc->delta_format([NUMBER⎪CODEREF]); # global default
61 $old = Date::Calc->date_format([NUMBER⎪CODEREF]); # global default
62 $old = Date::Calc->language([LANGUAGE]); # global default
63 $old = $date->accurate_mode([FLAG]); # is global nevertheless!
65 $old = $date->number_format([NUMBER⎪CODEREF]); # is global nevertheless!
66 $old = $date->delta_format([NUMBER⎪CODEREF]); # individual override
67 $old = $date->date_format([NUMBER⎪CODEREF]); # individual override
68 $old = $date->language([LANGUAGE]); # individual override
69 $flag = $date->is_delta();
71 $flag = $date->is_date();
72 $flag = $date->is_short(); # i.e., has no time part
73 $flag = $date->is_long(); # i.e., has time part
74 $flag = $date->is_valid();
75 $date = Date::Calc->new([TYPE]);
77 $date = Date::Calc->new([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
78 $date = Date::Calc->new($arrayref);
79 $newdate = $somedate->new([TYPE]);
80 $newdate = $somedate->new([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
81 $newdate = $somedate->new($arrayref);
82 $datecopy = $date->clone();
84 $targetdate->copy($sourcedate);
85 $targetdate->copy($arrayref);
86 $targetdate->copy(@list);
87 ($year,$month,$day) = $date->date([TYPE]);
89 ($year,$month,$day) = $date->date([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
90 ($year,$month,$day) = $date->date($arrayref);
91 ([$hrs,$min,$sec]) = $date->time([TYPE]);
92 ($hrs,$min,$sec) = $date->time([TYPE,]HRS,MIN,SEC);
93 ([$hrs,$min,$sec]) = $date->time($arrayref);
94 ($year,$month,$day,$hrs,$min,$sec) =
96 $date->datetime([TYPE]);
97 ($year,$month,$day,$hrs,$min,$sec) =
98 $date->datetime([TYPE,]YEAR,MONTH,DAY[,HRS,MIN,SEC]);
99 $date = Date::Calc->today([FLAG]);
101 $date = Date::Calc->now([FLAG]); # shorthand for --+
102 $date = Date::Calc->today_and_now([FLAG]); # <-----+
103 $date = Date::Calc->gmtime([time]); # UTC/GMT
104 $date = Date::Calc->localtime([time]); # local time
105 $delta = Date::Calc->tzoffset([time]);
106 $date = Date::Calc->time2date([time]); # UTC/GMT
107 $date->today([FLAG]); # updates the date part only
109 $date->now([FLAG]); # updates the time part only
110 $date->today_and_now([FLAG]); # updates both date and time
111 $date->gmtime([time]); # updates both date and time (UTC/GMT)
112 $date->localtime([time]); # updates both date and time (local time)
113 $delta->tzoffset([time]); # updates both date and time
114 $date->time2date([time]); # updates both date and time (UTC/GMT)
115 $time = Date::Calc->mktime(); # same as "$time = CORE::time();"
117 $time = Date::Calc->date2time(); # same as "$time = CORE::time();"
118 $time = $date->mktime(); # converts into Unix time (local time)
120 $time = $date->date2time(); # converts into Unix time (UTC/GMT)
121 $year = $date->year([YEAR]);
123 $month = $date->month([MONTH]);
124 $day = $date->day([DAY]);
125 $hours = $date->hours([HRS]);
126 $minutes = $date->minutes([MIN]);
127 $seconds = $date->seconds([SEC]);
128 $number = $date->number([NUMBER⎪CODEREF]);
130 $string = $date->string([NUMBER⎪CODEREF][,LANGUAGE]);
131 $delta->normalize(); # renormalizes a delta vector
133 Overloaded Operators
135 #####################################################
137 # Scalar operands are always converted into a delta #
138 # vector with that many days, i.e., [1,0,0,SCALAR] #
139 #####################################################
140 Comparison Operators:
142 if ($date1 < $date2) { # compares date part only
144 if ($date1 <= $date2) { # compares date part only
145 if ($date1 > $date2) { # compares date part only
146 if ($date1 >= $date2) { # compares date part only
147 if ($date1 == $date2) { # compares date part only
148 if ($date1 != $date2) { # compares date part only
149 $comp = $date1 <=> $date2; # compares date part only
151 if ($date1 lt $date2) { # compares both date and time
153 if ($date1 le $date2) { # compares both date and time
154 if ($date1 gt $date2) { # compares both date and time
155 if ($date1 ge $date2) { # compares both date and time
156 if ($date1 eq $date2) { # compares both date and time
157 if ($date1 ne $date2) { # compares both date and time
158 $comp = $date1 cmp $date2; # compares both date and time
160 Note that you can of course also compare two deltas, but not a date and
162 a delta!
163 ##################################################
165 # Default TYPE for array refs in comparisons is: #
166 # Same as other operand #
167 ##################################################
168 if ([2000,4,1] == $date) {
170 if ($today > [2000,4,1]) {
171 if ($now ge [2000,3,26,2,0,0]) {
173 if ($delta == [18,0,0]) {
175 if ($delta == -1) {
176 Plus:
178 $date2 = $date1 + $delta;
180 $date2 = $delta + $date1;
181 $date += $delta;
182 $this = $date++;
183 $next = ++$date;
184 $delta3 = $delta1 + $delta2;
186 $delta1 += $delta2;
187 $delta += $date; # beware of implicit type change!
188 $delta++;
189 ++$delta;
190 #####################################################
192 # Default TYPE for array refs in '+' operations is: #
193 # Opposite of other operand #
194 #####################################################
195 $date2 = [2000,3,26] + $delta;
197 $date2 = $date1 + [+1,0,0];
198 $date2 = [0,0,-1] + $date1;
199 $date2 = $date1 + 1;
200 $date += [0,0,+1];
201 $date += 2;
202 $delta3 = [1,+1,0,-1] + $delta2;
204 $delta3 = $delta1 + [1,0,0,+1];
205 $delta3 = $delta1 + 1;
206 $delta += [1,0,+1,0];
207 $delta += [2000,3,26]; # beware of implicit type change!
208 $delta += 7;
209 Unary Minus:
211 $delta2 = -$delta1;
213 Minus:
215 $delta = $date2 - $date1;
217 $date2 = $date1 - $delta;
218 $date -= $delta;
219 $date2 -= $date1; # beware of implicit type change!
220 $this = $date--;
221 $prev = --$date;
222 $delta3 = $delta2 - $delta1;
224 $delta2 -= $delta1;
225 $delta--;
226 --$delta;
227 #####################################################
229 # Default TYPE for array refs in '-' operations is: #
230 # Always a date #
231 #####################################################
232 $delta = $today - [2000,3,26];
234 $delta = [2000,4,1] - $date;
235 $date2 = [2000,3,26] - $delta;
236 $date2 = $date1 - [1,0,0,+7];
237 $date2 = $date1 - 7;
238 $date -= [1,0,0,+1]; # better add [0,0,-1] instead!
239 $date2 -= [2000,3,26]; # beware of implicit type change!
240 $date2 -= 1;
241 $delta3 = [1,0,+1,0] - $delta1;
243 $delta3 = $delta2 - [1,0,0,-1];
244 $delta -= [1,0,0,+1];
245 $delta -= 7;
246 Miscellaneous Operators:
248 $string = "$date";
250 $string = "$delta";
251 print "$date\n";
253 print "$delta\n";
254 if ($date) { # date is valid
256 if ($delta) { # delta is valid
257 $days = abs($date);
259 $diff = abs($delta); # can be negative!
260 $diff = abs(abs($delta)); # always positive
262
264 · FLAG
265 "FLAG" is either 0 (for "false") or 1 (for "true").
267 In the case of ""accurate_mode()"", this switches "accurate mode" on
269 and off (see further below for an explanation of what that is).
270 In the case of ""today()"", ""now()"" and ""today_and_now()"", a
272 "true" value indicates "GMT" (Greenwich Mean Time), as opposed to
273 local time, which is the default.
274 · NUMBER
276 "NUMBER" is a number between 0 and 2 (for "number_format()" and "num‐
278 ber()") or between 0 and 3 (for "delta_format()", "date_format()" and
279 "string()"), indicating which of the three/four predefined formats,
280 respectively, should be used for converting a date into numeric rep‐
281 resentation (needed for comparing dates, for instance) or string rep‐
282 resentation.
283 Format #0 is the default at startup and the simplest of all (and
285 should be fastest to calculate, too).
286 The string representation of dates in format #0 also has the advan‐
288 tage of being sortable in chronological order (and of complying with
289 ISO 8601).
290 (The numeric formats are (trivially) always sortable in chronological
292 order of course.)
293 The other formats are increasingly more sophisticated (in terms of
295 esthetics and computation time) with increasing number:
296 Delta number formats (short):
298 0 13603
300 1 13603
301 2 13603
302 Delta string formats (short):
304 0 '+0+0+13603'
306 1 '+0 +0 +13603'
307 2 '+0Y +0M +13603D'
308 3 '+0 Y +0 M +13603 D'
309 Date number formats (short):
311 0 20010401
313 1 730576
314 2 730576
315 Date string formats (short):
317 0 '20010401'
319 1 '01-Apr-2001'
320 2 'Sun 1-Apr-2001'
321 3 'Sunday, April 1st 2001'
322 Delta number formats (long):
324 0 13603.012959
326 1 13603.012959
327 2 13603.0624884259
328 Delta string formats (long):
330 0 '+0+0+13603+1+29+59'
332 1 '+0 +0 +13603 +1 +29 +59'
333 2 '+0Y +0M +13603D +1h +29m +59s'
334 3 '+0 Y +0 M +13603 D +1 h +29 m +59 s'
335 Date number formats (long):
337 0 20010401.082959
339 1 730576.082959
340 2 730576.354155093
341 Date string formats (long):
343 0 '20010401082959'
345 1 '01-Apr-2001 08:29:59'
346 2 'Sun 1-Apr-2001 08:29:59'
347 3 'Sunday, April 1st 2001 08:29:59'
348 If a number outside of the permitted range is specified, or if the
350 value is not a code reference (see also the next section below for
351 more details), the default format #0 is used instead.
352 · CODEREF
354 "CODEREF" is the reference of a subroutine which can be passed to the
356 methods "number_format()", "delta_format()" and "date_format()" in
357 order to install a callback function which will be called subse‐
358 quently whenever a date (or delta) object needs to be (implicitly)
359 converted into a number or string.
360 This happens for instance when you compare two date objects, or when
362 you put a date object reference in a string between double quotes.
363 Such a "CODEREF" can also be passed to the methods "number()" and
365 "string()" for explicitly converting a date object as desired.
366 · LANGUAGE
368 "LANGUAGE" is either a number in the range "[1..Languages()]", or one
370 of the strings ""Language_to_Text(1..Languages())"" (see also
371 Date::Calc(3)).
372 · TYPE
374 "TYPE" is 0 for a regular date and 1 for a delta vector (a list of
376 year, month, day and optionally hours, minutes and seconds offsets).
377 · Storage
379 "Date::Calc" objects are implemented as two nested arrays.
381 The "blessed" array (whose reference is the object reference you
383 receive when calling the "new()" method) contains an anonymous array
384 at position zero and the object's data in its remaining fields.
385 The embedded anonymous array is used for storing the object's
387 attributes (flags).
388 Dates and delta vectors always comprise either 3 or 6 data values:
390 Year, month, day plus (optionally) hours, minutes and seconds.
391 These values are stored in the "blessed" array at positions 1..3 or
393 1..6, respectively.
394 An object without the time values is therefore called "short", and an
396 object having time values is called "long" throughout this manual.
397 Hint: Whenever possible, if you do not need the time values, omit
399 them, i.e., always use the "short" form of the object if possible,
400 this will speed up calculations a little (the short form uses differ‐
401 ent (faster) functions for all calculations internally).
402 The embedded anonymous array contains various flags:
404 At position zero, it contains the "TYPE" indicator which determines
406 whether the object is a date or a delta vector.
407 At position 1, the object stores the "NUMBER" of one of the delta
409 vector formats, or the reference of a callback function which con‐
410 verts the contents of the object into string representation if it's a
411 delta vector, or "undef" if the global settings apply.
412 At position 2, the object stores the "NUMBER" of one of the date for‐
414 mats, or the reference of a callback function which converts the con‐
415 tents of the object into string representation if it's a date, or
416 "undef" if the global settings apply.
417 At position 3, the object stores the "LANGUAGE" to be used for all
419 conversions into strings (where applicable), or "undef" if the global
420 language setting applies.
421 Note that your callback functions (see the section "Callback Func‐
423 tions" further below for more details) do not need to pay attention
424 to the value at position 3, the language (of the "Date::Calc" module)
425 will automatically be set to this value whenever the callback func‐
426 tions are called, and automatically reset to its former value after
427 the callback.
428 So if your callback functions use the "*_to_Text*" functions from the
430 "Date::Calc" module, they will automatically use the correct lan‐
431 guage.
432 Be reminded though that you should NEVER access the object's internal
434 data directly, i.e., through their positional numbers, but ALWAYS
435 through their respective accessor methods, e.g.:
436 year()
438 month()
439 day()
440 hours()
441 minutes()
442 seconds()
443 date()
444 time()
445 datetime()
446 is_delta()
447 is_date()
448 is_short()
449 is_long()
450 delta_format()
451 date_format()
452 language()
453 And although position 4 and onward in the embedded anonymous array is
455 currently unused, it might not stay so in future releases of this
456 module.
457 Therefore, in case you need more attributes in a subclass of the
459 "Date::Calc[::Object]" class, I suggest using values starting at
460 positions a bit further up, e.g. 6, 8 or 10.
461 · Invalid Dates
463 Only "new()" allows to create objects containing possibly invalid
465 dates (needed for reading in and evaluating user input, for example).
466 · Usage
468 The methods
470 accurate_mode()
472 number_format()
473 delta_format()
474 date_format()
475 language()
476 date()
477 time()
478 datetime()
479 year()
480 month()
481 day()
482 hours()
483 minutes()
484 seconds()
485 are used for reading as well as for setting attributes. They simply
487 return the values in question if they are called without parameters.
488 The methods
490 accurate_mode()
492 number_format()
493 delta_format()
494 date_format()
495 language()
496 always return the previous value if a new value is set. This allows
498 you to change these values temporarily and to restore their old value
499 afterwards more easily (but you can also override the "format" and
500 "language" settings directly when calling the "number()" or
501 "string()" method).
502 The methods
504 date()
506 time()
507 datetime()
508 year()
509 month()
510 day()
511 hours()
512 minutes()
513 seconds()
514 always return the new values when the corresponding values have been
516 changed.
517 The method "date()" NEVER returns the time values (hours, minutes,
519 seconds) even if they have just been set using this method (which the
520 method optionally allows). Otherwise it would be very hard to predict
521 the exact number of values it returns, which might lead to errors
522 (wrong number of parameters) elsewhere in your program.
523 The method "datetime()" ALWAYS returns the time values (hours, min‐
525 utes, seconds) even if the object in question lacks a time part. In
526 that case, zeros are returned for hours, minutes and seconds instead
527 (but the stored time part is left unchanged, whether it exists or
528 not).
529 If you do not provide values for hours, minutes and seconds when
531 using the method "date()" to set the values for year, month and day,
532 the time part will not be changed (whether it exists or not).
533 If you do not provide values for hours, minutes and seconds when
535 using the method "datetime()" to set the values for year, month and
536 day, the time part will be filled with zeros (the time part will be
537 created if necessary).
538 If the object is short, i.e., if it does not have any time values,
540 the method "time()" returns an empty list.
541 If the object is short and the methods "hours()", "minutes()" or
543 "seconds()" are used to set any of these time values, the object is
544 automatically promoted to the "long" form, and the other two time
545 values are filled with zeros.
546 The following methods can also return "undef" under certain circum‐
548 stances:
549 delta_format()
551 date_format()
552 language()
553 is_delta()
554 is_date()
555 is_short()
556 is_long()
557 is_valid()
558 hours()
559 minutes()
560 seconds()
561 number()
562 string()
563 The methods "delta_format()", "date_format()" and "language()" return
565 "undef" when they are called as object methods and no individual
566 override has been defined for the object in question.
567 The "is_*()" predicate methods return "undef" if the object in ques‐
569 tion does not have the expected internal structure. This can happen
570 for instance when you create an empty object with "new()".
571 When called without parameters, the methods "hours()", "minutes()"
573 and "seconds()" return "undef" if the object in question does not
574 have a time part.
575 The methods "number()" and "string()" return "undef" if the object in
577 question is not valid (i.e., if "is_valid()" returns "undef" or
578 false).
579 And finally, the methods
581 copy()
583 today()
584 now()
585 today_and_now()
586 gmtime()
587 localtime()
588 tzoffset()
589 time2date()
590 normalize()
591 return the object reference of the (target) object in question for
593 convenience.
594 · Import/Export
596 Note that you can import and export Unix "time" values using the
598 methods "gmtime()", "localtime()", "mktime()", "date2time()" and
599 "time2date()", both as local time or as UTC/GMT.
600 · Accurate Mode
602 The method "accurate_mode()" controls the internal flag which deter‐
604 mines which of two modes of operation is used.
605 When set to true (the default at startup), delta vectors are calcu‐
607 lated to give the exact difference in days between two dates. The
608 "year" and "month" entries in the resulting delta vector are always
609 zero in that case.
610 If "accurate mode" is switched off (when the corresponding flag is
612 set to false), delta vectors are calculated with year and month dif‐
613 ferences.
614 E.g., the difference between "[1999,12,6]" and "[2000,6,24]" is "[+0
616 +0 +201]" (plus 201 days) in accurate mode and "[+1 -6 +18]" (plus
617 one year, minus 6 months, plus 18 days) when accurate mode is
618 switched off.
619 (The delta vector is calculated by simply taking the difference in
621 years, the difference in months and the difference in days.)
622 Because years and months have varying lengths in terms of days, the
624 latter is less accurate than the former because it depends on the
625 context of the two dates of which it represents the difference. Added
626 to a different date, the latter delta vector may yield a different
627 offset in terms of days.
628 Beware also that - for the same reason - the absolute value
630 (""abs()"") of a delta vector returns a fictitious number of days if
631 the delta vector contains non-zero values for "year" and/or "month"
632 (see also next section below for more details).
633 Example:
635 The difference between "[2000,1,1]" and "[2000,3,1]" is "[+0 +0 +60]"
637 in accurate mode and "[+0 +2 +0]" else (one could also call this
638 "year-month-day mode" or "YMD mode" for short).
639 When added to the date "[2000,4,1]", the "accurate" delta vector
641 yields the date "[2000,5,31]", whereas the other delta vector yields
642 the date "[2000,6,1]".
643 Moreover, when added to the date "[1999,1,1]", the "accurate" delta
645 vector yields the date "[1999,3,2]", whereas the "inaccurate" delta
646 vector yields the date "[1999,3,1]".
647 Depending on what you want, the one or the other mode may suit you
649 better.
650 · Absolute Value
652 Note that ""abs($date)"" and ""abs($delta)"" are just shorthands for
654 ""$date->number()"" and ""$delta->number()"".
655 The operator ""abs()"", when applied to a date or delta vector,
657 returns the corresponding number of days (see below for an exception
658 to this), with the time part (if available) represented by a fraction
659 after the decimal point.
660 In the case of dates, the absolute value (to the left of the decimal
662 point) is the number of days since the 1st of January 1 A.D. (by
663 extrapolating the Gregorian calendar back beyond its "natural" limit
664 of 1582 A.D.) PLUS ONE.
665 (I.e., the absolute value of the 1st of January 1 A.D. is 1.)
667 Exception:
669 If the "NUMBER" or "number_format()" is set to 0 (the default set‐
671 ting), the absolute value of a date to the left of the decimal point
672 is "yyyymmdd", i.e., the number in which the uppermost four digits
673 correspond to the year, the next lower two digits to the month and
674 the lowermost two digits to the day.
675 In the case of delta vectors, the absolute value (to the left of the
677 decimal point) is simply the difference in days (but see also below).
678 Note that the absolute value of a delta vector can be negative!
680 If you want a positive value in all cases, apply the ""abs()"" opera‐
682 tor again, i.e., ""$posdiff = abs(abs($delta));"".
683 If the delta vector contains non-zero values for "year" and/or
685 "month" (see also the discussion of "Accurate Mode" in the section
686 above), an exact representation in days cannot be calculated, because
687 years and months do not have fixed equivalents in days.
688 If nevertheless you attempt to calculate the absolute value of such a
690 delta vector, a fictitious value is returned, which is calculated by
691 simply multiplying the year difference with 12, adding the month dif‐
692 ference, multiplying this sum with 31 and finally adding the day dif‐
693 ference.
694 Beware that because of this, the absolute values of delta vectors are
696 not necessarily contiguous.
697 Moreover, since there is more than one way to express the difference
699 between two dates, comparisons of delta vectors may not always yield
700 the expected result.
701 Example:
703 The difference between the two dates "[2000,4,30]" and "[2001,5,1]"
705 can be expressed as "[+1 +1 -29]", or as "[+1 +0 +1]".
706 The first delta vector has an absolute value of 374, whereas the lat‐
708 ter delta vector has an absolute value of only 373 (while the true
709 difference in days between the two dates is 366).
710 If the date or delta vector has a time part, the time is returned as
712 a fraction of a full day after the decimal point as follows:
713 If the "NUMBER" or "number_format()" is set to 0 (the default set‐
715 ting) or 1, this fraction is simply ".hhmmss", i.e., the two digits
716 after the decimal point represent the hours, the next two digits the
717 minutes and the last two digits the seconds.
718 Note that you cannot simply add and subtract these values to yield
720 meaningful dates or deltas again, you can only use them for compar‐
721 isons (equal, not equal, less than, greater than, etc.). If you want
722 to add/subtract, read on:
723 Only when the "NUMBER" or "number_format()" is set to 2, this frac‐
725 tion will be the equivalent number of seconds (i.e., "(((hours * 60)
726 + minutes) * 60) + seconds") divided by the number of seconds in a
727 full day (i.e., "24*60*60 = 86400"), or "0/86400", "1/86400", ... ,
728 "86399/86400".
729 In other words, the (mathematically correct) fraction of a day.
731 You can safely perform arithmetics with these values as far as the
733 internal precision of your vendor's implementation of the C run-time
734 library (on which Perl depends) will permit.
735 · Renormalizing Delta Vectors
737 When adding or subtracting delta vectors to/from one another, the
739 addition or subtraction takes place component by component.
740 Example:
742 [+0 +0 +0 +3 +29 +50] + [+0 +0 +0 +0 +55 +5] = [+0 +0 +0 +3 +84 +55]
744 [+0 +0 +0 +3 +29 +50] - [+0 +0 +0 +0 +55 +5] = [+0 +0 +0 +3 -26 +45]
745 This may result in time values outside the usual ranges ("[-23..+23]"
747 for hours and "[-59..+59]" for minutes and seconds).
748 Note that even though the delta value for days will often become
750 quite large, it is impossible to renormalize this value because there
751 is no constant conversion factor from days to months (should it be
752 28, 29, 30 or 31?).
753 If accurate mode (see further above for what that is) is switched
755 off, delta vectors can also contain non-zero values for years and
756 months. If you add or subtract these, the value for months can lie
757 outside the range "[-11..11]", which isn't wrong, but may seem funny.
758 Therefore, the "normalize()" method will also renormalize the
760 "months" value, if and only if accurate mode has been switched off.
761 (!)
762 (Hence, switch accurate mode ON temporarily if you DON'T want the
764 renormalization of the "months" value to happen.)
765 If you want to force the time values from the example above back into
767 their proper ranges, use the "normalize()" method as follows:
768 print "[$delta]\n";
770 $delta->normalize();
771 print "[$delta]\n";
772 This will print
774 [+0 +0 +0 +3 +84 +55]
776 [+0 +0 +0 +4 +24 +55]
777 for the first and
779 [+0 +0 +0 +3 -26 +45]
781 [+0 +0 +0 +2 +34 +45]
782 for the second delta vector from the example further above.
784 Note that the values for days, hours, minutes and seconds are guaran‐
786 teed to have the same sign after the renormalization.
787 Under "normal" circumstances, i.e., when accurate mode is on (the
789 default), this method only has an effect on the time part of the
790 delta vector.
791 If the delta vector in question does not have a time part, nothing is
793 done.
794 If accurate mode is off, the "months" value is also normalized, i.e.,
796 if it lies outside of the range "[-11..11]", integer multiples of 12
797 are added to the "years" value and subtracted from the "months"
798 value. Moreover, the "months" value is guaranteed to have the same
799 sign as the values for days, hours, minutes and seconds, unless the
800 "months" value is zero or the values for days, hours, minutes and
801 seconds are all zero.
802 If the object in question is a date and if warnings are enabled, the
804 message "normalizing a date is a no-op" will be printed to STDERR.
805 If the object in question is not a valid "Date::Calc" object, nothing
807 is done.
808 The method returns its object's reference, which allows chaining of
810 method calls, as in the following example:
811 @time = $delta->normalize()->time();
813 · Callback Functions
815 Note that you are not restricted to the built-in formats (numbered
817 from 0 to 2 for "number_format()" and "number()" and from 0 to 3 for
818 "delta_format()", "date_format()" and "string()") for converting a
819 date or delta object into a number or string.
820 You can also provide your own function(s) for doing so, in order to
822 suit your own taste or needs, by passing a subroutine reference to
823 the appropriate method, i.e., "number_format()", "number()",
824 "delta_format()", "date_format()" and "string()".
825 You can pass a handler to only one or more of these methods, or to
827 all of them, as you like. You can use different callback functions,
828 or the same for all.
829 In order to facilitate the latter, and in order to make the decoding
831 of the various cases easier for you, the callback function receives a
832 uniquely identifying function code as its second parameter:
833 0 = TO_NUMBER ⎪ IS_DATE ⎪ IS_SHORT (number[_format])
835 1 = TO_NUMBER ⎪ IS_DATE ⎪ IS_LONG (number[_format])
836 2 = TO_NUMBER ⎪ IS_DELTA ⎪ IS_SHORT (number[_format])
837 3 = TO_NUMBER ⎪ IS_DELTA ⎪ IS_LONG (number[_format])
838 4 = TO_STRING ⎪ IS_DATE ⎪ IS_SHORT (string⎪date_format)
839 5 = TO_STRING ⎪ IS_DATE ⎪ IS_LONG (string⎪date_format)
840 6 = TO_STRING ⎪ IS_DELTA ⎪ IS_SHORT (string⎪delta_format)
841 7 = TO_STRING ⎪ IS_DELTA ⎪ IS_LONG (string⎪delta_format)
842 The first parameter of the callback function is of course the handle
844 of the object in question itself (therefore, the callback function
845 can actually be an object method - but not a class method, for obvi‐
846 ous reasons).
847 The handler should return the resulting number or string, as
849 requested.
850 BEWARE that you should NEVER rely upon any knowledge of the object's
852 internal structure, as this may be subject to change!
853 ALWAYS use the test and access methods provided by this module!
855 Example:
857 sub handler
859 {
860 my($self,$code) = @_;
861 if ($code == 0) # TO_NUMBER ⎪ IS_DATE ⎪ IS_SHORT
863 {
864 return Date_to_Days( $self->date() );
865 }
866 elsif ($code == 1) # TO_NUMBER ⎪ IS_DATE ⎪ IS_LONG
867 {
868 return Date_to_Days( $self->date() ) +
869 ( ( $self->hours() * 60 +
870 $self->minutes() ) * 60 +
871 $self->seconds() ) / 86400;
872 }
873 elsif ($code == 2) # TO_NUMBER ⎪ IS_DELTA ⎪ IS_SHORT
874 {
875 return ( $self->year() * 12 +
876 $self->month() ) * 31 +
877 $self->day();
878 }
879 elsif ($code == 3) # TO_NUMBER ⎪ IS_DELTA ⎪ IS_LONG
880 {
881 return ( $self->year() * 12 +
882 $self->month() ) * 31 +
883 $self->day() +
884 ( ( $self->hours() * 60 +
885 $self->minutes() ) * 60 +
886 $self->seconds() ) / 86400;
887 }
888 elsif ($code == 4) # TO_STRING ⎪ IS_DATE ⎪ IS_SHORT
889 {
890 return join( "/", $self->date() );
891 }
892 elsif ($code == 5) # TO_STRING ⎪ IS_DATE ⎪ IS_LONG
893 {
894 return join( "/", $self->date() ) . " " .
895 join( ":", $self->time() );
896 }
897 elsif ($code == 6) # TO_STRING ⎪ IS_DELTA ⎪ IS_SHORT
898 {
899 return join( "⎪", $self->date() );
900 }
901 elsif ($code == 7) # TO_STRING ⎪ IS_DELTA ⎪ IS_LONG
902 {
903 return join( "⎪", $self->datetime() );
904 }
905 else
906 {
907 die "internal error";
908 }
909 }
910 Date::Calc->number_format(\&handler);
912 Date::Calc->delta_format(\&handler);
913 Date::Calc->date_format(\&handler);
914 This sets our handler to take care of all automatic conversions, such
916 as needed when comparing dates or when interpolating a string in dou‐
917 ble quotes which contains a date object.
918 To deactivate a handler, simply pass a valid format number to the
920 method in question, e.g.:
921 Date::Calc->number_format(0);
923 Date::Calc->delta_format(2);
924 Date::Calc->date_format(3);
925 When calling the "number()" or "string()" method explicitly, you can
927 pass a different format number (than the global setting), like this:
928 $number = $date->number(2);
930 $string = $date->string(1);
931 You can also pass a handler's reference, like so:
933 $number = $date->number(\&handler);
935 $string = $date->string(\&handler);
936 This overrides the global setting for the duration of the call of
938 "number()" or "string()" (but doesn't change the global setting
939 itself).
940 Moreover, you can also define individual overrides for the date and
942 the delta vector formats (but not the number format) for individual
943 objects, e.g.:
944 $date->delta_format(1);
946 $date->date_format(2);
947 $date->delta_format(\&handler);
949 $date->date_format(\&handler);
950 In order to deactivate an individual handler for an object, and/or in
952 order to deactivate any override altogether (so that the global set‐
953 tings apply again), you have to pass "undef" explicitly to the method
954 in question:
955 $date->delta_format(undef);
957 $date->date_format(undef);
958 You can also define a language for individual objects (see the next
960 section immediately below for more details).
961 If such an individual language override has been set, and if your
963 callback handlers only use the "*_to_Text*" functions from the
964 "Date::Calc" module to produce any text, the text produced will auto‐
965 matically be in the desired language.
966 This is because the language is set to the value determined by the
968 individual override before the callback handler is executed, and
969 reset to its previous value afterwards.
970 · Languages
972 Note that this module is completely transparent to the setting of a
974 language in "Date::Calc". This means that you can choose a language
975 in "Date::Calc" (with the "Language()" function) and all dates subse‐
976 quently printed by this module will automatically be in that language
977 - provided that you use the built-in formats of this module, or that
978 you use the "*to_Text*" functions from the "Date::Calc" module in
979 your formatting handler (callback function).
980 However, this global language setting can be overridden for individ‐
982 ual date (or delta) objects by using the OBJECT method
983 $oldlang = $date->language($newlang);
985 (The global setting is not altered by this in any way.)
987 In order to deactivate such an individual language setting (so that
989 the global setting applies again), simply pass the value "undef"
990 explicitly to the "language()" object method:
991 $date->language(undef);
993 The CLASS method
995 $oldlang = Date::Calc->language($newlang);
997 is just a convenient wrapper around the "Language()" function, which
999 allows you to enter language numbers (as returned by the "Decode_Lan‐
1000 guage()" function) or strings (as returned by the "Lan‐
1001 guage_to_Text()" function), at your option.
1002 The "language()" method (both class and object) always returns the
1004 NAME (one of ""Language_to_Text(1..Languages())"") of the current
1005 setting (and never its number).
1006 · Exported Functions
1008 The "Date::Calc::Object" package imports ":all" functions exported by
1010 the "Date::Calc" module and re-exports them, for conveniency.
1011 This allows you to write
1013 use Date::Calc::Object qw(...);
1015 instead of
1017 use Date::Calc qw(...);
1019 but with exactly the same semantics. The difference is that the
1021 object-oriented frontend is loaded additionally in the first case.
1022 As with "Date::Calc" you can use the ":all" tag to import all of
1024 "Date::Calc"'s functions:
1025 use Date::Calc::Object qw(:all);
1027 In addition to the functions exported by "Date::Calc", the
1029 "Date::Calc::Object" package offers some utility functions of its own
1030 for export:
1031 $year = shift_year(\@_);
1033 ($year,$mm,$dd) = shift_date(\@_);
1034 ($hrs,$min,$sec) = shift_time(\@_);
1035 ($year,$mm,$dd,$hrs,$min,$sec) = shift_datetime(\@_);
1036 These functions enable your subroutines or methods to accept a
1038 "Date::Calc" (or subclass) date object, an (anonymous) array or a
1039 list (containing the necessary values) as parameters INTERCHANGEABLY.
1040 You can import all of these auxiliary functions by using an ":aux"
1042 tag:
1043 use Date::Calc::Object qw(:aux);
1045 If you want to import both all of the "Date::Calc" functions as well
1047 as all these auxiliary functions, use the ":ALL" tag:
1048 use Date::Calc::Object qw(:ALL);
1050 · Subclassing
1052 In case you want to subclass "Date::Calc" objects and to add new
1054 attributes of your own, it is recommended that you proceed as follows
1055 (the following will be considered as a part of the module's "contract
1056 of use" - which might be subject to change in the future, however):
1057 Define a constant for the index of each attribute you want to add,
1059 currently starting no lower than "4", at the top of your subclass:
1060 use constant ATTRIB1 => 4;
1062 use constant ATTRIB2 => 5;
1063 use constant ATTRIB3 => 6;
1064 ...
1065 It is recommended that you use constants (which are easy to change),
1067 because I someday might want to require the element with index "4"
1068 for a new attribute of my own... ":-)"
1069 Then access your attributes like so (e.g. after calling ""$self =
1071 SUPER->new();"" in your constructor method):
1072 $self->[0][ATTRIB1] = 'value1';
1074 $self->[0][ATTRIB2] = 'value2';
1075 $self->[0][ATTRIB3] = 'value3';
1076 ...
1077 Beware that if you put anything other than numbers or strings into
1079 your attributes, the methods "clone()" and "copy()" might not work as
1080 expected anymore!
1081 Especially if your attributes contain references to other data struc‐
1083 tures, only the references will be copied, but not the data struc‐
1084 tures themselves.
1085 This may not be what you want.
1087 (You will have to override these two methods and write some of your
1089 own if not.)
1090 In order for the overloaded operators and the "shift_*()" auxiliary
1092 functions from the "Date::Calc::Object" package to work properly (the
1093 latter of which are heavily used in the "Date::Calendar[::Year]" mod‐
1094 ules, for instance), the package name of your subclass (= the one
1095 your objects will be blessed into) is REQUIRED to contain a "::".
1096 Note that you should ONLY subclass "Date::Calc", NEVER
1098 "Date::Calc::Object", since subclassing the latter is less efficient
1099 (because "Date::Calc::Object" is just an empty class which inherits
1100 from "Date::Calc" - subclassing "Date::Calc::Object" would thus just
1101 introduce an additional name space layer to search during Perl's run‐
1102 time method binding process).
1103 If you give your subclass a package name below/inside the "Date::"
1105 namespace, you will also benefit from the fact that all error mes‐
1106 sages produced by the "Date::Calc[::Object]" module (and also the
1107 "Date::Calendar[::Year]" modules, by the way) will appear to have
1108 originated from the place outside of all ""/^Date::/"" modules
1109 (including yours) where one of the "Date::" modules was first called
1110 - i.e., all errors are always blamed on the user, no matter how
1111 deeply nested inside the "Date::" modules they occur, and do not usu‐
1112 ally refer to places inside any of the "Date::" modules (this assumes
1113 that there are no bugs in the "Date::" modules, and that all errors
1114 are always the user's fault ":-)").
1115 Moreover, your module's own error messages will behave in the same
1117 way if you ""use Carp::Clan qw(^Date::);"" at the top of your module
1118 and if you produce all error messages using "carp()" and "croak()"
1119 (instead of "warn()" and "die()", respectively).
1120
1122 1)
1123 # Switch to summer time:
1124 $now = Date::Calc->now();
1125 if (($now ge [2000,3,26,2,0,0]) and
1126 ($now lt [2000,3,26,3,0,0]))
1127 {
1128 $now += [0,0,0,1,0,0];
1129 }
1130 2)
1132 use Date::Calc::Object qw(:all);
1133 Date::Calc->date_format(3);
1135 $date = 0;
1137 while (!$date)
1138 {
1139 print "Please enter the date of your birthday (day-month-year): ";
1140 $date = Date::Calc->new( Decode_Date_EU( scalar(<STDIN>) ) );
1141 if ($date)
1142 {
1143 $resp = 0;
1144 while ($resp !~ /^\s*[YyNn]/)
1145 {
1146 print "Your birthday is: $date\n";
1147 print "Is that correct? (yes/no) ";
1148 $resp = <STDIN>;
1149 }
1150 $date = 0 unless ($resp =~ /^\s*[Yy]/)
1151 }
1152 else
1153 {
1154 print "Unable to parse your birthday. Please try again.\n";
1155 }
1156 }
1157 if ($date + [18,0,0] <= [Today()])
1159 { print "Ok, you are over 18.\n"; }
1160 else
1161 { print "Sorry, you are under 18!\n"; }
1162 For more examples, see the "examples" subdirectory in this distribu‐
1164 tion, and their descriptions in the file "EXAMPLES.txt".
1165
1167 Date::Calc(3), Date::Calendar(3), Date::Calendar::Year(3), Date::Calen‐
1168 dar::Profiles(3).
1169
1171 This man page documents "Date::Calc::Object" version 5.4.
1172
1174 Steffen Beyer
1175 mailto:sb@engelschall.com
1176 http://www.engelschall.com/u/sb/download/
1177
1179 Copyright (c) 2000 - 2004 by Steffen Beyer. All rights reserved.
1180
1182 This package is free software; you can redistribute it and/or modify it
1183 under the same terms as Perl itself, i.e., under the terms of the
1184 "Artistic License" or the "GNU General Public License".
1185 Please refer to the files "Artistic.txt" and "GNU_GPL.txt" in this dis‐
1187 tribution for details!
1188
1190 This package is distributed in the hope that it will be useful, but
1191 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
1192 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
1193 See the "GNU General Public License" for more details.
1195perl v5.8.8 2004-10-03 Date::Calc::Object(3)