1NAME
2 Date::Handler - Easy but complete date object (1.1)
3
4SYNOPSIS
5 use Date::Handler;
6
7 my $date = new Date::Handler({ date => time, time_zone => 'Europe/Paris', locale => 'french'});
8 my $date = new Date::Handler({ date => [2001,04,12,03,01,55], time_zone => 'EST', });
9 my $date = new Date::Handler({ date => {
10 year => 2001,
11 month => 4,
12 day => 12,
13 hour => 3,
14 min => 1,
15 sec => 55,
16 },
17 time_zone => 'America/Los_Angeles',
18 locale => 'en_US.ISO8859-15',
19 });
20
21 print $date;
22 print "$date";
23 print $date->AllInfo();
24
25 $date->new() Constructor
26 $date->Year() 2001
27 $date->Month() 1..12
28 $date->Day() 1..31
29 $date->Hour() 0..23
30 $date->Min() 0..59
31 $date->Sec() 0..59
32 $date->Epoch($epoch) Seconds since epoch (GMT)
33 $date->TimeZone() America/Montreal,EST,PST and so on
34 $date->Locale() french, en_US.ISO8859-15, fr_FR.ISO8859-15, spanish and so on
35 $date->SetLocale(locale) Set the locale to the argument, returns locale or undef.
36 $date->LocaleRealName() Current locale's real name on the system
37 $date->TimeZoneName() EST, PST and so on
38 $date->LocalTime() localtime of the object's epoch
39 $date->TimeFormat($format_string) strftime
40 $date->GmtTime() gmtime of object's epoch
41 $date->UtcTime() same as GmtTime()
42 $date->GmtOffset() Offset of object's TZ in seconds
43 $date->MonthName() April
44 $date->WeekDay() 1..7 (1 monday)
45 $date->WeekDayName() Wednesday
46 $date->FirstWeekDayOfMonth() 1..7
47 $date->WeekOfMonth() 1..4
48 $date->DaysInMonth() 31,30,29,28 depending on month and year.
49 $date->IsLeapYear() 1 if true, 0 if false
50 $date->DayLightSavings() 1 if true, 0 if false
51 $date->DayOfYear() Return the day of the year
52 $date->DaysInYear() Returns the number of days in the year.
53 $date->DaysLeftInYear() Returns the number of days remaining in the year
54 $date->Array2Epoch([]) Transfer [y,m,d,h,mm,ss] to epoch time
55 $date->AsScalar () Same as TimeFormat("%A, %B%e %Y %R (%Z)")
56 $date->AsNumber() same as Epoch()
57 $date->AsArray() Returns [y,m,d,h,mm,ss]
58 $date->AsHash() Returns { year => y, month => m, day => d, hour => h, min => mm, sec => ss }
59 $date->AllInfo() Returns a string containing all of the Object's related information.
60
61 my $delta = new Date::Handler::Delta([3,1,10,2,5,5]);
62 my $delta = new Date::Handler::Delta({
63 years => 3,
64 months => 1,
65 days => 10,
66 hours => 2,
67 minutes => 5,
68 seconds => 5,
69 });
70
71 $delta->new (More information in perldoc Date::Handler::Delta)
72 $delta->Months() Number of months in delta
73 $delta->Seconds() Number of seconds in delta
74 $delta->AsScalar() "%d months and %d seconds"
75 $delta->AsNumber() "%d-%d-%d"
76 $delta->AsArray() [y,m,ss]
77 $delta->AsHash() { months => m, seconds => ss }
78
79 $date + $delta = Date::Handler
80 $date - $delta = Date::Handler
81 $date - $date2 = Date::Handler::Delta
82 $date + n = (+n seconds)
83 $date - n = (-n seconds)
84
85 $delta + $delta = Date::Handler::Delta
86 $delta - $delta = Date::Handler::Delta
87 $delta * n = Date::Handler::Delta
88 $delta / n = Date::Handler::Delta
89 $delta + n = (+n seconds)
90 $delta - n = (-n seconds)
91
92 my $range = Date::Handler::Range->new({
93 date => $date,
94 delta => $delta,
95 });
96 my $range = Date::Handler::Range->new({
97 date => [2001,06,08,2,00,00],
98 delta => [0,0,1,0,0],
99 });
100
101 $range->new (More info in perldoc Date::Handler::Range)
102 $range->Direction() Specifies the direction of a range ('FORWARDS' || 'BACKWARDS')
103 $range->StartDate() Start Date::Handler object for this range and direction
104 $range->EndDate() End Date::Handler object for this range and direction
105 $range->Overlaps($range2) Returns true if range overlaps range2. undef otherwise.
106
107DESCRIPTION
108 Date::Handler is a container for dates that holds all the methods to
109 transform itself from Timezone to Timezone and format itself. This
110 module idea comes from an original version written by dLux (Szab�,
111 Bal�zs) <dlux@kapu.hu> in his module Class::Date.
112
113 Date::Handler is implemented in pure Perl using POSIX modules, it
114 encapsulates the environnement variable TZ for it's time zone management
115 so you don't have to play with it externally in the implementation.
116 Date::Handler also supports localisation using POSIX where available.
117
118 It uses operator overloading and Delta date objects to calculates time
119 differences.
120
121IMPLEMENTATION
122 Using the Date::Handler is simple.
123
124 Creating the absolute Date::Handler
125 The new() constructor receives only one argument as a hashref:
126
127 my $date = new Date::Handler({
128 date => time,
129 time_zone => 'Japan',
130 });
131
132 my $date = new Date::Handler({
133 date => time(),
134 time_zone => 'America/Los_Angeles',
135 locale => 'spanish',
136 });
137
138 The 'date' key of this argument can be either:
139
140 * Epoch time
141 * Anonymous array of the form: [y,m,d,h,mm,ss]
142 * A hashref of the form : { year => y,month => m, day => d, hour => h,
143 min => mm, sec => ss }
144
145 The items in the array (or hash) of the 'date' key should follow these
146 rules:
147
148 * year - The year number
149 * mon - The number of months since January, in the range 1 to 12.
150 * day - The day of the month, in the range 1 to 31.
151 * hour - The number of hours past midnight, in the range 0 to 23.
152 * min - The number of minutes after the hour, in the range 0 to 59.
153 * sec - The number of seconds after the minute, normally in the range 0
154 to 59.
155
156 The optional 'time_zone' key represents the time zone name this date is
157 considered in. i.e. Africa/Dakar, EST, PST, EDT
158
159 The optional 'locale' key represents the locale used to represent this
160 date. i.e. spanish, japananese, de_DE.ISO8859-15 , fr_FR.ISO8859-15
161
162 You can also pass an 'intuitive_day' key to the constructor. This is
163 described in the "USING INTUITIVE MONTH CALCULATIONS" section.
164
165 Accessors
166 You can access the data inside the object using any of the provided
167 methods. These methods are detailed in the SYNOPSIS up above.
168
169 Modifying the object
170 A created Date::Handler can be modified on the fly by many ways:
171
172 * Changing the time_zone of the object using TimeZone()
173 * Changing the object's locale on the fly using SetLocale()
174 * Changing the internal date of the object using Epoch()
175 * By using operators in combination with Date::Handler::Delta objects
176 Examples:
177
178 #Start off with a basic object for NOW.
179 my $date = new Date::Handler({ date => time });
180
181 #Go through the time zones...
182 $date->TimeZone('Asia/Tokyo');
183 print "Time in tokyo: ".$date->LocalTime()."\n";
184 $date->Epoch(time);
185 $date->TimeZone('America/Montreal');
186 print "Time in Montreal: ".$date->LocalTime()."\n";
187 $date->TimeZone('GMT');
188 print "Greenwich Mean Time: ".$date->LocalTime()."\n";
189
190 # Go through some locales...
191
192 $date->SetLocale('french');
193 print "Time in ".$date->Locale().": ".$date."\n";
194 $date->SetLocale('deutsch');
195 print "Time in ".$date->Locale().": ".$date."\n";
196 $date->SetLocale('spanish');
197 print "Time in ".$date->Locale().": ".$date."\n";
198
199 Operator overload special cases
200 The Date::Handler overloaded operator have special cases. Refer to the
201 SYNOPSIS to get a description of each overloaded operator's behaviour.
202
203 One special case of the overload is when adding an integer 'n' to a
204 Date::Handler's reference. This is treated as if 'n' was in seconds.
205 Same thing for substraction.
206
207 Example Uses of the overload:
208
209 my $date = new Date::Handler({ date =>
210 {
211 year => 2001,
212 month => 5,
213 day => 14,
214 hour => 5,
215 min => 0,
216 sec => 0,
217 }});
218 #Quoted string overload
219 print "Current date is $date\n";
220
221 my $delta = new Date::Handler::Delta({ days => 5, });
222
223 #'+' overload, now, $date is 5 days in the future.
224 $date += $delta;
225
226 #Small clock. Not too accurate, but still ;)
227 while(1)
228 {
229 #Add one second to the date. (same as $date + 1)
230 $date++;
231 print "$date\n";
232 sleep(1);
233 }
234
235INHERITANCE
236 A useful way of using Date::Handler in your code is to implement that a
237 class that ISA Date::Handler. This way you can overload methods through
238 the inheritance tree and change the object's behaviour to your needs.
239
240 Here is a small example of an overloaded class that specifies a default
241 timezone different than the machine's timezone.
242
243 #!/usr/bin/perl
244 package My::Date::Handler;
245
246 use strict;
247 use vars qw(@ISA $VERSION);
248
249 use Date::Handler;
250 @ISA = qw(Date::Handler);
251
252 use constant DEFAULT_TIMEZONE => 'Europe/Moscow';
253 use consant DEFAULT_LOCALE => 'russian';
254
255 sub TimeZone
256 {
257 my ($self) = @_;
258
259 my $time_zone = $self->SUPER::TimeZone(@_);
260
261 return $time_zone if defined $time_zone;
262
263 return $self->DEFAULT_TIMEZONE();
264 }
265
266 1;
267 __END__
268
269USING INTUITIVE MONTH CALCULATIONS (off by default)
270 Date::Handler contains a feature by witch a date handler object can use
271 intuitive month calculation. This means that Date::Handler will
272 compensate for month overflows during delta operations.
273
274 For example, if you have a date handler that is 2002/01/30, and you add
275 to it a delta of 1 month, standard Date::Handler object will give you a
276 new object that is 2002/03/02. This is because POSIX will compensate for
277 the month overflow and add 2 days to the date because February does not
278 have a 29 or 30th in 2002. Date::Handler can compensate for that by
279 using the INTUITIVE_MONTH_CALCULATIONS constant. (this is turned off by
280 default).
281
282 This constant can be turned on during overloading (inheritance):
283
284 use constant INTUITIVE_MONTH_CALCULATIONS => 1;
285
286 Turning this constant on will tell Date::Handler to follow track of
287 month overflow during operations. This will make it so that adding a
288 month to 2002/01/30 will bring you to 2002/02/28. Adding another month
289 to this will bring you (with intuition) to 2002/03/30, because
290 Date::Handler keeps track of the "intuitive" day of the month.
291
292 Using INTUITIVE_MONTH_CALCULATIONS will also make it possible to pass an
293 "intuitive_day" key to the new() constructor in order to simulate a
294 previous addition.
295
296 i.e.
297
298 my $date = Date::Handler->new({
299 date => [2002,02,28,1,0,0,0],
300 time_zone => 'America/Montreal',
301 intuitive_day => '30',
302 });
303
304 my $onemonth = Date::Handler::Delta->new([0,1,0,0,0,0]);
305
306 print ($date + $onemonth)."\n";
307
308 In this example, the start date of 2002/02/28 with intuitive_day set to
309 30 will make it so that adding 1 month to the date will bring us to
310 march 30th. Note that INTUITIVE_MONTH_CALCULATIONS will only affect
311 month/day calculations and no time modifications will be applied.
312
313USING INTUITIVE_DST_ADJUSTMENTS (off by default)
314 Date::Handler provides a facility called INTUITIVE_DST_ADJUSTMENTS. This
315 is implemented via an inherited constant, like the other options above.
316 When INTUITIVE_DST_ADJUSTMENTS are turned on, Date::Handler will
317 compensate for day light savings changes. For example, 2002/04/07 1AM +
318 1 day would give you 2002/04/08 1AM instead of 2AM. Note that
319 INTUITIVE_DST_ADJUSTMENTS will not apply this compensation when the
320 exact "turn over" date/time is detected. For example, 2002/04/06 2AM + 1
321 day would give you 2002/04/07 3AM because we don't compensate for this
322 specific case.
323
324USING INTUITIVE_TIME_CALCULATIONS (off by default)
325 Date::Handler provides yet another facility to add intuitive date
326 calculations. By using INTUITIVE_TIME_CALCULATIONS (via inherited
327 constant), Date::Handler will "remember" that it compensated for a DST
328 adjustment and try to compensate for it.
329
330 For example, 2002/04/06 2AM + 1day would give you 2002/04/07 3AM. Adding
331 a day to this date under INTUITIVE_TIME_CALCULATIONS would give you
332 2002/04/08 2AM because Date::Handler remembers it compensated for day
333 light savings.
334
335 Combining INTUITIVE_DST_ADJUSTMENTS, INTUITIVE_MONTH_CALCULATIONS and
336 INTUITIVE_TIME_CALCULATIONS will give a behaviour closer to the way
337 humans expect the module to react.
338
339 This can be very useful to make date calculations a little more
340 "humanized".
341
342 The intuitive "hour" can be faked by passing it to the new()
343 constructor:
344
345 package MyDateHandler;
346
347 use strict;
348 use base qw(Date::Handler);
349
350 use constant INTUITIVE_DST_ADJUSTMENTS => 1;
351 use constant INTUITIVE_TIME_CALCULATIONS => 1;
352
353 1;
354
355 then:
356
357 my $date = MyDateHandler->new({
358 date => [2002,04,08,5,0,0],
359 time_zone => 'America/Montreal',
360 intuitive_hour => 2,
361 });
362
363NOTES ON TIME ZONES, LOCALISATION AND FORMATTING
364 Date::Handler supports locales using POSIX setlocale() functions. The
365 allowed values for the locale are listed (on most unix system) using the
366 `locale -a` command. The Date::Handler defaults to "en_US.ISO8859-15" for it's
367 locale when no locale are passed to the constructor. The constant
368 DEFAULT_LOCALE can be overloaded to change this behaviour. Special note
369 that the locales "english" and "en" are not implemented on most linux
370 (Red Hat here) systems. You need to use the locale en_US.ISO8859-15, en_GB.ISO8859-15 etc etc.
371
372 Date::Handler supports time zones using POSIX tzset() and tzname()
373 functions. The allowed values for the time_zone key are listed (on linux
374 systems) by look at the /usr/share/zoneinfo directory. The Date::Handler
375 default to "GMT" for it's time zone when to time_zone key are passed to
376 the constructor. The constant DEFAULT_TIME_ZONE can be overloaded to
377 change this behaviour.
378
379 Date::Handler's formatting is provided by POSIX's strfmtime() function.
380 The allowed parameters to the TimeFormat() method can be listed (on most
381 unix system) using `man strftime`. By default, Date::Handler uses the
382 format string '%c' to represent itself in most cases. The constant
383 DEFAULT_FORMAT_STRING can be overloaded to change this behaviour.
384
385OTHER DATE::HANDLER MODULES
386 Here is a brief description of the other modules in this package.
387
388 Using Date::Handler::Delta objects
389 To go forward or backward in time with a date object, you can use the
390 Date::Handler::Delta objects. These objects represent a time lapse
391 represented in months and seconds. Since Date::Handler uses operator
392 overloading, you can 'apply' a Delta object on an absolute date simply
393 by using '+' and '-'.
394
395 Example:
396
397 #A Delta of 1 year.
398 my $delta = new Date::Handler::Delta([1,0,0,0,0,0]);
399
400 my $date = new Date::Handler({ date => time } );
401
402 #$newdate is now one year in the furure.
403 my $newdate = $date+$delta;
404
405 Refer to the Date::Handler::Delta(1) documentation for more on Deltas.
406
407 Using Date::Handler::Range objects
408 Range objects are used to define a time range using a start date and a
409 delta object. Can be useful to calculate recurrences of events and event
410 overlap.
411
412 Example:
413
414 A simple range for an event of 3 days:
415
416 my $range = Date::Handler::Range->new({
417 date => Date::Handler->new({ date => time() }),
418 delta => Date::Handler::Delta->new([0,0,3,0,0,0]),
419 });
420
421 print "This event starts on ".$range->StartDate()." and end on ".$range->EndDate()."\n";
422
423 See perldoc Date::Handler::Range(1) for more information on how to use
424 Date::Handler::Range objects.
425
426BUGS (known)
427 Dates after 2038 are not handled by this module yet. (POSIX)
428
429 Dates before 1970 are not handled by this module. (POSIX)
430
431 If you find bugs with this module, do not hesitate to contact the
432 author. Your comments and rants are welcomed :)
433
434SUPPORT, CVS AND BLEEDING VERSIONS
435 For the latest developments,changes files, history, CVS access and more,
436 please visit:
437
438 http://labs.turbulent.ca/
439
440 Please, if you use this module in a project, let me know!
441
442 Commercial support for this module is available, please contact me for
443 more info!
444
445TODO
446 Add support for dynamic locale using perllocales functions. This will
447 plugin directly with the use of strftime in the Date::Handler and
448 provide locales.
449
450 Add a list of supported timezones in the Constants class.Just didnt
451 around to do it yet :) Feel free :) If you have patches, recommendations
452 or suggestions on this module, please come forward :)
453
454COPYRIGHT
455 Copyright(c) 2001 Benoit Beausejour <bbeausej@pobox.com>
456
457 All rights reserved. This program is free software; you can redistribute
458 it and/or modify it under the same terms as Perl itself.
459
460 Portions Copyright (c) Philippe M. Chiasson <gozer@cpan.org>
461
462 Portions Copyright (c) Szab�, Bal�zs <dlux@kapu.hu>
463
464 Portions Copyright (c) Larry Rosler
465
466AUTHOR
467 Benoit Beausejour <bbeausej@pobox.com>
468
469CONTRIBUTORS
470 * Ron Savage <ron@savage.net.au>
471 * Roland Rauch <roland@rauch.com>
472 * Patrick Bradley <peanut@burstofindifference.com>
473 * Phillippe M. Chiasson <gozer@cpan.org>
474 * Jamie Letual <jamie@letual.net>
475 * Ethan Joffe <ethan@namimedia.com>
476 * Mathew Robertson <mathew.robertson@redsheriff.com>
477 * Sivaguru Sankaridurg <uc_regents@yahoo.com>
478
479SEE ALSO
480 Class::Date(1). Time::Object(1). Date::Calc(1). perl(1).
481
482