1Handler(3)            User Contributed Perl Documentation           Handler(3)
2
3
4

NAME

6       Date::Handler - Easy but complete date object (1.1)
7

SYNOPSIS

9         use Date::Handler;
10
11         my $date = new Date::Handler({ date => time, time_zone => 'Europe/Paris', locale => 'french'});
12         my $date = new Date::Handler({ date => [2001,04,12,03,01,55], time_zone => 'EST', });
13         my $date = new Date::Handler({ date => {
14                                                       year => 2001,
15                                                       month => 4,
16                                                       day => 12,
17                                                       hour => 3,
18                                                       min => 1,
19                                                       sec => 55,
20                                               },
21                                               time_zone => 'America/Los_Angeles',
22                                               locale => 'en_US',
23                                       });
24
25          print $date;
26          print "$date";
27          print $date->AllInfo();
28
29          $date->new()                         Constructor
30          $date->Year()                        2001
31          $date->Month()                       1..12
32          $date->Day()                         1..31
33          $date->Hour()                        0..23
34          $date->Min()                         0..59
35          $date->Sec()                         0..59
36          $date->Epoch($epoch)                 Seconds since epoch (GMT)
37          $date->TimeZone()                    America/Montreal,EST,PST and so on
38          $date->Locale()                      french, en_US, fr_FR, spanish and so on
39          $date->SetLocale(locale)             Set the locale to the argument, returns locale or undef.
40          $date->LocaleRealName()              Current locale's real name on the system
41          $date->TimeZoneName()                EST, PST and so on
42          $date->LocalTime()                   localtime of the object's epoch
43          $date->TimeFormat($format_string)    strftime
44          $date->GmtTime()                     gmtime of object's epoch
45          $date->UtcTime()                     same as GmtTime()
46          $date->GmtOffset()                   Offset of object's TZ in seconds
47          $date->MonthName()                   April
48          $date->WeekDay()                     1..7 (1 monday)
49          $date->WeekDayName()                 Wednesday
50          $date->FirstWeekDayOfMonth()         1..7
51          $date->WeekOfMonth()                 1..4
52          $date->DaysInMonth()                 31,30,29,28 depending on month and year.
53          $date->IsLeapYear()                  1 if true, 0 if false
54          $date->DayLightSavings()             1 if true, 0 if false
55          $date->DayOfYear()                   Return the day of the year
56          $date->DaysInYear()                  Returns the number of days in the year.
57          $date->DaysLeftInYear()              Returns the number of days remaining in the year
58          $date->Array2Epoch([])                       Transfer [y,m,d,h,mm,ss] to epoch time
59          $date->AsScalar ()                   Same as TimeFormat("%A, %B%e %Y %R (%Z)")
60          $date->AsNumber()                    same as Epoch()
61          $date->AsArray()                     Returns [y,m,d,h,mm,ss]
62          $date->AsHash()                      Returns { year => y, month => m, day => d, hour => h, min => mm, sec => ss }
63          $date->AllInfo()                     Returns a string containing all of the Object's related information.
64
65
66          my $delta = new Date::Handler::Delta([3,1,10,2,5,5]);
67          my $delta = new Date::Handler::Delta({
68                                                       years => 3,
69                                                       months => 1,
70                                                       days => 10,
71                                                       hours => 2,
72                                                       minutes => 5,
73                                                       seconds => 5,
74                                               });
75
76          $delta->new                          (More information in perldoc Date::Handler::Delta)
77          $delta->Months()                     Number of months in delta
78          $delta->Seconds()                    Number of seconds in delta
79          $delta->AsScalar()                   "%d months and %d seconds"
80          $delta->AsNumber()                   "%d-%d-%d"
81          $delta->AsArray()                    [y,m,ss]
82          $delta->AsHash()                     { months => m, seconds => ss }
83
84          $date + $delta = Date::Handler
85          $date - $delta = Date::Handler
86          $date - $date2 = Date::Handler::Delta
87          $date + n = (+n seconds)
88          $date - n = (-n seconds)
89
90          $delta + $delta = Date::Handler::Delta
91          $delta - $delta = Date::Handler::Delta
92          $delta * n = Date::Handler::Delta
93          $delta / n = Date::Handler::Delta
94          $delta + n = (+n seconds)
95          $delta - n = (-n seconds)
96
97
98          my $range = Date::Handler::Range->new({
99                                                       date => $date,
100                                                       delta => $delta,
101                                               });
102          my $range = Date::Handler::Range->new({
103                                                       date => [2001,06,08,2,00,00],
104                                                       delta => [0,0,1,0,0],
105                                               });
106
107          $range->new                  (More info in perldoc Date::Handler::Range)
108          $range->Direction()          Specifies the direction of a range ('FORWARDS' || 'BACKWARDS')
109          $range->StartDate()          Start Date::Handler object for this range and direction
110          $range->EndDate()            End Date::Handler object for this range and direction
111          $range->Overlaps($range2)    Returns true if range overlaps range2. undef otherwise.
112

