DateTime::Incomplete(3pm)

1DateTime::Incomplete(3)User Contributed Perl DocumentatioDnateTime::Incomplete(3)
2
3
4

NAME

6       DateTime::Incomplete - An incomplete datetime, like January 5
7

SYNOPSIS

9         my $dti = DateTime::Incomplete->new( year => 2003 );
10         # 2003-xx-xx
11         $dti->set( month => 12 );
12         # 2003-12-xx
13         $dt = $dti->to_datetime( base => DateTime->now );
14         # 2003-12-19T16:54:33
15

DESCRIPTION

17       DateTime::Incomplete is a class for representing partial dates and
18       times.
19
20       These are actually encountered relatively frequently.  For example, a
21       birthday is commonly given as a month and day, without a year.
22

ERROR HANDLING

24       Constructor and mutator methods (such as "new" and "set") will die if
25       there is an attempt to set the datetime to an invalid value.
26
27       Invalid values are detected by setting the appropriate fields of a
28       "base" datetime object. See the "set_base" method.
29
30       Accessor methods (such as "day()") will return either a value or
31       "undef", but will never die.
32

THE "BASE" DATETIME

34       A "DateTime::Incomplete" object can have a "base" "DateTime.pm" object.
35       This object is used as a default datetime in the "to_datetime()"
36       method, and it also used to validate inputs to the "set()" method.
37
38       The base object must use the year/month/day system.  Most calendars use
39       this system including Gregorian ("DateTime") and Julian.  Note that
40       this module has not been well tested with base objects from classes
41       other than "DateTime.pm" class.
42
43       By default, newly created "DateTime::Incomplete" objects have no base.
44

DATETIME-LIKE METHODS

