Date::Manip::Examples(3pm)

1Date::Manip::Examples(3U)ser Contributed Perl DocumentatiDoante::Manip::Examples(3)
2
3
4

NAME

6       Date::Manip::Examples - examples of how to use Date::Manip
7

DESCRIPTION

9       This document includes a number of examples on how to do common
10       Date::Manip operations.  I will be happy to add new examples over time,
11       and welcome suggestions and examples to include.
12
13       In most cases, an example will include two different ways of getting
14       the answer.  The first way will be using the new (as of 6.00) OO
15       modules. The second will be using the old-style functional interface.
16
17       It should be noted that any time you want to work with alternate time
18       zones, the OO interface is STRONGLY recommended since the functional
19       interface does not preserve time zone information with the date, and
20       may therefore give incorrect results in some cases. However, working in
21       the time zone of the system should give correct results.
22
23       It should be noted that, in the examples below, it appears that the OO
24       method often requires more lines of code than the functional interface.
25       There are a number of ways to shorten the OO method, but for the
26       examples, I wanted to include all the steps explicitly.
27

PARSING A DATE

29       Dates can be parsed in practically any form in common usage:
30
31       OO method
32              $date = new Date::Manip::Date;
33              $err = $date->parse("today");
34              $err = $date->parse("1st Thursday in June 1992");
35              $err = $date->parse("05/10/93");
36              $err = $date->parse("12:30 Dec 12th 1880");
37              $err = $date->parse("8:00pm December tenth");
38
39       Functional
40              $date = ParseDate("today");
41              $date = ParseDate("1st Thursday in June 1992");
42              $date = ParseDate("05/10/93");
43              $date = ParseDate("12:30 Dec 12th 1880");
44              $date = ParseDate("8:00pm December tenth");
45
46       The Date::Manip::Date manual has a list of all valid formats.
47

PARSING AN AMOUNT OF TIME

49       Amounts of time (referred to as deltas) can also be parsed:
50
51       OO method
52              $delta = new Date::Manip::Delta;
53              $err = $delta->parse("in 12 hours");
54              $err = $delta->parse("-1:30:0");
55              $err = $delta->parse("4 business days later");
56
57       Functional
58              $delta = ParseDateDelta("in 12 hours");
59              $delta = ParseDateDelta("-1:30:0");
60              $delta = ParseDateDelta("4 business days later");
61

TO CALCULATE THE AMOUNT OF TIME BETWEEN TWO DATES

63          $datestr1 = "Jan 30 1999 13:00 EST";
64          $datestr2 = "2/Mar/1999 15:30:00 +0500";
65
66       OO method
67              $date1 = new Date::Manip::Date;
68              $date2 = $date1->new_date();
69              $err = $date1->parse($datestr1);
70              $err = $date2->parse($datestr2);
71
72           To get an exact amount of time between the two dates (expressed
73           only in terms of weeks, days, hours, minutes, seconds), use:
74
75              $delta = $date1->calc($date2);
76
77           To get an approximate amount of time (expressed in terms of years,
78           months, weeks, etc. in terms that a human would typically think
79           of), use:
80
81              $delta = $date1->calc($date2,"approx");
82
83       Functional
84              $date1 = ParseDate($string1);
85              $date2 = ParseDate($string2);
86
87           To get an exact amount:
88
89              $delta = DateCalc($date1,$date2);
90
91           and the approximate amount:
92
93              $delta = DateCalc($date1,$date2,1);
94
95       The Date::Manip::Calc manual has information about these, and other
96       types of calculations.
97

TO ADD AN AMOUNT OF TIME TO A DATE

99       To find a second date a given amount of time before or after a first
100       date, use the following:
101
102          $datestr  = "Jan 30 1999 13:00 EST";
103          $deltastr = "12 hours ago";
104          $deltastr = "in 3 business days";
105
106       OO method
107              $date = new Date::Manip::Date;
108              $delta = $date->new_delta();
109              $date->parse($datestr);
110              $delta->parse($deltastr);
111
112              $d = $date->calc($delta);
113
114       Functional
115              $date = DateCalc($datestr,$deltastr);
116
117       If the delta is a business delta, it will do a business mode
118       calculation.
119
120       The Date::Manip::Calc manual has information about these, and other
121       types of calculations.
122

COMPARE TWO DATES

124       To take two different dates and see which is earlier, do the following:
125
126          $datestr1 = "Jan 30 1999 13:00 EST";
127          $datestr2 = "2/Mar/1999 15:30:00 +0500";
128
129       OO method
130              $date1 = new Date::Manip::Date;
131              $date2 = $date1->new_date;
132              $date1->parse($datestr1);
133              $date2->parse($datestr2);
134
135              $date1->cmp($date2);
136                 => -1, 0, 1
137
138       Functional
139              $date1 = ParseDate($datestr1);
140              $date2 = ParseDate($datestr2);
141
142              Date_Cmp($date1,$date2);
143                 => -1, 0, 1
144

TO EXTRACT INFORMATION ABOUT A DATE OR DELTA