DESCRIPTION

114       Date::Handler is a container for dates that holds all the methods to
115       transform itself from Timezone to Timezone and format itself. This
116       module idea comes from an original version written by dLux (Szabó,
117       Balázs) <dlux@kapu.hu> in his module Class::Date.
118
119       Date::Handler is implemented in pure Perl using POSIX modules, it
120       encapsulates the environnement variable TZ for it's time zone
121       management so you don't have to play with it externally in the
122       implementation. Date::Handler also supports localisation using POSIX
123       where available.
124
125       It uses operator overloading and Delta date objects to calculates time
126       differences.
127

IMPLEMENTATION

129       Using the Date::Handler is simple.
130
131   Creating the absolute Date::Handler
132       The new() constructor receives only one argument as a hashref:
133
134               my $date = new Date::Handler({
135                                       date => time,
136                                       time_zone => 'Japan',
137                               });
138
139
140               my $date = new Date::Handler({
141                                       date => time(),
142                                       time_zone => 'America/Los_Angeles',
143                                       locale => 'spanish',
144                               });
145
146       The 'date' key of this argument can be either:
147
148       •  Epoch time
149
150       •  Anonymous array of the form: [y,m,d,h,mm,ss]
151
152       •  A hashref of the form : { year => y,month => m, day => d, hour => h,
153          min => mm, sec => ss }
154
155       The items in the array (or hash) of the 'date' key should follow these
156       rules:
157
158       •  year -    The year number
159
160       •  mon  -    The number of months since January, in the range 1 to 12.
161
162       •  day  -    The day of the month, in the range 1 to 31.
163
164       •  hour -    The number of hours past midnight, in the range 0 to 23.
165
166       •  min  -    The number of minutes after the hour, in the range 0 to
167          59.
168
169       •  sec  -    The number of seconds after the minute, normally in the
170          range 0 to 59.
171
172       The optional 'time_zone' key represents the time zone name this date is
173       considered in.  i.e. Africa/Dakar, EST, PST, EDT
174
175       The optional 'locale' key represents the locale used to represent this
176       date. i.e. spanish, japananese, de_DE , fr_FR
177
178       You can also pass an 'intuitive_day' key to the constructor. This is
179       described in the "USING INTUITIVE MONTH CALCULATIONS" section.
180
181   Accessors
182       You can access the data inside the object using any of the provided
183       methods.  These methods are detailed in the SYNOPSIS up above.
184
185   Modifying the object
186       A created Date::Handler can be modified on the fly by many ways:
187
188       •  Changing the time_zone of the object using TimeZone()
189
190       •  Changing the object's locale on the fly using SetLocale()
191
192       •  Changing the internal date of the object using Epoch()
193
194       •  By using operators in combination with Date::Handler::Delta objects
195
196       Examples:
197
198               #Start off with a basic object for NOW.
199               my $date = new Date::Handler({ date => time });
200
201               #Go through the time zones...
202               $date->TimeZone('Asia/Tokyo');
203               print "Time in tokyo: ".$date->LocalTime()."\n";
204               $date->Epoch(time);
205               $date->TimeZone('America/Montreal');
206               print "Time in Montreal: ".$date->LocalTime()."\n";
207               $date->TimeZone('GMT');
208               print "Greenwich Mean Time: ".$date->LocalTime()."\n";
209
210               # Go through some locales...
211
212               $date->SetLocale('french');
213               print "Time in ".$date->Locale().": ".$date."\n";
214               $date->SetLocale('deutsch');
215               print "Time in ".$date->Locale().": ".$date."\n";
216               $date->SetLocale('spanish');
217               print "Time in ".$date->Locale().": ".$date."\n";
218
219   Operator overload special cases
220       The Date::Handler overloaded operator have special cases. Refer to the
221       SYNOPSIS to get a description of each overloaded operator's behaviour.
222
223       One special case of the overload is when adding an integer 'n' to a
224       Date::Handler's reference. This is treated as if 'n' was in seconds.
225       Same thing for substraction.
226
227       Example Uses of the overload:
228
229               my $date = new Date::Handler({ date =>
230                                               {
231                                                       year => 2001,
232                                                       month => 5,
233                                                       day => 14,
234                                                       hour => 5,
235                                                       min => 0,
236                                                       sec => 0,
237                                               }});
238               #Quoted string overload
239               print "Current date is $date\n";
240
241               my $delta = new Date::Handler::Delta({ days => 5, });
242
243               #'+' overload, now, $date is 5 days in the future.
244               $date += $delta;
245
246               #Small clock. Not too accurate, but still ;)
247               while(1)
248               {
249                       #Add one second to the date. (same as $date + 1)
250                       $date++;
251                       print "$date\n";
252                       sleep(1);
253               }
254