46       Most methods provided by this class are designed to emulate the
47       behavior of "DateTime.pm" whenever possible.
48
49       ·   new()
50
51           Creates a new incomplete date:
52
53             my $dti = DateTime::Incomplete->new( year => 2003 );
54             # 2003-xx-xx
55
56           This class method accepts parameters for each date and time
57           component: "year", "month", "day", "hour", "minute", "second",
58           "nanosecond".  Additionally, it accepts "time_zone", "locale", and
59           "base" parameters.
60
61           Any parameters not given default to "undef".
62
63           Calling the "new()" method without parameters creates a completely
64           undefined datetime:
65
66             my $dti = DateTime::Incomplete->new();
67
68       ·   from_day_of_year( ... )
69
70           This constructor takes the same arguments as can be given to the
71           "new()" method, except that it does not accept a "month" or "day"
72           argument.  Instead, it requires both "year" and "day_of_year".  The
73           day of year must be between 1 and 366, and 366 is only allowed for
74           leap years.
75
76           It creates a "DateTime::Incomplete" object with all date fields
77           defined, but with the time fields (hour, minute, etc.) set to
78           undef.
79
80       ·   from_object( object => $object, ... )
81
82           This class method can be used to construct a new
83           "DateTime::Incomplete" object from any object that implements the
84           "utc_rd_values()" method.  All "DateTime::Calendar" modules must
85           implement this method in order to provide cross-calendar
86           compatibility.  This method accepts a "locale" parameter.
87
88           If the object passed to this method has a "time_zone()" method,
89           that is used to set the time zone.  Otherwise UTC is used.
90
91           It creates a "DateTime::Incomplete" object with all fields defined.
92
93       ·   from_epoch( ... )
94
95           This class method can be used to construct a new
96           "DateTime::Incomplete" object from an epoch time instead of
97           components.  Just as with the "new()" method, it accepts
98           "time_zone" and "locale" parameters.
99
100           If the epoch value is not an integer, the part after the decimal
101           will be converted to nanoseconds.  This is done in order to be
102           compatible with "Time::HiRes".
103
104           It creates a "DateTime::Incomplete" object with all fields defined.
105
106       ·   now( ... )
107
108           This class method is equivalent to "DateTime->now".
109
110           It creates a new "DateTime::Incomplete" object with all fields
111           defined.
112
113       ·   today( ... )
114
115           This class method is equivalent to "now()", but it leaves hour,
116           minute, second and nanosecond undefined.
117
118       ·   clone
119
120           Creates a new object with the same information as the object this
121           method is called on.
122
123   "Get" Methods
124       ·   year
125
126       ·   month
127
128       ·   day
129
130       ·   hour
131
132       ·   minute
133
134       ·   second
135
136       ·   nanosecond
137
138       ·   time_zone
139
140       ·   locale
141
142           These methods returns the field value for the object, or "undef".
143
144           These values can also be accessed using the same alias methods
145           available in "DateTime.pm", such as "mon()", "mday()", etc.
146
147       ·   has_year
148
149       ·   has_month
150
151       ·   has_day
152
153       ·   has_hour
154
155       ·   has_minute
156
157       ·   has_second
158
159       ·   has_nanosecond
160
161       ·   has_time_zone
162
163       ·   has_locale
164
165       ·   has_date
166
167       ·   has_time
168
169           Returns a boolean value indicating whether the corresponding
170           component is defined.
171
172           "has_date" tests for year, month, and day.
173
174           "has_time" tests for hour, minute, and second.
175
176       ·   has
177
178               $has_date = $dti->has( 'year', 'month', 'day' );
179
180           Returns a boolean value indicating whether all fields in the
181           argument list are defined.
182
183       ·   defined_fields
184
185               @fields = $dti->defined_fields;   # list of field names
186
187           Returns a list containing the names of the fields that are defined.
188
189           The list order is: year, month, day, hour, minute, second,
190           nanosecond, time_zone, locale.
191
192       ·   datetime, ymd, date, hms, time, iso8601, mdy, dmy
193
194           These are equivalent to DateTime stringification methods with the
195           same name, except that the undefined fields are replaced by 'xx' or
196           'xxxx' as appropriate.
197
198       ·   epoch
199
200       ·   hires_epoch
201
202       ·   is_dst
203
204       ·   utc_rd_values
205
206       ·   utc_rd_as_seconds
207
208               my $epoch = $dti->epoch( base => $dt );
209
210           These methods are equivalent to the "DateTime" methods with the
211           same name.
212
213           They all accept a "base" argument to use in order to calculate the
214           method's return values.
215
216           If no "base" argument is given, then "today" is used.
217
218       ·   is_finite, is_infinite
219
220           Incomplete dates are always "finite".
221
222       ·   strftime( $format, ... )
223
224           This method implements functionality similar to the "strftime()"
225           method in C.  However, if given multiple format strings, then it
226           will return multiple scalars, one for each format string.
227
228           See the "strftime Specifiers" section in the "DateTime.pm"
229           documentation for a list of all possible format specifiers.
230
231           Undefined fields are replaced by 'xx' or 'xxxx' as appropriate.
232
233           The specification %s (epoch) is calculated using "today" as the
234           base date, unless the object has a base datetime set.
235
236       Computed Values
237
238       All other accessors, such as "day_of_week()", or "week_year()" are
239       computed from the base values for a datetime.  When these methods are
240       called, they return the requested information if there is enough data
241       to compute them, otherwise they return "undef"
242
243       Unimplemented Methods
244
245       The following "DateTime.pm" methods are not implemented in
246       "DateTime::Incomplete", though some of them may be implemented in
247       future versions:
248
249       ·   add_duration
250
251       ·   add
252
253       ·   subtract_duration
254
255       ·   subtract
256
257       ·   subtract_datetime
258
259       ·   subtract_datetime_absolute
260
261       ·   delta_md
262
263       ·   delta_days
264
265       ·   delta_ms
266
267       ·   compare
268
269       ·   compare_ignore_floating
270
271       ·   DefaultLanguage
272
273   "Set" Methods
274       ·   set
275
276           Use this to set or undefine a datetime field:
277
278             $dti->set( month => 12 );
279             $dti->set( day => 24 );
280             $dti->set( day => undef );
281
282           This method takes the same arguments as the "set()" method in
283           "DateTime.pm", but it can accept "undef" for any value.
284
285       ·   set_time_zone
286
287           This method accepts either a time zone object or a string that can
288           be passed as the "name" parameter to "DateTime::TimeZone->new()".
289
290           Unlike with "DateTime.pm", if the new time zone's offset is
291           different from the previous time zone, no local time adjustment is
292           made.
293
294           You can remove time zone information by calling this method with
295           the value "undef".
296
297       ·   truncate( to => ... )
298
299           This method allows you to reset some of the local time components
300           in the object to their "zero" values.  The "to" parameter is used
301           to specify which values to truncate, and it may be one of "year",
302           "month", "day", "hour", "minute", or "second".  For example, if
303           "month" is specified, then the local day becomes 1, and the hour,
304           minute, and second all become 0.
305
306           Note that the "to" parameter cannot be "week".
307

"DATETIME::INCOMPLETE" METHODS

