1Date::Manip::Base(3)  User Contributed Perl Documentation Date::Manip::Base(3)
2
3
4

NAME

6       Date::Manip::Base - Base methods for date manipulation
7

SYNOPSIS

9          use Date::Manip::Base;
10          $dmb = new Date::Manip::Base;
11

DESCRIPTION

13       The Date::Manip package of modules consists of several modules for
14       doing high level date operations with full error checking and a lot of
15       flexibility.
16
17       The high level operations, though intended to be used in most
18       situations, have a lot of overhead associated with them. As such, a
19       number of the most useful low level routines (which the high level
20       routines use to do much of the real work) are included in this module
21       and are available directly to users.
22
23       These low level routines are powerful enough that they can be used
24       independent of the high level routines and perform useful (though much
25       simpler) operations. They are also significantly faster than the high
26       level routines.
27
28       These routines do NO error checking on input. Invalid data will result
29       in meaningless results.  If you need error checking, you must call the
30       higher level Date::Manip routines instead of these.
31
32       These routines also ignore all effects of time zones and daylight
33       savings time. One way to think of these routines is working with times
34       and dates in the GMT time zone.
35

BASE METHODS

37       This class inherits several base methods from the Date::Manip::Obj
38       class. Please refer to the documentation for that class for a
39       description of those methods.
40
41       err
42       new
43       new_config
44           Please refer to the Date::Manip::Obj documentation for these
45           methods.
46
47       config
48              $dmb->config($var1,$val1,$var2,$val2,...);
49
50           This will set the value of any configuration variable. Please refer
51           to the Date::Manip::Config manual for a list of all configuration
52           variables and their description.
53

DATE METHODS