INHERITANCE

256       A useful way of using Date::Handler in your code is to implement that a
257       class that ISA Date::Handler. This way you can overload methods through
258       the inheritance tree and change the object's behaviour to your needs.
259
260       Here is a small example of an overloaded class that specifies a default
261       timezone different than the machine's timezone.
262
263               #!/usr/bin/perl
264               package My::Date::Handler;
265
266               use strict;
267               use vars qw(@ISA $VERSION);
268
269               use Date::Handler;
270               @ISA = qw(Date::Handler);
271
272               use constant DEFAULT_TIMEZONE => 'Europe/Moscow';
273               use consant DEFAULT_LOCALE => 'russian';
274
275               sub TimeZone
276               {
277                       my ($self) = @_;
278
279                       my $time_zone = $self->SUPER::TimeZone(@_);
280
281                       return $time_zone if defined $time_zone;
282
283                       return $self->DEFAULT_TIMEZONE();
284               }
285
286               1;
287               __END__
288

USING INTUITIVE MONTH CALCULATIONS (off by default)

290       Date::Handler contains a feature by witch a date handler object can use
291       intuitive month calculation. This means that Date::Handler will
292       compensate for month overflows during delta operations.
293
294       For example, if you have a date handler that is 2002/01/30, and you add
295       to it a delta of 1 month, standard Date::Handler object will give you a
296       new object that is 2002/03/02.  This is because POSIX will compensate
297       for the month overflow and add 2 days to the date because February does
298       not have a 29 or 30th in 2002. Date::Handler can compensate for that by
299       using the INTUITIVE_MONTH_CALCULATIONS constant. (this is turned off by
300       default).
301
302       This constant can be turned on during overloading (inheritance):
303
304               use constant INTUITIVE_MONTH_CALCULATIONS => 1;
305
306       Turning this constant on will tell Date::Handler to follow track of
307       month overflow during operations. This will make it so that adding a
308       month to 2002/01/30 will bring you to 2002/02/28. Adding another month
309       to this will bring you (with intuition) to 2002/03/30, because
310       Date::Handler keeps track of the "intuitive" day of the month.
311
312       Using INTUITIVE_MONTH_CALCULATIONS will also make it possible to pass
313       an "intuitive_day" key to the new() constructor in order to simulate a
314       previous addition.
315
316               i.e.
317
318               my $date = Date::Handler->new({
319                                       date => [2002,02,28,1,0,0,0],
320                                       time_zone => 'America/Montreal',
321                                       intuitive_day => '30',
322               });
323
324               my $onemonth = Date::Handler::Delta->new([0,1,0,0,0,0]);
325
326               print ($date + $onemonth)."\n";
327
328       In this example, the start date of 2002/02/28 with intuitive_day set to
329       30 will make it so that adding 1 month to the date will bring us to
330       march 30th. Note that INTUITIVE_MONTH_CALCULATIONS will only affect
331       month/day calculations and no time modifications will be applied.
332