309       "DateTime::Incomplete" objects also have a number of methods unique to
310       this class.
311
312       ·   base
313
314           Returns the base datetime value, or "undef" if the object has none.
315
316       ·   has_base
317
318           Returns a boolean value indicating whether or not the object has a
319           base datetime set.
320
321       ·   is_undef
322
323           Returns true if the datetime is completely undefined.
324
325       ·   can_be_datetime
326
327           Returns true if the datetime has enough information to be converted
328           to a proper DateTime object.
329
330           The year field must be valid, followed by a sequence of valid
331           fields.
332
333           Examples:
334
335             Can be datetime:
336             2003-xx-xxTxx:xx:xx
337             2003-10-xxTxx:xx:xx
338             2003-10-13Txx:xx:xx
339
340             Can not be datetime:
341             2003-10-13Txx:xx:30
342             xxxx-10-13Txx:xx:30
343
344       ·   set_base
345
346           Sets the base datetime object for the "DateTime::Incomplete"
347           object.
348
349           The default value for "base" is "undef", which means no validation
350           is made on input.
351
352       ·   to_datetime
353
354           This method takes an optional "base" parameter and returns a
355           "complete" datetime.
356
357             $dt = $dti->to_datetime( base => DateTime->now );
358
359             $dti->set_base( DateTime->now );
360             $dt = $dti->to_datetime;
361
362           The resulting datetime can be either before of after the given base
363           datetime. No adjustments are made, besides setting the missing
364           fields.
365
366           This method will use "today" if the object has no base datetime set
367           and none is given as an argument.
368
369           This method may die if it results in a datetime that doesn't
370           actually exist, such as February 30, for example.
371
372           The fields in the resulting datetime are set in this order: locale,
373           time_zone, nanosecond, second, minute, hour, day, month, year.
374
375       ·   to_recurrence
376
377           This method generates the set of all possible datetimes that fit
378           into an incomplete datetime definition.
379
380             $dti = DateTime::Incomplete->new( month => 12, day => 24 );
381             $dtset1 = $dti->to_recurrence;
382             # Christmas recurrence, with _seconds_ resolution
383
384             $dti->truncate( to => 'day' );
385             $dtset2 = $dti->to_recurrence;
386             # Christmas recurrence, with days resolution (hour/min/sec = 00:00:00)
387
388           Those recurrences are "DateTime::Set" objects:
389
390             $dt_next_xmas = $dti->to_recurrence->next( DateTime->today );
391
392           Incomplete dates that have the year defined will generate finite
393           sets.  This kind of set can take a lot of resources (RAM and CPU).
394           The following incomplete datetime would generate the set of all
395           seconds in 2003:
396
397             2003-xx-xxTxx:xx:xx
398
399           Recurrences are generated with up to 1 second resolution.  The
400           "nanosecond" value is ignored.
401
402       ·   to_spanset
403
404           This method generates the set of all possible spans that fit into
405           an incomplete datetime definition.
406
407             $dti = DateTime::Incomplete->new( month => 12, day => 24 );
408             $dtset1 = $dti->to_spanset;
409             # Christmas recurrence, from xxxx-12-24T00:00:00
410             #                         to xxxx-12-25T00:00:00
411
412       ·   start
413
414       ·   end
415
416       ·   to_span
417
418           These methods view an incomplete datetime as a "time span".
419
420           For example, the incomplete datetime "2003-xx-xxTxx:xx:xx" starts
421           in "2003-01-01T00:00:00" and ends in "2004-01-01T00:00:00".
422
423           The "to_span" method returns a "DateTime::Span" object.
424
425           An incomplete datetime without an year spans "forever".  Start and
426           end datetimes are "undef".
427
428       ·   contains
429
430           Returns a true value if the incomplete datetime range contains a
431           given datetime value.
432
433           For example:
434
435             2003-xx-xx contains 2003-12-24
436             2003-xx-xx does not contain 1999-12-14
437
438       ·   previous / next / closest
439
440             $dt2 = $dti->next( $dt );
441
442           The "next()" returns the first complete date after or equal to the
443           given datetime.
444
445           The "previous()" returns the first complete date before or equal to
446           the given datetime.
447
448           The "closest()" returns the closest complete date (previous or
449           next) to the given datetime.
450
451           All of these methods return "undef" if there is no matching
452           complete datetime.
453
454           If no datetime is given, these methods use the "base" datetime.
455
456           Note: The definition of "previous()" and "next()" is different from
457           the methods of the same name in the "DateTime::Set" class.
458
459           The datetimes are generated with 1 nanosecond precision. The last
460           "time" value of a given day is 23:59:59.999999999 (for non
461           leapsecond days).
462

SUPPORT

464       Support for this module is provided via the datetime@perl.org email
465       list.  See http://lists.perl.org/ for more details.
466

AUTHORS

468       Flavio S. Glock <fglock[at]cpan.org>
469
470       With Ben Bennett <fiji[at]ayup.limey.net>, Claus Farber
471       <claus[at]xn--frber-gra.muc.de>, Dave Rolsky <autarch[at]urth.org>,
472       Eugene Van Der Pijll <pijll[at]gmx.net>, Rick Measham
473       <rick[at]isite.net.au>, and the DateTime team.
474

COPYRIGHT

476       Copyright (c) 2003 Flavio S. Glock.  All rights reserved.  This program
477       is free software; you can redistribute it and/or modify it under the
478       same terms as Perl itself.
479
480       The full text of the license can be found in the LICENSE file included
481       with this module.
482