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
93 Date::Simple objects has been provided. However Date::Simple has
94 traditionally provided few ways of stringification, a primary one via
95 the format() method and another primary one via direct stringification.
96 However the later is currently implemented as an XS routine and the
97 former is implemented through a perl routine. This means that using
98 format() is more expensive than stringification and that the
99 stringification format is class specific.
100 In order to alleviate some of these problems a new mechanism has been
102 introduced to Date::Simple that allows for a per object level format
103 default. In addition a set of utility classes that have different
104 stringification overloads provided. These classes are simple
105 subclasses of Date::Simple and beside the default format() and the
106 overloaded stringification behaviour are identical to Date::Simple. In
107 fact one is totally identical to Date::Simple and is provided mostly
108 for completeness.
109 The classes included are:
111 Date::Simple::ISO
113 Identical to Date::Simple in every respect but name.
114 Date::Simple::D8
116 Uses the D8 format (%Y%m%d) as the default format for printing.
117 Uses XS for the overloaded stringification.
118 Date::Simple::Fmt
120 Uses the perl implemented format() as the default stringification
121 mechanism. The first argument to the constructor is expected to be
122 the format to use for the object.
123 NOTE its important to remember that the primary difference between the
125 behaviour of objects of the different classes is how they are
126 stringified when quoted, and what date format is used by default when
127 the format() method is called. Nothing else differs.
128
130 Several functions take a string or numeric representation and generate
131 a corresponding date object. The most general is "new", whose argument
132 list may be empty (returning the current date), a string in format
133 YYYY-MM-DD or YYYYMMDD, a list or arrayref of year, month, and day
134 number, or an existing date object.
135 Date::Simple->new ([ARG, ...])
137 date ([ARG, ...])
138 my $date = Date::Simple->new('1972-01-17');
139 The "new" method will return a date object if the values passed in
141 specify a valid date. (See above.) If an invalid date is passed,
142 the method returns undef. If the argument is invalid in form as
143 opposed to numeric range, "new" dies.
144 The "date" function provides the same functionality but must be
146 imported or qualified as "Date::Simple::date". (To import all
147 public functions, do "use Date::Simple (':all');".) This function
148 returns undef on all invalid input, rather than dying in some cases
149 like "new".
150 date_fmt (FMT,[ARG, ...])
152 Equivelent to "date" but creates a Date::Simple::Fmt object
153 instead. The format is expected to be a valid POSIX::strftime
154 format string.
155 date_iso ([ARG, ...])
157 Identical to "date" but creates a Date::Simple::ISO object instead.
158 date_d8 ([ARG, ...])
160 Equivelent to "date" but creates a Date::Simple::D8 object instead.
161 today()
163 Returns the current date according to "localtime".
164 Caution: To get tomorrow's date (or any fixed offset from today),
166 do not use "today + 1". Perl parses this as "today(+1)". You need
167 to put empty parentheses after the function: "today() + 1".
168 ymd (YEAR, MONTH, DAY)
170 Returns a date object with the given year, month, and day numbers.
171 If the arguments do not specify a valid date, undef is returned.
172 Example:
174 use Date::Simple ('ymd');
176 $pbd = ymd(1987, 12, 18);
177 d8 (STRING)
179 Parses STRING as "YYYYMMDD" and returns the corresponding date
180 object, or undef if STRING has the wrong format or specifies an
181 invalid date.
182 Example:
184 use Date::Simple ('d8');
186 $doi = d8('17760704');
187 Mnemonic: The string matches "/\d{8}/". Also, "d8" spells "date",
189 if 8 is expanded phonetically.
190
192 DATE->next
193 my $tomorrow = $today->next;
194 Returns an object representing tomorrow.
196 DATE->prev
198 my $yesterday = $today->prev;
199 Returns an object representing yesterday.
201 DATE->year
203 my $year = $date->year;
204 Return the year of DATE as an integer.
206 DATE->month
208 my $month = $date->month;
209 Return the month of DATE as an integer from 1 to 12.
211 DATE->day
213 my $day = $date->day;
214 Return the DATE's day of the month as an integer from 1 to 31.
216 DATE->day_of_week
218 Return a number representing DATE's day of the week from 0 to 6,
219 where 0 means Sunday.
220 DATE->as_ymd
222 my ($year, $month, $day) = $date->as_ymd;
223 Returns a list of three numbers: year, month, and day.
225 DATE->as_d8
227 Returns the "d8" representation (see "d8"), like
228 "$date->format("%Y%m%d")".
229 DATE->as_iso
231 Returns the ISO 8601 representation of the date (eg '2004-01-01'),
232 like "$date->format("%Y-%m-%d")". This is in fact the default
233 overloaded stringification mechanism and is provided mostly so
234 other subclasses with different overloading can still do fast ISO
235 style date output.
236 DATE->as_str ([STRING])
238 DATE->format ([STRING])
239 DATE->strftime ([STRING])
240 These functions are equivalent. Return a string representing the
241 date, in the format specified. If you don't pass a parameter, the
242 default date format for the object is used if one has been
243 specified, otherwise uses the default date format for the class the
244 object is a member of, or as a last fallback uses the
245 $Date::Simple::Standard_Format which is changeable, but probably
246 shouldn't be modified. See "default_format" for details.
247 my $change_date = $date->format("%d %b %y");
249 my $iso_date1 = $date->format("%Y-%m-%d");
250 my $iso_date2 = $date->format;
251 The formatting parameter is similar to one you would pass to
253 strftime(3). This is because we actually do pass it to strftime to
254 format the date. This may result in differing behavior across
255 platforms and locales and may not even work everywhere.
256 DATE->default_format ([FORMAT])
258 This method sets or gets the default_format for the DATE object or
259 class that it is called on.
260
262 Some operators can be used with Date::Simple instances. If one side of
263 an expression is a date object, and the operator expects two date
264 objects, the other side is interpreted as "date(ARG)", so an array
265 reference or ISO 8601 string will work.
266 DATE + NUMBER
268 DATE - NUMBER
269 You can construct a new date offset by a number of days using the
270 "+" and "-" operators.
271 DATE1 - DATE2
273 You can subtract two dates to find the number of days between them.
274 DATE1 == DATE2
276 DATE1 < DATE2
277 DATE1 <=> DATE2
278 DATE1 cmp DATE2
279 etc.
280 You can compare two dates using the arithmetic or string comparison
281 operators. Equality tests ("==" and "eq") return false when one of
282 the expressions can not be converted to a date. Other comparison
283 tests die in such cases. This is intentional, because in a sense,
284 all non-dates are not "equal" to all dates, but in no sense are
285 they "greater" or "less" than dates.
286 DATE += NUMBER
288 DATE -= NUMBER
289 You can increment or decrement a date by a number of days using the
290 += and -= operators. This actually generates a new date object and
291 is equivalent to "$date = $date + $number".
292 "$date"
294 You can interpolate a date instance directly into a string, in the
295 format specified by ISO 8601 (eg: 2000-01-17) for Date::Simple and
296 Date::Simple::ISO, for Date::Simple::D8 this is the same as calling
297 as_d8() on the object, and for Date::Simple::Fmt this is the same
298 as calling format() on the object.
299
301 leap_year (YEAR)
302 Returns true if YEAR is a leap year.
303 days_in_month (YEAR, MONTH)
305 Returns the number of days in MONTH, YEAR.
306 leap_year (YEAR)
308 Returns true if YEAR is a leap year.
309 days_in_month (YEAR, MONTH)
311 Returns the number of days in MONTH, YEAR.
312
314 Marty Pauley <marty@kasei.com>
315 John Tobey <jtobey@john-edwin-tobey.org>
316 Yves Orton <demerphq@hotmail.com>
317
319 Copyright (C) 2001 Kasei.
320 Copyright (C) 2001,2002 John Tobey.
321 Copyright (C) 2004 Yves Orton.
322 This program is free software; you can redistribute it and/or
324 modify it under the terms of either:
325 a) the GNU General Public License;
327 either version 2 of the License, or (at your option) any later
328 version. You should have received a copy of the GNU General
329 Public License along with this program; see the file COPYING.
330 If not, write to the Free Software Foundation, Inc., 59
331 Temple Place, Suite 330, Boston, MA 02111-1307 USA
332 b) the Perl Artistic License.
334 This program is distributed in the hope that it will be useful,
336 but WITHOUT ANY WARRANTY; without even the implied warranty of
337 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
338
340 Date::Simple::Fmt Date::Simple::ISO Date::Simple::D8 and of course perl
341perl v5.34.0 2022-01-21 Date::Simple(3)