1Date::Manip::Base(3) User Contributed Perl Documentation Date::Manip::Base(3)
2
6 Date::Manip::Base - Base methods for date manipulation
7
9 use Date::Manip::Base;
10 $dmb = new Date::Manip::Base;
11
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 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 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 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 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
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 err
42 new
43 new_config
44 Please refer to the Date::Manip::Obj documentation for these
45 methods.
46 config
48 $dmb->config($var1,$val1,$var2,$val2,...);
49 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
55 In all of the following methods, the following variables are used:
56 $date
58 This is a list reference containing a full date and time:
59 [$y, $m, $d, $h, $mn, $s]
61 $ymd
63 A list reference containing only the date portion:
64 [$y, $m, $d]
66 $hms
68 A list reference containing only the time portion:
69 [$h, $mn, $s]
71 $time
73 A list reference containing an amount of time:
74 [$dh, $dmn, $ds]
76 $delta
78 A list containing a full delta:
79 [$dy, $dm, $dw, $dd, $dh, $dmn, $ds]
81 $offset
83 A list containing a time zone expressed as an offset:
84 [ $offh, $offm, $offs ]
86 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 $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 Years are not translated to 4 digit years, so passing in a year of "04"
97 will be equivalent to "0004", NOT "2004".
98 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 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 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 The following methods are available:
117 $time = $dmb->calc_date_date($date1,$date2);
119 This take two dates and determine the amount of time between them.
121 $date = $dmb->calc_date_days($date,$n [,$subtract]);
123 $ymd = $dmb->calc_date_days($ymd,$n [,$subtract]);
124 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 $date = $dmb->calc_date_delta($date,$delta [,$subtract]);
130 This take a date and add the given delta to it (or subtract the
132 delta if $subtract is non-zero).
133 $date = $dmb->calc_date_time($date,$time [,$subtract]);
135 This take a date and add the given time to it (or subtract the time
137 if $subtract is non-zero).
138 $time = $dmb->calc_time_time(@time1,@time2 [,$subtract]);
140 This take two times and add them together (or subtract the second
142 from the first if $subtract is non-zero).
143 check
145 check_time
146 $valid = $dmb->check($date);
147 $valid = $dmb->check_time($hms);
148 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 1 is returned if the the fields are valid, 0 otherwise.
154 $hms is in the range 00:00:00 to 24:00:00.
156 cmp
158 $flag = $dmb->cmp($date1,$date2);
159 Returns -1, 0, or 1 if date1 is before, the same as, or after
161 date2.
162 day_of_week
164 $day = $dmb->day_of_week($date);
165 $day = $dmb->day_of_week($ymd);
166 Returns the day of the week (1 for Monday, 7 for Sunday).
168 day_of_year
170 $day = $dmb->day_of_year($ymd);
171 $day = $dmb->day_of_year($date);
172 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 The inverse operations can also be done:
184 $ymd = $dmb->day_of_year($y,$day);
186 $date = $dmb->day_of_year($y,$day);
187 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 $day must be greater than or equal to 1 and less than 366 on non-
193 leap years or 367 on leap years.
194 days_in_month
196 $days = $dmb->days_in_month($y,$m);
197 Returns the number of days in the month.
199 @days = $dmb->days_in_month($y,0);
201 Returns a list of 12 elements with the days in each month of the
203 year.
204 days_in_year
206 $days = $dmb->days_in_year($y);
207 Returns the number of days in the year (365 or 366)
209 days_since_1BC
211 $days = $dmb->days_since_1BC($date);
212 $days = $dmb->days_since_1BC($ymd);
213 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 The inverse operation is also available:
222 $ymd = $dmb->days_since_1BC($days);
224 Returns the date $days since Dec 31, 1BC. So day 1 is Jan 1, 0001.
226 leapyear
228 $flag = $dmb->leapyear($y);
229 Returns 1 if the argument is a leap year. Originally copied from
231 code written by David Muir Sharnoff <muir@idiom.com>.
232 nth_day_of_week
234 $ymd = $dmb->nth_day_of_week($y,$n,$dow);
235 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 $ymd = $dmb->nth_day_of_week($y,$n,$dow,$m);
240 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 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 secs_since_1970
248 $secs = $dmb->secs_since_1970($date);
249 Returns the number of seconds since Jan 1, 1970 00:00:00 (negative
251 if date is earlier).
252 $date = $dmb->secs_since_1970($secs);
254 Translates number of seconds into a date.
256 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 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 The following are allowed:
268 $date = $dmb->split("date",$string);
270 $string = $dmb->join("date",$date);
271 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 YYYYMMDDHH:MN:SS
276 YYYYMMDDHHMNSS
277 YYYY-MM-DD-HH:MN:SS
278 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 $hms = $dmb->split("hms",$string);
286 $string = $dmb->join("hms",$hms);
287 This works with the hours, minutes, and seconds portion of a date.
289 When splitting a string, the string can be of any of the forms:
291 H
293 H:MN
294 H:MN:SS
295 HH
296 HHMN
297 HHMNSS
298 Here, H is a 1 or 2 digit representation of the hours. All other
300 fields are two digit representations.
301 The string formed by the join function will always be of the form
303 HH:MN:SS.
304 The time must be between 00:00:00 and 24:00:00.
306 $offset = $dmb->split("offset",$string);
308 $string = $dmb->join("offset",$offset);
309 An offset string should have a sign (though it is optional if it is
311 positive) and is any of the forms:
312 +H
314 +H:MN
315 +H:MN:SS
316 +HH
317 +HHMN
318 +HHMNSS
319 Here, H is a 1 or 2 digit representation of the hours. All other
321 fields are two digit representations.
322 The string formed by the join function will always be of the form
324 +HH:MN:SS.
325 $time = $dmb->split("time",$string);
327 $string = $dmb->join("time",$time);
328 This works with an amount of time in hours, minutes, and seconds.
330 The string is of the format:
331 +H:MN:S
333 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 $delta = $dmb->split("delta",$string);
340 $delta = $dmb->split("business",$string);
341 $string = $dmb->join("delta",$delta);
343 $string = $dmb->join("business",$delta);
344 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 The string that can be split is of the form:
351 +Y:M:+W:+D:H:MN:S
353 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 Fields may be omitted entirely. For example:
359 D:H:MN:S
361 D:::S
362 are both valid.
364 The string or list output is normalized.
366 week1_day1
368 $ymd = $dmb->week1_day1($y);
369 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 This uses the FirstDay and Jan1Week1 config variables to evaluate
375 the results.
376 weeks_in_year
378 $w = $dmb->weeks_in_year($y);
379 This returns the number of ISO 8601 weeks in the year. It will
381 always be 52 or 53.
382 week_of_year
384 ($y,$w) = $dmb->week_of_year($date);
385 ($y,$w) = $dmb->week_of_year($ymd);
386 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 The inverse operation is also available:
393 $ymd = $dmb->week_of_year($y,$w);
395 which returns the first day of the given week.
397 This uses the FirstDay and Jan1Week1 config variables to evaluate
399 the results.
400
402 None known.
403
405 Please refer to the Date::Manip::Problems documentation for information
406 on submitting bug reports or questions to the author.
407
409 Date::Manip - main module documentation
410
412 This script is free software; you can redistribute it and/or modify it
413 under the same terms as Perl itself.
414
416 Sullivan Beck (sbeck@cpan.org)
417perl v5.12.0 2010-04-27 Date::Manip::Base(3)