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       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 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 saving 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           The offset must be between -23:59:59 and +23:59:59 .
327
328              $time = $dmb->split("time",$string [,$no_normalize]);
329              $string = $dmb->join("time",$time [,$no_normalize]);
330
331           This works with an amount of time in hours, minutes, and seconds.
332           The string is of the format:
333
334              +H:MN:S
335
336           where all signs are optional. The returned value (whether a list
337           reference from the split function, or a string from the join
338           function) will have all fields normalized unless $no_normalize is
339           passed in.
340
341              $delta = $dmb->split("delta",$string [,$no_normalize]);
342              $delta = $dmb->split("business",$string [,$no_normalize]);
343
344              $string = $dmb->join("delta",$delta [,$no_normalize]);
345              $string = $dmb->join("business",$delta [,$no_normalize]);
346
347           Both of these split a string containing a delta, or create a string
348           containing one. The difference is whether the delta is treated as a
349           business or non-business delta (see Date::Manip::Delta
350           documentation for a detailed description).
351
352           The string that can be split is of the form:
353
354             +Y:M:+W:+D:H:MN:S
355
356           All signs are optional in the string being split. The string
357           produced is of the form +Y:M:+W:D:H:MN:S (for a non-business delta)
358           or +Y:M:+W:+D:H:MN:S (for a business delta).
359
360           Fields may be omitted entirely. For example:
361
362             D:H:MN:S
363             D:::S
364
365           are both valid.
366
367           The string or list output is normalized unless $no_normalize is
368           passed in.
369
370       week1_day1
371              $ymd = $dmb->week1_day1($y);
372
373           This returns the date of the 1st day of the 1st week in the given
374           year.  Note that this uses the ISO 8601 definition of week, so the
375           year returned may be the year before the one passed in.
376
377           This uses the FirstDay and Jan1Week1 config variables to evaluate
378           the results.
379
380       weeks_in_year
381              $w = $dmb->weeks_in_year($y);
382
383           This returns the number of ISO 8601 weeks in the year. It will
384           always be 52 or 53.
385
386       week_of_year
387              ($y,$w) = $dmb->week_of_year($date);
388              ($y,$w) = $dmb->week_of_year($ymd);
389
390           This returns the week number (1-53) of the given date and the year
391           that it falls in. Since the ISO 8601 definition of a week is used,
392           the year returned is not necessarily the one passed in (it may
393           differ for the first or last week of the year).
394
395           The inverse operation is also available:
396
397              $ymd = $dmb->week_of_year($y,$w);
398
399           which returns the first day of the given week.
400
401           This uses the FirstDay and Jan1Week1 config variables to evaluate
402           the results.
403

KNOWN BUGS

405       None known.
406

BUGS AND QUESTIONS

408       Please refer to the Date::Manip::Problems documentation for information
409       on submitting bug reports or questions to the author.
410

SEE ALSO

412       Date::Manip        - main module documentation
413

LICENSE

415       This script is free software; you can redistribute it and/or modify it
416       under the same terms as Perl itself.
417

AUTHOR

419       Sullivan Beck (sbeck@cpan.org)
420
421
422
423perl v5.16.3                      2014-06-09              Date::Manip::Base(3)
Impressum