1Date::Simple(3)       User Contributed Perl Documentation      Date::Simple(3)
2
3
4

NAME

6       Date::Simple - a simple date object
7

SYNOPSIS

9           use Date::Simple ('date', 'today');
10
11           # Difference in days between two dates:
12           $diff = date('2001-08-27') - date('1977-10-05');
13
14           # Offset $n days from now:
15           $date = today() + $n;
16           print "$date\n";  # uses ISO 8601 format (YYYY-MM-DD)
17
18           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
24           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
33           if ($today > $tomorrow) {
34               die "warp in space-time continuum";
35           }
36
37           print "Today is ";
38           print(('Sun','Mon','Tues','Wednes','Thurs','Fri','Satur')
39                 [$today->day_of_week]);
40           print "day.\n";
41
42           # you can also do this:
43           ($date cmp "2001-07-01")
44           # and this
45           ($date <=> [2001, 7, 1])
46

DESCRIPTION

48       Dates are complex enough without times and timezones.  This module may
49       be used to create simple date objects.  It handles:
50
51       Validation.
52           Reject 1999-02-29 but accept 2000-02-29.
53
54       Interval arithmetic.
55           How many days were between two given dates?  What date comes N days
56           after today?
57
58       Day-of-week calculation.
59           What day of the week is a given date?
60
61       Transparent date formatting.
62           How should a date object be formatted.
63
64       It does not deal with hours, minutes, seconds, and time zones.
65
66       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
72       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
77       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
81       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
86       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
91   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
101       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
110       The classes included are:
111
112       Date::Simple::ISO
113           Identical to Date::Simple in every respect but name.
114
115       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
119       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
124       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

CONSTRUCTORS

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
136       Date::Simple->new ([ARG, ...])
137       date ([ARG, ...])
138               my $date = Date::Simple->new('1972-01-17');
139
140           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
145           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
151       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
156       date_iso ([ARG, ...])
157           Identical to "date" but creates a Date::Simple::ISO object instead.
158
159       date_d8 ([ARG, ...])
160           Equivelent to "date" but creates a Date::Simple::D8 object instead.
161
162       today()
163           Returns the current date according to "localtime".
164
165           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
169       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
173           Example:
174
175               use Date::Simple ('ymd');
176               $pbd = ymd(1987, 12, 18);
177
178       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
183           Example:
184
185               use Date::Simple ('d8');
186               $doi = d8('17760704');
187
188           Mnemonic: The string matches "/\d{8}/".  Also, "d8" spells "date",
189           if 8 is expanded phonetically.
190

INSTANCE METHODS

192       DATE->next
193               my $tomorrow = $today->next;
194
195           Returns an object representing tomorrow.
196
197       DATE->prev
198              my $yesterday = $today->prev;
199
200           Returns an object representing yesterday.
201
202       DATE->year
203               my $year  = $date->year;
204
205           Return the year of DATE as an integer.
206
207       DATE->month
208               my $month = $date->month;
209
210           Return the month of DATE as an integer from 1 to 12.
211
212       DATE->day
213               my $day   = $date->day;
214
215           Return the DATE's day of the month as an integer from 1 to 31.
216
217       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
221       DATE->as_ymd
222               my ($year, $month, $day) = $date->as_ymd;
223
224           Returns a list of three numbers: year, month, and day.
225
226       DATE->as_d8
227           Returns the "d8" representation (see "d8"), like
228           "$date->format("%Y%m%d")".
229
230       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
237       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
248               my $change_date = $date->format("%d %b %y");
249               my $iso_date1 = $date->format("%Y-%m-%d");
250               my $iso_date2 = $date->format;
251
252           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
257       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

OPERATORS

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
267       DATE + NUMBER
268       DATE - NUMBER
269           You can construct a new date offset by a number of days using the
270           "+" and "-" operators.
271
272       DATE1 - DATE2
273           You can subtract two dates to find the number of days between them.
274
275       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
287       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
293       "$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

UTILITIES

301       leap_year (YEAR)
302           Returns true if YEAR is a leap year.
303
304       days_in_month (YEAR, MONTH)
305           Returns the number of days in MONTH, YEAR.
306
307       leap_year (YEAR)
308           Returns true if YEAR is a leap year.
309
310       days_in_month (YEAR, MONTH)
311           Returns the number of days in MONTH, YEAR.
312

AUTHOR

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
323             This program is free software; you can redistribute it and/or
324             modify it under the terms of either:
325
326             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
333             b) the Perl Artistic License.
334
335             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

SEE ALSO

340       Date::Simple::Fmt Date::Simple::ISO Date::Simple::D8 and of course perl
341
342
343
344perl v5.34.0                      2022-01-21                   Date::Simple(3)
Impressum