146       If you have a date or a delta, you can extract information about them
147       as follows:
148
149          $datestr  = "1:24:08 PM EST Feb 3, 1996";
150          $deltastr = "12 hours ago";
151
152       OO method
153              $date = new Date::Manip::Date;
154              $delta = $date->new_delta();
155              $date->parse($datestr);
156              $delta->parse($deltastr);
157
158              $str = $date->printf("It is now %T on %b %e, %Y.");
159                =>  "It is now 13:24:08 on Feb  3, 1996."
160
161              $str = $delta->printf("In %hv hours, %mv minutes, %sv seconds");
162                => "In -12 hours, 0 minutes, 0 seconds";
163
164       Functional
165              $str = UnixDate($datestr,"It is now %T on %b %e, %Y.");
166                =>  "It is now 13:24:08 on Feb  3, 1996."
167
168              $str = Delta_Format($deltastr,"In %hv hours, %mv minutes, %sv seconds");
169                => "In -12 hours, 0 minutes, 0 seconds";
170
171       The Date::Manip::Date manual contains all of the format codes that can
172       be used to extract information from a date. The Date::Manip::Delta
173       manual contains the codes for a delta.
174

WORKING WITH EPOCH

176       Date::Manip can easily be used to work with the number of seconds since
177       the epoch (Jan 1, 1970 00:00:00 UTC).
178
179       If you have a date, and you want to find out how many seconds it is
180       after the epoch, you can do it in the following ways:
181
182          $datestr  = "1999-04-30-15:30:00 EDT";
183          $secs  = 1234567;
184
185       OO method
186           To find out how many seconds have elapsed on a certain date, you
187           can do the following:
188
189              $date     = new Date::Manip::Date;
190              $err      = $date->parse($datestr);
191
192              $str      = $date->printf('%s');
193                 => number of seconds
194
195           To find out the date that is a certain number of seconds since the
196           epoch, you can use the following:
197
198              $date  = new Date::Manip::Date;
199              $err   = $date->parse("epoch $secs");
200
201           $date now contains the date wanted (in the local time zone)
202
203       Functional
204           To find out how many seconds have elapsed:
205
206              $str = UnixDate($datestr,'%s');
207                => number of seconds
208
209           To find the date that is a number of seconds since the epoch:
210
211              $date = ParseDateString("epoch $secs");
212
213       Note that Date::Manip will work with both positive seconds (for dates
214       that have come since the epoch) and negative seconds (for dates that
215       occurred before the epoch).
216

RECURRING EVENTS

218       To find a list of dates where a recurring event happens (even very
219       complex recurrences), do the following:
220
221       OO method
222             # To find the 2nd Tuesday of every month from Jan 1 1999 to Apr 30 1999
223
224             $recur = new Date::Manip::Recur;
225             $start = $recur->new_date();
226             $end   = $recur->new_date();
227             $start->parse("Jan 1 1999");
228             $end->parse("Apr 30 1999");
229
230             $recur->parse("0:1*2:2:0:0:0",$start,$end);
231             @date = $recur->dates();
232
233             # To find the Monday after Easter in 1997-1999
234
235             $recur = new Date::Manip::Recur;
236             $recur->parse("*1997-1999:0:0:0:0:0:0*EASTER,ND1");
237             @date = $recur->dates();
238
239       Functional
240             # To find the 2nd Tuesday of every month from Jan 1 1999 to Apr 30 1999
241             @date = ParseRecur("0:1*2:2:0:0:0","","Jan 1 1999","Apr 30 1999");
242
243             # To find the Monday after Easter in 1997-1999.
244             @date = ParseRecur("*1997-1999:0:0:0:0:0:0*EASTER,ND1");
245
246       The Date::Manip::Recur manual contains information about recurring
247       events.
248

WORKING WITH DATES IN ANOTHER LANGUAGE

250       If you want to work with dates in a language other than English (but
251       you are only working with a single language), do the following:
252
253       OO method
254              $date = new Date::Manip::Date;
255              $date->config("Language","French","DateFormat","non-US");
256              $date->parse("1er decembre 1990");
257
258       Functional
259              Date_Init("Language=French","DateFormat=non-US");
260              $date = ParseDate("1er decembre 1990");
261
262       The Date::Manip::Config manual has a list of all supported languages
263       (in the section on the Language config variable). The meaning of the
264       DateFormat config variable is also included.
265

WORKING WITH TWO DIFFERENT LANGUAGES

267       If you want to work with dates in two (or more) languages, it is
268       STRONGLY recommended that you use the OO interface. The functional
269       interface will be much slower since it has to re-initialize a lot of
270       language-specific stuff every time you switch back and forth between
271       languages.
272
273       OO method
274              $date_eng = new Date::Manip::Date;
275              $date_eng->config("Language","English","DateFormat","US");
276
277              $date_fre = new Date::Manip::Date;
278              $date_fre->config("Language","French","DateFormat","non-US");
279
280           Use the $date_eng object to do English operations, the $date_fre
281           object to do French operations.
282
283       Functional
284           If you are working with both French and English dates, you can call
285           the following to switch between them:
286
287              Date_Init("Language=French","DateFormat=non-US");
288              Date_Init("Language=English","DateFormat=US");
289
290           This is NOT recommended. Use the OO method instead.
291

BUGS AND QUESTIONS

293       Please refer to the Date::Manip::Problems documentation for information
294       on submitting bug reports or questions to the author.
295

LICENSE

300       This script is free software; you can redistribute it and/or modify it
301       under the same terms as Perl itself.
302

AUTHOR

304       Sullivan Beck (sbeck@cpan.org)
305
306
307
308perl v5.26.3                      2017-03-01          Date::Manip::Examples(3)