55       In all of the following methods, the following variables are used:
56
57       $date
58           This is a list reference containing a full date and time:
59
60              [$y, $m, $d, $h, $mn, $s]
61
62       $ymd
63           A list reference containing only the date portion:
64
65              [$y, $m, $d]
66
67       $hms
68           A list reference containing only the time portion:
69
70              [$h, $mn, $s]
71
72       $time
73           A list reference containing an amount of time:
74
75              [$dh, $dmn, $ds]
76
77       $delta
78           A list containing a full delta:
79
80              [$dy, $dm, $dw, $dd, $dh, $dmn, $ds]
81
82       $offset
83           A list containing a time zone expressed as an offset:
84
85              [ $offh, $offm, $offs ]
86
87       In all of the above, the elements ($y, $m, $d, $h, $mn, $s) are all
88       numeric. In most of the routines described below, no error checking is
89       done on the input.  $y should be between 1 and 9999, $m between 1 and
90       12, $d between 1 and 31, $h should be between 0 and 23, $mn and $s
91       between 0 and 59.
92
93       $hms can be between 00:00:00 and 24:00:00, but an $offset must be
94       between -23:59:59 and +23:59:59.
95
96       Years are not translated to 4 digit years, so passing in a year of "04"
97       will be equivalent to "0004", NOT "2004".
98
99       The elements ($dy, $dm, $dw, $dd, $dh, $dmn, $ds) are all numeric, but
100       can be positive or negative. They represent an elapsed amount of time
101       measured in years, months, weeks, etc.
102
103       Since no error checking is done, passing in ($y,$m,$d) = (2004,2,31)
104       will NOT trigger an error, even though February does not have 31 days.
105       Instead, some meaningless result will be returned.
106
107       calc_date_date
108       calc_date_days
109       calc_date_delta
110       calc_date_time
111       calc_time_time
112           These are all routines for doing simple date and time calculations.
113           As mentioned above, they ignore all affects of time zones and
114           daylight savings time.
115
116           The following methods are available:
117
118              $time = $dmb->calc_date_date($date1,$date2);
119
120           This take two dates and determine the amount of time between them.
121
122              $date = $dmb->calc_date_days($date,$n [,$subtract]);
123              $ymd  = $dmb->calc_date_days($ymd,$n [,$subtract]);
124
125           This returns a date $n days later (if $n>0) or earlier (if $n<0)
126           than the date passed in. If $subtract is passed in, the sign of $n
127           is reversed.
128
129              $date = $dmb->calc_date_delta($date,$delta [,$subtract]);
130
131           This take a date and add the given delta to it (or subtract the
132           delta if $subtract is non-zero).
133
134              $date = $dmb->calc_date_time($date,$time [,$subtract]);
135
136           This take a date and add the given time to it (or subtract the time
137           if $subtract is non-zero).
138
139              $time = $dmb->calc_time_time(@time1,@time2 [,$subtract]);
140
141           This take two times and add them together (or subtract the second
142           from the first if $subtract is non-zero).
143
144       check
145       check_time
146              $valid = $dmb->check($date);
147              $valid = $dmb->check_time($hms);
148
149           This tests a list of values to see if they form a valid date or
150           time ignoring all time zone affects. The date/time would be valid
151           in GMT, but perhaps not in all time zones.
152
153           1 is returned if the the fields are valid, 0 otherwise.
154
155           $hms is in the range 00:00:00 to 24:00:00.
156
157       cmp
158              $flag = $dmb->cmp($date1,$date2);
159
160           Returns -1, 0, or 1 if date1 is before, the same as, or after
161           date2.
162
163       day_of_week
164              $day = $dmb->day_of_week($date);
165              $day = $dmb->day_of_week($ymd);
166
167           Returns the day of the week (1 for Monday, 7 for Sunday).
168
169       day_of_year
170              $day = $dmb->day_of_year($ymd);
171              $day = $dmb->day_of_year($date);
172
173           In the first case, returns the day of the year (1 to 366) for $y,
174           $m, $d.  In the second case, it returns a fractional day (1.0 <=
175           $day < 366.0 or 1.0 <= $day < 367.0 for a leap-year).  For example,
176           day 1.5 falls on Jan 1, at noon.  The somewhat non-intuitive answer
177           (1.5 instead of 0.5) is to make the two forms return numerically
178           equivalent answers for times of 00:00:00 . You can look at the
179           integer part of the number as being the day of the year, and the
180           fractional part of the number as the fraction of the day that has
181           passed at the given time.
182
183           The inverse operations can also be done:
184
185              $ymd   = $dmb->day_of_year($y,$day);
186              $date  = $dmb->day_of_year($y,$day);
187
188           If $day is an integer, the year, month, and day is returned. If
189           $day is a floating point number, it returns the year, month, day,
190           hour, minutes, and decimal seconds.
191
192           $day must be greater than or equal to 1 and less than 366 on non-
193           leap years or 367 on leap years.
194
195       days_in_month
196              $days = $dmb->days_in_month($y,$m);
197
198           Returns the number of days in the month.
199
200              @days = $dmb->days_in_month($y,0);
201
202           Returns a list of 12 elements with the days in each month of the
203           year.
204
205       days_in_year
206              $days = $dmb->days_in_year($y);
207
208           Returns the number of days in the year (365 or 366)
209
210       days_since_1BC
211              $days = $dmb->days_since_1BC($date);
212              $days = $dmb->days_since_1BC($ymd);
213
214           Returns the number of days since Dec 31, 1BC. Since the calendar
215           has changed a number of times, the number returned is based on the
216           current calendar projected backwards in time, and in no way
217           reflects a true number of days since then. As such, the result is
218           largely meaningless, except when called twice as a means of
219           determining the number of days separating two dates.
220
221           The inverse operation is also available:
222
223              $ymd = $dmb->days_since_1BC($days);
224
225           Returns the date $days since Dec 31, 1BC. So day 1 is Jan 1, 0001.
226
227       leapyear
228              $flag = $dmb->leapyear($y);
229
230           Returns 1 if the argument is a leap year.  Originally copied from
231           code written by David Muir Sharnoff <muir@idiom.com>.
232
233       nth_day_of_week
234              $ymd = $dmb->nth_day_of_week($y,$n,$dow);
235
236           Returns the $n'th occurrence of $dow (1 for Monday, 7 for Sunday)
237           in the year.  $n must be between 1 and 53 or -1 through -53.
238
239              $ymd = $dmb->nth_day_of_week($y,$n,$dow,$m);
240
241           Returns the $n'th occurrence of $dow in the given month.  $n must
242           be between 1 and 5 or it can be -1 through -5.
243
244           In all cases, nothing is returned if $n is beyond the last actual
245           result (i.e. the 5th Sunday in a month with only four Sundays).
246
247       secs_since_1970
248              $secs = $dmb->secs_since_1970($date);
249
250           Returns the number of seconds since Jan 1, 1970 00:00:00 (negative
251           if date is earlier).
252
253              $date = $dmb->secs_since_1970($secs);
254
255           Translates number of seconds into a date.
256
257       split
258       join
259           The split and join functions are used to take a string containing a
260           common type of time data and split it into a list of fields. The
261           join function takes the list and forms it into a string.
262
263           Rudimentary error checking is performed with both of these
264           functions and undef is returned in the case of any error. No error
265           checking is done on the specific values.
266
267           The following are allowed:
268
269              $date = $dmb->split("date",$string);
270              $string = $dmb->join("date",$date);
271
272           This splits a string containing a date or creates one from a list
273           reference.  The string split must be of one of the forms:
274
275              YYYYMMDDHH:MN:SS
276              YYYYMMDDHHMNSS
277              YYYY-MM-DD-HH:MN:SS
278
279           The string formed by join is one of the above, depending on the
280           value of the Printable config variable. The default format is
281           YYYYMMDDHH:MN:SS, but if Printable is set to 1, YYYYMMDDHHMNSS is
282           produced, and if Printable is set to 2, the YYYY-MM-DD-HH:MN:SS
283           form is produced.
284
285              $hms = $dmb->split("hms",$string);
286              $string = $dmb->join("hms",$hms);
287
288           This works with the hours, minutes, and seconds portion of a date.
289
290           When splitting a string, the string can be of any of the forms:
291
292              H
293              H:MN
294              H:MN:SS
295              HH
296              HHMN
297              HHMNSS
298
299           Here, H is a 1 or 2 digit representation of the hours. All other
300           fields are two digit representations.
301
302           The string formed by the join function will always be of the form
303           HH:MN:SS.
304
305           The time must be between 00:00:00 and 24:00:00.
306
307              $offset = $dmb->split("offset",$string);
308              $string = $dmb->join("offset",$offset);
309
310           An offset string should have a sign (though it is optional if it is
311           positive) and is any of the forms:
312
313              +H
314              +H:MN
315              +H:MN:SS
316              +HH
317              +HHMN
318              +HHMNSS
319
320           Here, H is a 1 or 2 digit representation of the hours. All other
321           fields are two digit representations.
322
323           The string formed by the join function will always be of the form
324           +HH:MN:SS.
325
326              $time = $dmb->split("time",$string);
327              $string = $dmb->join("time",$time);
328
329           This works with an amount of time in hours, minutes, and seconds.
330           The string is of the format:
331
332              +H:MN:S
333
334           where all signs are optional. The returned value (whether a list
335           reference from the split function, or a string from the join
336           function) will have all fields normalized (see Date::Manip::Delta
337           for an explanation).
338
339              $delta = $dmb->split("delta",$string);
340              $delta = $dmb->split("business",$string);
341
342              $string = $dmb->join("delta",$delta);
343              $string = $dmb->join("business",$delta);
344
345           Both of these split a string containing a delta, or create a string
346           containing one. The difference is whether the delta is treated as a
347           business or non-business delta (see Date::Manip::Delta
348           documentation for a detailed description).
349
350           The string that can be split is of the form:
351
352             +Y:M:+W:+D:H:MN:S
353
354           All signs are optional in the string being split. The string
355           produced is of the form +Y:M:+W:D:H:MN:S (for a non-business delta)
356           or +Y:M:+W:+D:H:MN:S (for a business delta).
357
358           Fields may be omitted entirely. For example:
359
360             D:H:MN:S
361             D:::S
362
363           are both valid.
364
365           The string or list output is normalized.
366
367       week1_day1
368              $ymd = $dmb->week1_day1($y);
369
370           This returns the date of the 1st day of the 1st week in the given
371           year.  Note that this uses the ISO 8601 definition of week, so the
372           year returned may be the year before the one passed in.
373
374           This uses the FirstDay and Jan1Week1 config variables to evaluate
375           the results.
376
377       weeks_in_year
378              $w = $dmb->weeks_in_year($y);
379
380           This returns the number of ISO 8601 weeks in the year. It will
381           always be 52 or 53.
382
383       week_of_year
384              ($y,$w) = $dmb->week_of_year($date);
385              ($y,$w) = $dmb->week_of_year($ymd);
386
387           This returns the week number (1-53) of the given date and the year
388           that it falls in. Since the ISO 8601 definition of a week is used,
389           the year returned is not necessarily the one passed in (it may
390           differ for the first or last week of the year).
391
392           The inverse operation is also available:
393
394              $ymd = $dmb->week_of_year($y,$w);
395
396           which returns the first day of the given week.
397
398           This uses the FirstDay and Jan1Week1 config variables to evaluate
399           the results.
400

KNOWN BUGS

402       None known.
403

BUGS AND QUESTIONS

405       Please refer to the Date::Manip::Problems documentation for information
406       on submitting bug reports or questions to the author.
407

SEE ALSO

409       Date::Manip        - main module documentation
410

LICENSE

412       This script is free software; you can redistribute it and/or modify it
413       under the same terms as Perl itself.
414

AUTHOR

416       Sullivan Beck (sbeck@cpan.org)
417
418
419
420perl v5.12.0                      2010-04-27              Date::Manip::Base(3)
Impressum