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

KNOWN BUGS

460       None known.
461

BUGS AND QUESTIONS

463       Please refer to the Date::Manip::Problems documentation for information
464       on submitting bug reports or questions to the author.
465

SEE ALSO

467       Date::Manip        - main module documentation
468

LICENSE

470       This script is free software; you can redistribute it and/or modify it
471       under the same terms as Perl itself.
472

AUTHOR

474       Sullivan Beck (sbeck@cpan.org)
475
476
477
478perl v5.32.1                      2021-03-03              Date::Manip::Base(3)
Impressum