USING INTUITIVE_DST_ADJUSTMENTS (off by default)

334       Date::Handler provides a facility called INTUITIVE_DST_ADJUSTMENTS.
335       This is implemented via an inherited constant, like the other options
336       above. When INTUITIVE_DST_ADJUSTMENTS are turned on, Date::Handler will
337       compensate for day light savings changes. For example, 2002/04/07 1AM +
338       1 day would give you 2002/04/08 1AM instead of 2AM. Note that
339       INTUITIVE_DST_ADJUSTMENTS will not apply this compensation when the
340       exact "turn over" date/time is detected. For example, 2002/04/06 2AM +
341       1 day would give you 2002/04/07 3AM because we don't compensate for
342       this specific case.
343

USING INTUITIVE_TIME_CALCULATIONS (off by default)

345       Date::Handler provides yet another facility to add intuitive date
346       calculations. By using INTUITIVE_TIME_CALCULATIONS (via inherited
347       constant), Date::Handler will "remember" that it compensated for a DST
348       adjustment and try to compensate for it.
349
350       For example, 2002/04/06 2AM + 1day would give you 2002/04/07 3AM.
351       Adding a day to this date under INTUITIVE_TIME_CALCULATIONS would give
352       you 2002/04/08 2AM because Date::Handler remembers it compensated for
353       day light savings.
354
355       Combining INTUITIVE_DST_ADJUSTMENTS, INTUITIVE_MONTH_CALCULATIONS and
356       INTUITIVE_TIME_CALCULATIONS will give a behaviour closer to the way
357       humans expect the module to react.
358
359       This can be very useful to make date calculations a little more
360       "humanized".
361
362       The intuitive "hour" can be faked by passing it to the new()
363       constructor:
364
365               package MyDateHandler;
366
367               use strict;
368               use base qw(Date::Handler);
369
370               use constant INTUITIVE_DST_ADJUSTMENTS => 1;
371               use constant INTUITIVE_TIME_CALCULATIONS => 1;
372
373               1;
374
375       then:
376
377               my $date = MyDateHandler->new({
378                               date => [2002,04,08,5,0,0],
379                               time_zone => 'America/Montreal',
380                               intuitive_hour => 2,
381               });
382

NOTES ON TIME ZONES, LOCALISATION AND FORMATTING

384       Date::Handler supports locales using POSIX setlocale() functions. The
385       allowed values for the locale are listed (on most unix system) using
386       the `locale -a` command. The Date::Handler defaults to "en_US" for it's
387       locale when no locale are passed to the constructor. The constant
388       DEFAULT_LOCALE can be overloaded to change this behaviour. Special note
389       that the locales "english" and "en" are not implemented on most linux
390       (Red Hat here) systems. You need to use the locale en_US, en_GB etc
391       etc.
392
393       Date::Handler supports time zones using POSIX tzset() and tzname()
394       functions. The allowed values for the time_zone key are listed (on
395       linux systems) by look at the /usr/share/zoneinfo directory. The
396       Date::Handler default to "GMT" for it's time zone when to time_zone key
397       are passed to the constructor. The constant DEFAULT_TIME_ZONE can be
398       overloaded to change this behaviour.
399
400       Date::Handler's formatting is provided by POSIX's strfmtime() function.
401       The allowed parameters to the TimeFormat() method can be listed (on
402       most unix system) using `man strftime`. By default, Date::Handler uses
403       the format string '%c' to represent itself in most cases. The constant
404       DEFAULT_FORMAT_STRING can be overloaded to change this behaviour.
405

