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 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 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
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 method descriptions, the following variables
56 are used:
57 $date
59 This is a list reference containing a full date and time:
60 [$y, $m, $d, $h, $mn, $s]
62 $ymd
64 A list reference containing only the date portion:
65 [$y, $m, $d]
67 $hms
69 A list reference containing only the time portion:
70 [$h, $mn, $s]
72 $delta
74 A list containing a full delta (an amount of time elapsed, or a
75 duration):
76 [$dy, $dm, $dw, $dd, $dh, $dmn, $ds]
78 $time
80 A list reference containing the hour/minute/second portion of a
81 delta:
82 [$dh, $dmn, $ds]
84 $offset
86 A list containing a time zone expressed as an offset:
87 [ $offh, $offm, $offs ]
89 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 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 $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 Years are not translated to 4 digit years, so passing in a year of "04"
104 will be equivalent to "0004", NOT "2004".
105 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 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 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 The following methods are available:
124 $time = $dmb->calc_date_date($date1,$date2);
126 This take two dates and determine the amount of time between them.
128 $date = $dmb->calc_date_days($date,$n [,$subtract]);
130 $ymd = $dmb->calc_date_days($ymd,$n [,$subtract]);
131 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 $date = $dmb->calc_date_delta($date,$delta [,$subtract]);
137 This take a date and add the given delta to it (or subtract the
139 delta if $subtract is non-zero).
140 $date = $dmb->calc_date_time($date,$time [,$subtract]);
142 This take a date and add the given time to it (or subtract the time
144 if $subtract is non-zero).
145 $time = $dmb->calc_time_time(@time1,@time2 [,$subtract]);
147 This take two times and add them together (or subtract the second
149 from the first if $subtract is non-zero).
150 check
152 check_time
153 $valid = $dmb->check($date);
154 $valid = $dmb->check_time($hms);
155 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 1 is returned if the the fields are valid, 0 otherwise.
161 $hms is in the range 00:00:00 to 24:00:00.
163 cmp
165 $flag = $dmb->cmp($date1,$date2);
166 Returns -1, 0, or 1 if date1 is before, the same as, or after
168 date2.
169 day_of_week
171 $day = $dmb->day_of_week($date);
172 $day = $dmb->day_of_week($ymd);
173 Returns the day of the week (1 for Monday, 7 for Sunday).
175 day_of_year
177 $day = $dmb->day_of_year($ymd);
178 $day = $dmb->day_of_year($date);
179 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 The inverse operations can also be done:
190 $ymd = $dmb->day_of_year($y,$day);
192 $date = $dmb->day_of_year($y,$day);
193 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 $day must be greater than or equal to 1 and less than 366 on non-
199 leap years or 367 on leap years.
200 days_in_month
202 $days = $dmb->days_in_month($y,$m);
203 Returns the number of days in the month.
205 @days = $dmb->days_in_month($y,0);
207 Returns a list of 12 elements with the days in each month of the
209 year.
210 days_in_year
212 $days = $dmb->days_in_year($y);
213 Returns the number of days in the year (365 or 366)
215 days_since_1BC
217 $days = $dmb->days_since_1BC($date);
218 $days = $dmb->days_since_1BC($ymd);
219 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 The inverse operation is also available:
228 $ymd = $dmb->days_since_1BC($days);
230 Returns the date $days since Dec 31, 1BC. So day 1 is Jan 1, 0001.
232 leapyear
234 $flag = $dmb->leapyear($y);
235 Returns 1 if the argument is a leap year.
237 nth_day_of_week
239 $ymd = $dmb->nth_day_of_week($y,$n,$dow);
240 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 $ymd = $dmb->nth_day_of_week($y,$n,$dow,$m);
245 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 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 secs_since_1970
253 $secs = $dmb->secs_since_1970($date);
254 Returns the number of seconds since Jan 1, 1970 00:00:00 (negative
256 if date is earlier).
257 $date = $dmb->secs_since_1970($secs);
259 Translates number of seconds into a date.
261 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 The general format for these is:
269 $obj = $dmb->split($type,$string,\%opts);
271 $string = $dmb->join($type,$obj,\%opts);
272 An older format is also supported:
274 $obj = $dmb->split($type,$string,[$no_normalize]);
276 $string = $dmb->join($type,$obj,[$no_normalize]);
277 but this is deprecated and will be removed in Date::Manip 7.00.
279 These are equivalent to:
280 $obj = $dmb->split($type,$string,{ 'nonorm' => $no_normalize });
282 $string = $dmb->join($type,$obj,{ 'nonorm' => $no_normalize });
283 The value of $type determines what type of join/split operation
285 occurs.
286 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 $type = 'date'
292 $date = $dmb->split("date",$string);
293 $string = $dmb->join("date",$date);
294 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 YYYYMMDDHH:MN:SS
300 YYYYMMDDHHMNSS
301 YYYY-MM-DD-HH:MN:SS
302 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 $type = 'hms'
310 $hms = $dmb->split("hms",$string);
311 $string = $dmb->join("hms",$hms);
312 This works with the hours, minutes, and seconds portion of
314 a date.
315 When splitting a string, the string can be of any of the
317 forms:
318 H
320 H:MN
321 H:MN:SS
322 HH
323 HHMN
324 HHMNSS
325 Here, H is a 1 or 2 digit representation of the hours but
327 HH (and all other fields) are two digit representations.
328 The string formed by the join function will always be of
330 the form HH:MN:SS.
331 The time must be between 00:00:00 and 24:00:00.
333 $type = 'offset'
335 $offset = $dmb->split("offset",$string);
336 $string = $dmb->join("offset",$offset);
337 An offset string should have a sign (though it is optional
339 if it is positive) and is any of the forms:
340 +H
342 +H:MN
343 +H:MN:SS
344 +HH
345 +HHMN
346 +HHMNSS
347 Here, H is a 1 or 2 digit representation of the hours. All
349 other fields are two digit representations.
350 The string formed by the join function will always be of
352 the form +HH:MN:SS.
353 The offset must be between -23:59:59 and +23:59:59 .
355 $type = 'time'
357 $time = $dmb->split("time",$string,\%opts]);
358 $string = $dmb->join("time",$time,\%opts);
359 The only option supported is:
361 'nonorm' 0/1
363 This works with an amount of time in hours, minutes, and
365 seconds. The string is of the format:
366 +H:MN:S
368 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 $type = 'delta'
375 $delta = $dmb->split("delta",$string,\%opts);
376 $string = $dmb->join("delta",$delta,\%opts);
377 Options recognized are:
379 mode : standard/business
381 nonorm : 0/1
382 type : exact/semi/approx/estimated
383 A second format is also supported, but is deprecated and
385 will be removed in Date::Manip 7.0.
386 $delta = $dmb->split("business",$string,\%opts);
388 $string = $dmb->join("business",$delta,\%opts);
389 These are equivalent to using 'delta' with an option of
391 "'mode' =" 'business'>.
392 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 The string that can be split is of the form:
398 Y:M:W:D:H:MN:S
400 Any field may have a sign, but they are optional.
402 Fields may be omitted entirely. For example:
404 D:H:MN:S
406 D:::S
407 are both valid.
409 The string or list output is normalized unless the nonorm
411 option is passed in.
412 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 default_type condition
419 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 week1_day1
426 $ymd = $dmb->week1_day1($y);
427 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 This uses the FirstDay and Jan1Week1 config variables to evaluate
433 the results.
434 weeks_in_year
436 $w = $dmb->weeks_in_year($y);
437 This returns the number of ISO 8601 weeks in the year. It will
439 always be 52 or 53.
440 week_of_year
442 ($y,$w) = $dmb->week_of_year($date);
443 ($y,$w) = $dmb->week_of_year($ymd);
444 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 The inverse operation is also available:
451 $ymd = $dmb->week_of_year($y,$w);
453 which returns the first day of the given week.
455 This uses the FirstDay and Jan1Week1 config variables to evaluate
457 the results.
458
460 None known.
461
463 Please refer to the Date::Manip::Problems documentation for information
464 on submitting bug reports or questions to the author.
465
467 Date::Manip - main module documentation
468
470 This script is free software; you can redistribute it and/or modify it
471 under the same terms as Perl itself.
472
474 Sullivan Beck (sbeck@cpan.org)
475perl v5.34.1 2022-06-06 Date::Manip::Base(3)