1Handler(3) User Contributed Perl Documentation Handler(3)
2
6 Date::Handler - Easy but complete date object (1.1)
7
9 use Date::Handler;
10 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 print $date;
26 print "$date";
27 print $date->AllInfo();
28 $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 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 $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 $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 $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 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 $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 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 It uses operator overloading and Delta date objects to calculates time
126 differences.
127
129 Using the Date::Handler is simple.
130 Creating the absolute Date::Handler
132 The new() constructor receives only one argument as a hashref:
133 my $date = new Date::Handler({
135 date => time,
136 time_zone => 'Japan',
137 });
138 my $date = new Date::Handler({
141 date => time(),
142 time_zone => 'America/Los_Angeles',
143 locale => 'spanish',
144 });
145 The 'date' key of this argument can be either:
147 • Epoch time
149 • Anonymous array of the form: [y,m,d,h,mm,ss]
151 • A hashref of the form : { year => y,month => m, day => d, hour => h,
153 min => mm, sec => ss }
154 The items in the array (or hash) of the 'date' key should follow these
156 rules:
157 • year - The year number
159 • mon - The number of months since January, in the range 1 to 12.
161 • day - The day of the month, in the range 1 to 31.
163 • hour - The number of hours past midnight, in the range 0 to 23.
165 • min - The number of minutes after the hour, in the range 0 to
167 59.
168 • sec - The number of seconds after the minute, normally in the
170 range 0 to 59.
171 The optional 'time_zone' key represents the time zone name this date is
173 considered in. i.e. Africa/Dakar, EST, PST, EDT
174 The optional 'locale' key represents the locale used to represent this
176 date. i.e. spanish, japananese, de_DE , fr_FR
177 You can also pass an 'intuitive_day' key to the constructor. This is
179 described in the "USING INTUITIVE MONTH CALCULATIONS" section.
180 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 Modifying the object
186 A created Date::Handler can be modified on the fly by many ways:
187 • Changing the time_zone of the object using TimeZone()
189 • Changing the object's locale on the fly using SetLocale()
191 • Changing the internal date of the object using Epoch()
193 • By using operators in combination with Date::Handler::Delta objects
195 Examples:
197 #Start off with a basic object for NOW.
199 my $date = new Date::Handler({ date => time });
200 #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 # Go through some locales...
211 $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 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 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 Example Uses of the overload:
228 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 my $delta = new Date::Handler::Delta({ days => 5, });
242 #'+' overload, now, $date is 5 days in the future.
244 $date += $delta;
245 #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 Here is a small example of an overloaded class that specifies a default
261 timezone different than the machine's timezone.
262 #!/usr/bin/perl
264 package My::Date::Handler;
265 use strict;
267 use vars qw(@ISA $VERSION);
268 use Date::Handler;
270 @ISA = qw(Date::Handler);
271 use constant DEFAULT_TIMEZONE => 'Europe/Moscow';
273 use consant DEFAULT_LOCALE => 'russian';
274 sub TimeZone
276 {
277 my ($self) = @_;
278 my $time_zone = $self->SUPER::TimeZone(@_);
280 return $time_zone if defined $time_zone;
282 return $self->DEFAULT_TIMEZONE();
284 }
285 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 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 This constant can be turned on during overloading (inheritance):
303 use constant INTUITIVE_MONTH_CALCULATIONS => 1;
305 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 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 i.e.
317 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 my $onemonth = Date::Handler::Delta->new([0,1,0,0,0,0]);
325 print ($date + $onemonth)."\n";
327 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 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 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 This can be very useful to make date calculations a little more
360 "humanized".
361 The intuitive "hour" can be faked by passing it to the new()
363 constructor:
364 package MyDateHandler;
366 use strict;
368 use base qw(Date::Handler);
369 use constant INTUITIVE_DST_ADJUSTMENTS => 1;
371 use constant INTUITIVE_TIME_CALCULATIONS => 1;
372 1;
374 then:
376 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 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 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 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 Example:
417 #A Delta of 1 year.
419 my $delta = new Date::Handler::Delta([1,0,0,0,0,0]);
420 my $date = new Date::Handler({ date => time } );
422 #$newdate is now one year in the furure.
424 my $newdate = $date+$delta;
425 Refer to the Date::Handler::Delta(1) documentation for more on Deltas.
427 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 Example:
434 A simple range for an event of 3 days:
436 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 print "This event starts on ".$range->StartDate()." and end on ".$range->EndDate()."\n";
443 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 Dates before 1970 are not handled by this module. (POSIX)
451 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 http://labs.turbulent.ca/
460 Please, if you use this module in a project, let me know!
462 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 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 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 Portions Copyright (c) Philippe M. Chiasson <gozer@cpan.org>
482 Portions Copyright (c) Szabó, Balázs <dlux@kapu.hu>
484 Portions Copyright (c) Larry Rosler
486
488 Benoit Beausejour <bbeausej@pobox.com>
489
491 • Ron Savage <ron@savage.net.au>
492 • Roland Rauch <roland@rauch.com>
494 • Patrick Bradley <peanut@burstofindifference.com>
496 • Phillippe M. Chiasson <gozer@cpan.org>
498 • Jamie Letual <jamie@letual.net>
500 • Ethan Joffe <ethan@namimedia.com>
502 • Mathew Robertson <mathew.robertson@redsheriff.com>
504 • Sivaguru Sankaridurg <uc_regents@yahoo.com>
506
508 Class::Date(1). Time::Object(1). Date::Calc(1). perl(1).
509perl v5.38.0 2023-09-25 Handler(3)