OTHER DATE::HANDLER MODULES

407       Here is a brief description of the other modules in this package.
408
409   Using Date::Handler::Delta objects
410       To go forward or backward in time with a date object, you can use the
411       Date::Handler::Delta objects. These objects represent a time lapse
412       represented in months and seconds. Since Date::Handler uses operator
413       overloading, you can 'apply' a Delta object on an absolute date simply
414       by using '+' and '-'.
415
416       Example:
417
418               #A Delta of 1 year.
419               my $delta = new Date::Handler::Delta([1,0,0,0,0,0]);
420
421               my $date = new Date::Handler({ date => time } );
422
423               #$newdate is now one year in the furure.
424               my $newdate = $date+$delta;
425
426       Refer to the Date::Handler::Delta(1) documentation for more on Deltas.
427
428   Using Date::Handler::Range objects
429       Range objects are used to define a time range using a start date and a
430       delta object.  Can be useful to calculate recurrences of events and
431       event overlap.
432
433       Example:
434
435               A simple range for an event of 3 days:
436
437               my $range = Date::Handler::Range->new({
438                                                               date => Date::Handler->new({ date => time() }),
439                                                               delta => Date::Handler::Delta->new([0,0,3,0,0,0]),
440                                                       });
441
442               print "This event starts on ".$range->StartDate()." and end on ".$range->EndDate()."\n";
443
444       See perldoc Date::Handler::Range(1) for more information on how to use
445       Date::Handler::Range objects.
446

BUGS (known)

448       Dates after 2038 are not handled by this module yet. (POSIX)
449
450       Dates before 1970 are not handled by this module. (POSIX)
451
452       If you find bugs with this module, do not hesitate to contact the
453       author.  Your comments and rants are welcomed :)
454

SUPPORT, CVS AND BLEEDING VERSIONS

456       For the latest developments,changes files, history, CVS access and
457       more, please visit:
458
459       http://labs.turbulent.ca/
460
461       Please, if you use this module in a project, let me know!
462
463       Commercial support for this module is available, please contact me for
464       more info!
465

TODO

467       Add support for dynamic locale using perllocales functions. This will
468       plugin directly with the use of strftime in the Date::Handler and
469       provide locales.
470
471       Add a list of supported timezones in the Constants class.Just didnt
472       around to do it yet :) Feel free :) If you have patches,
473       recommendations or suggestions on this module, please come forward :)
474
476       Copyright(c) 2001 Benoit Beausejour <bbeausej@pobox.com>
477
478       All rights reserved. This program is free software; you can
479       redistribute it and/or modify it under the same terms as Perl itself.
480
481       Portions Copyright (c) Philippe M. Chiasson <gozer@cpan.org>
482
483       Portions Copyright (c) Szabó, Balázs <dlux@kapu.hu>
484
485       Portions Copyright (c) Larry Rosler
486

AUTHOR

488       Benoit Beausejour <bbeausej@pobox.com>
489

CONTRIBUTORS

491       •  Ron Savage <ron@savage.net.au>
492
493       •  Roland Rauch <roland@rauch.com>
494
495       •  Patrick Bradley <peanut@burstofindifference.com>
496
497       •  Phillippe M. Chiasson <gozer@cpan.org>
498
499       •  Jamie Letual <jamie@letual.net>
500
501       •  Ethan Joffe <ethan@namimedia.com>
502
503       •  Mathew Robertson <mathew.robertson@redsheriff.com>
504
505       •  Sivaguru Sankaridurg <uc_regents@yahoo.com>
506

SEE ALSO

508       Class::Date(1).  Time::Object(1).  Date::Calc(1).  perl(1).
509
510
511
512perl v5.38.0                      2023-09-25                        Handler(3)
Impressum