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

PARSING A DATE

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

PARSING AN AMOUNT OF TIME

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

TO CALCULATE THE AMOUNT OF TIME BETWEEN TWO DATES

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

TO ADD AN AMOUNT OF TIME TO A DATE

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

COMPARE TWO DATES

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

TO EXTRACT INFORMATION ABOUT A DATE OR DELTA

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

WORKING WITH EPOCH

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

RECURRING EVENTS

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

WORKING WITH DATES IN ANOTHER LANGUAGE

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

WORKING WITH TWO DIFFERENT LANGUAGES

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

BUGS AND QUESTIONS

297       Please refer to the Date::Manip::Problems documentation for information
298       on submitting bug reports or questions to the author.
299

LICENSE

304       This script is free software; you can redistribute it and/or modify it
305       under the same terms as Perl itself.
306

AUTHOR

308       Sullivan Beck (sbeck@cpan.org)
309
310
311
312perl v5.12.0                      2010-04-27          Date::Manip::Examples(3)