1Date::Simple(3) User Contributed Perl Documentation Date::Simple(3)
2
6 Date::Simple - a simple date object
7
9 use Date::Simple ('date', 'today');
10 # Difference in days between two dates:
12 $diff = date('2001-08-27') - date('1977-10-05');
13 # Offset $n days from now:
15 $date = today() + $n;
16 print "$date\n"; # uses ISO 8601 format (YYYY-MM-DD)
17 use Date::Simple ();
19 my $date = Date::Simple->new('1972-01-17');
20 my $year = $date->year;
21 my $month = $date->month;
22 my $day = $date->day;
23 use Date::Simple (':all');
25 my $date2 = ymd($year, $month, $day);
26 my $date3 = d8('19871218');
27 my $today = today();
28 my $tomorrow = $today + 1;
29 if ($tomorrow->year != $today->year) {
30 print "Today is New Year's Eve!\n";
31 }
32 if ($today > $tomorrow) {
34 die "warp in space-time continuum";
35 }
36 print "Today is ";
38 print(('Sun','Mon','Tues','Wednes','Thurs','Fri','Satur')
39 [$today->day_of_week]);
40 print "day.\n";
41 # you can also do this:
43 ($date cmp "2001-07-01")
44 # and this
45 ($date <=> [2001, 7, 1])
46
48 Dates are complex enough without times and timezones. This module may
49 be used to create simple date objects. It handles:
50 Validation.
52 Reject 1999-02-29 but accept 2000-02-29.
53 Interval arithmetic.
55 How many days were between two given dates? What date comes N days
56 after today?
57 Day-of-week calculation.
59 What day of the week is a given date?
60 Transparent date formatting.
62 How should a date object be formatted.
63 It does not deal with hours, minutes, seconds, and time zones.
65 A date is uniquely identified by year, month, and day integers within
67 valid ranges. This module will not allow the creation of objects for
68 invalid dates. Attempting to create an invalid date will return undef.
69 Month numbering starts at 1 for January, unlike in C and Java. Years
70 are 4-digit.
71 Gregorian dates up to year 9999 are handled correctly, but we rely on
73 Perl's builtin "localtime" function when the current date is requested.
74 On some platforms, "localtime" may be vulnerable to rollovers such as
75 the Unix "time_t" wraparound of 18 January 2038.
76 Overloading is used so you can compare or subtract two dates using
78 standard numeric operators such as "==", and the sum of a date object
79 and an integer is another date object.
80 Date::Simple objects are immutable. After assigning $date1 to $date2,
82 no change to $date1 can affect $date2. This means, for example, that
83 there is nothing like a "set_year" operation, and "$date++" assigns a
84 new object to $date.
85 This module contains various undocumented functions. They may not be
87 available on all platforms and are likely to change or disappear in
88 future releases. Please let the author know if you think any of them
89 should be public.
90 Controlling output format.
92 As of version 3.0 new ways of controlling the output formats of
94 Date::Simple objects has been provided. However Date::Simple has tradi‐
95 tionally provided few ways of stringification, a primary one via the
96 format() method and another primary one via direct stringification.
97 However the later is currently implemented as an XS routine and the
98 former is implemented through a perl routine. This means that using
99 format() is more expensive than stringification and that the stringifi‐
100 cation format is class specific.
101 In order to alleviate some of these problems a new mechanism has been
103 introduced to Date::Simple that allows for a per object level format
104 default. In addition a set of utility classes that have different
105 stringification overloads provided. These classes are simple sub‐
106 classes of Date::Simple and beside the default format() and the over‐
107 loaded stringification behaviour are identical to Date::Simple. In fact
108 one is totally identical to Date::Simple and is provided mostly for
109 completeness.
110 The classes included are:
112 Date::Simple::ISO
114 Identical to Date::Simple in every respect but name.
115 Date::Simple::D8
117 Uses the D8 format (%Y%m%d) as the default format for printing.
118 Uses XS for the overloaded stringification.
119 Date::Simple::Fmt
121 Uses the perl implemented format() as the default stringification
122 mechanism. The first argument to the constructor is expected to be
123 the format to use for the object.
124 NOTE its important to remember that the primary difference between the
126 behaviour of objects of the different classes is how they are stringi‐
127 fied when quoted, and what date format is used by default when the for‐
128 mat() method is called. Nothing else differs.
129
131 Several functions take a string or numeric representation and generate
132 a corresponding date object. The most general is "new", whose argument
133 list may be empty (returning the current date), a string in format
134 YYYY-MM-DD or YYYYMMDD, a list or arrayref of year, month, and day num‐
135 ber, or an existing date object.
136 Date::Simple->new ([ARG, ...])
138 date ([ARG, ...])
139 my $date = Date::Simple->new('1972-01-17');
140 The "new" method will return a date object if the values passed in
142 specify a valid date. (See above.) If an invalid date is passed,
143 the method returns undef. If the argument is invalid in form as
144 opposed to numeric range, "new" dies.
145 The "date" function provides the same functionality but must be
147 imported or qualified as "Date::Simple::date". (To import all pub‐
148 lic functions, do "use Date::Simple (':all');".) This function
149 returns undef on all invalid input, rather than dying in some cases
150 like "new".
151 date_fmt (FMT,[ARG, ...])
153 Equivelent to "date" but creates a Date::Simple::Fmt object
154 instead. The format is expected to be a valid POSIX::strftime for‐
155 mat string.
156 date_iso ([ARG, ...])
158 Identical to "date" but creates a Date::Simple::ISO object instead.
159 date_d8 ([ARG, ...])
161 Equivelent to "date" but creates a Date::Simple::D8 object instead.
162 today()
164 Returns the current date according to "localtime".
165 Caution: To get tomorrow's date (or any fixed offset from today),
167 do not use "today + 1". Perl parses this as "today(+1)". You need
168 to put empty parentheses after the function: "today() + 1".
169 ymd (YEAR, MONTH, DAY)
171 Returns a date object with the given year, month, and day numbers.
172 If the arguments do not specify a valid date, undef is returned.
173 Example:
175 use Date::Simple ('ymd');
177 $pbd = ymd(1987, 12, 18);
178 d8 (STRING)
180 Parses STRING as "YYYYMMDD" and returns the corresponding date
181 object, or undef if STRING has the wrong format or specifies an
182 invalid date.
183 Example:
185 use Date::Simple ('d8');
187 $doi = d8('17760704');
188 Mnemonic: The string matches "/\d{8}/". Also, "d8" spells "date",
190 if 8 is expanded phonetically.
191
193 DATE->next
194 my $tomorrow = $today->next;
195 Returns an object representing tomorrow.
197 DATE->prev
199 my $yesterday = $today->prev;
200 Returns an object representing yesterday.
202 DATE->year
204 my $year = $date->year;
205 Return the year of DATE as an integer.
207 DATE->month
209 my $month = $date->month;
210 Return the month of DATE as an integer from 1 to 12.
212 DATE->day
214 my $day = $date->day;
215 Return the DATE's day of the month as an integer from 1 to 31.
217 DATE->day_of_week
219 Return a number representing DATE's day of the week from 0 to 6,
220 where 0 means Sunday.
221 DATE->as_ymd
223 my ($year, $month, $day) = $date->as_ymd;
224 Returns a list of three numbers: year, month, and day.
226 DATE->as_d8
228 Returns the "d8" representation (see "d8"), like "$date->for‐
229 mat("%Y%m%d")".
230 DATE->as_iso
232 Returns the ISO 8601 representation of the date (eg '2004-01-01'),
233 like "$date->format("%Y-%m-%d")". This is in fact the default over‐
234 loaded stringification mechanism and is provided mostly so other
235 subclasses with different overloading can still do fast ISO style
236 date output.
237 DATE->as_str ([STRING])
239 DATE->format ([STRING])
240 DATE->strftime ([STRING])
241 These functions are equivalent. Return a string representing the
242 date, in the format specified. If you don't pass a parameter, the
243 default date format for the object is used if one has been speci‐
244 fied, otherwise uses the default date format for the class the
245 object is a member of, or as a last fallback uses the $Date::Sim‐
246 ple::Standard_Format which is changeable, but probably shouldn't be
247 modified. See "default_format" for details.
248 my $change_date = $date->format("%d %b %y");
250 my $iso_date1 = $date->format("%Y-%m-%d");
251 my $iso_date2 = $date->format;
252 The formatting parameter is similar to one you would pass to strf‐
254 time(3). This is because we actually do pass it to strftime to
255 format the date. This may result in differing behavior across
256 platforms and locales and may not even work everywhere.
257 DATE->default_format ([FORMAT])
259 This method sets or gets the default_format for the DATE object or
260 class that it is called on.
261
263 Some operators can be used with Date::Simple instances. If one side of
264 an expression is a date object, and the operator expects two date
265 objects, the other side is interpreted as "date(ARG)", so an array ref‐
266 erence or ISO 8601 string will work.
267 DATE + NUMBER
269 DATE - NUMBER
270 You can construct a new date offset by a number of days using the
271 "+" and "-" operators.
272 DATE1 - DATE2
274 You can subtract two dates to find the number of days between them.
275 DATE1 == DATE2
277 DATE1 < DATE2
278 DATE1 <=> DATE2
279 DATE1 cmp DATE2
280 etc.
281 You can compare two dates using the arithmetic or string comparison
282 operators. Equality tests ("==" and "eq") return false when one of
283 the expressions can not be converted to a date. Other comparison
284 tests die in such cases. This is intentional, because in a sense,
285 all non-dates are not "equal" to all dates, but in no sense are
286 they "greater" or "less" than dates.
287 DATE += NUMBER
289 DATE -= NUMBER
290 You can increment or decrement a date by a number of days using the
291 += and -= operators. This actually generates a new date object and
292 is equivalent to "$date = $date + $number".
293 "$date"
295 You can interpolate a date instance directly into a string, in the
296 format specified by ISO 8601 (eg: 2000-01-17) for Date::Simple and
297 Date::Simple::ISO, for Date::Simple::D8 this is the same as calling
298 as_d8() on the object, and for Date::Simple::Fmt this is the same
299 as calling format() on the object.
300
302 leap_year (YEAR)
303 Returns true if YEAR is a leap year.
304 days_in_month (YEAR, MONTH)
306 Returns the number of days in MONTH, YEAR.
307 leap_year (YEAR)
309 Returns true if YEAR is a leap year.
310 days_in_month (YEAR, MONTH)
312 Returns the number of days in MONTH, YEAR.
313
315 Marty Pauley <marty@kasei.com>
316 John Tobey <jtobey@john-edwin-tobey.org>
317 Yves Orton <demerphq@hotmail.com>
318
320 Copyright (C) 2001 Kasei.
321 Copyright (C) 2001,2002 John Tobey.
322 Copyright (C) 2004 Yves Orton.
323 This program is free software; you can redistribute it and/or
325 modify it under the terms of either:
326 a) the GNU General Public License;
328 either version 2 of the License, or (at your option) any later
329 version. You should have received a copy of the GNU General
330 Public License along with this program; see the file COPYING.
331 If not, write to the Free Software Foundation, Inc., 59
332 Temple Place, Suite 330, Boston, MA 02111-1307 USA
333 b) the Perl Artistic License.
335 This program is distributed in the hope that it will be useful,
337 but WITHOUT ANY WARRANTY; without even the implied warranty of
338 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
339
341 Date::Simple::Fmt Date::Simple::ISO Date::Simple::D8 and of course perl
342perl v5.8.8 2004-04-05 Date::Simple(3)