1Handler(3) User Contributed Perl Documentation Handler(3)
2
3
4
6 Date::Handler - Easy but complete date object (1.1)
7
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
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
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
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
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
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
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
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
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
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
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
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
488 Benoit Beausejour <bbeausej@pobox.com>
489
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
508 Class::Date(1). Time::Object(1). Date::Calc(1). perl(1).
509
511 Hey! The above document had some coding errors, which are explained
512 below:
513
514 Around line 116:
515 Non-ASCII character seen before =encoding in '(Szabó,'. Assuming
516 CP1252
517
518
519
520perl v5.34.0 2022-01-21 Handler(3)