| Date::Simple - a simple date object |
Date::Simple - a simple date object
use Date::Simple ('date', 'today');
# Difference in days between two dates:
$diff = date('2001-08-27') - date('1977-10-05');
# Offset $n days from now:
$date = today() + $n;
print "$date\n"; # uses ISO 8601 format (YYYY-MM-DD)
use Date::Simple ();
my $date = Date::Simple->new('1972-01-17');
my $year = $date->year;
my $month = $date->month;
my $day = $date->day;
use Date::Simple (':all');
my $date2 = ymd($year, $month, $day);
my $date3 = d8('19871218');
my $today = today();
my $tomorrow = $today + 1;
if ($tomorrow->year != $today->year) {
print "Today is New Year's Eve!\n";
}
if ($today > $tomorrow) {
die "warp in space-time continuum";
}
print "Today is ";
print(('Sun','Mon','Tues','Wednes','Thurs','Fri','Satur')
[$today->day_of_week]);
print "day.\n";
# you can also do this:
($date cmp "2001-07-01")
# and this
($date <=> [2001, 7, 1])
Dates are complex enough without times and timezones. This module may be used to create simple date objects. It handles:
It does not deal with hours, minutes, seconds, and time zones.
A date is uniquely identified by year, month, and day integers within valid ranges. This module will not allow the creation of objects for invalid dates. Attempting to create an invalid date will return undef. Month numbering starts at 1 for January, unlike in C and Java. Years are 4-digit.
Gregorian dates up to year 9999 are handled correctly, but we rely on
Perl's builtin localtime function when the current date is
requested. On some platforms, localtime may be vulnerable to
rollovers such as the Unix time_t wraparound of 18 January 2038.
Overloading is used so you can compare or subtract two dates using
standard numeric operators such as ==, and the sum of a date object
and an integer is another date object.
Date::Simple objects are immutable. After assigning $date1 to
$date2, no change to $date1 can affect $date2. This means,
for example, that there is nothing like a set_year operation, and
$date++ assigns a new object to $date.
This module contains various undocumented functions. They may not be available on all platforms and are likely to change or disappear in future releases. Please let the author know if you think any of them should be public.
As of version 3.0 new ways of controlling the output formats of Date::Simple
objects has been provided. However Date::Simple has traditionally provided
few ways of stringification, a primary one via the format() method and another
primary one via direct stringification. However the later is currently
implemented as an XS routine and the former is implemented through a perl routine.
This means that using format() is more expensive than stringification and
that the stringification format is class specific.
In order to alleviate some of these problems a new mechanism has been introduced
to Date::Simple that allows for a per object level format default. In addition
a set of utility classes that have different stringification overloads provided.
These classes are simple subclasses of Date::Simple and beside the default format()
and the overloaded stringification behaviour are identical to Date::Simple. In fact
one is totally identical to Date::Simple and is provided mostly for completeness.
The classes included are:
format() as the default stringification mechanism. The first
argument to the constructor is expected to be the format to use for the object.
NOTE its important to remember that the primary difference between the behaviour
of objects of the different classes is how they are stringified when quoted, and what
date format is used by default when the format() method is called. Nothing else differs.
Several functions take a string or numeric representation and generate
a corresponding date object. The most general is new, whose
argument list may be empty (returning the current date), a string in
format YYYY-MM-DD or YYYYMMDD, a list or arrayref of year, month, and
day number, or an existing date object.
my $date = Date::Simple->new('1972-01-17');
The new method will return a date object if the values passed in
specify a valid date. (See above.) If an invalid date is passed, the
method returns undef. If the argument is invalid in form as opposed
to numeric range, new dies.
The date function provides the same functionality but must be
imported or qualified as Date::Simple::date. (To import all public
functions, do use Date::Simple (':all');.) This function returns
undef on all invalid input, rather than dying in some cases like
new.
date but creates a Date::Simple::Fmt object instead. The
format is expected to be a valid POSIX::strftime format string.
date but creates a Date::Simple::ISO object instead.
date but creates a Date::Simple::D8 object instead.
today()localtime.
Caution: To get tomorrow's date (or any fixed offset from today),
do not use today + 1. Perl parses this as today(+1). You need
to put empty parentheses after the function: today() + 1.
Example:
use Date::Simple ('ymd');
$pbd = ymd(1987, 12, 18);
Example:
use Date::Simple ('d8');
$doi = d8('17760704');
Mnemonic: The string matches /\d{8}/. Also, ``d8'' spells ``date'', if
8 is expanded phonetically.
my $tomorrow = $today->next;
Returns an object representing tomorrow.
my $yesterday = $today->prev;
Returns an object representing yesterday.
my $year = $date->year;
Return the year of DATE as an integer.
my $month = $date->month;
Return the month of DATE as an integer from 1 to 12.
my $day = $date->day;
Return the DATE's day of the month as an integer from 1 to 31.
my ($year, $month, $day) = $date->as_ymd;
Returns a list of three numbers: year, month, and day.
d8), like
$date->format("%Y%m%d").
$date->format("%Y-%m-%d"). This is in fact the default
overloaded stringification mechanism and is provided mostly so
other subclasses with different overloading can still do fast
ISO style date output.
default_format for details.
my $change_date = $date->format("%d %b %y");
my $iso_date1 = $date->format("%Y-%m-%d");
my $iso_date2 = $date->format;
The formatting parameter is similar to one you would pass to strftime(3). This is because we actually do pass it to strftime to format the date. This may result in differing behavior across platforms and locales and may not even work everywhere.
Some operators can be used with Date::Simple instances. If one side
of an expression is a date object, and the operator expects two date
objects, the other side is interpreted as date(ARG), so an array
reference or ISO 8601 string will work.
+
and - operators.
== and eq) return false when one of
the expressions can not be converted to a date. Other comparison
tests die in such cases. This is intentional, because in a sense, all
non-dates are not ``equal'' to all dates, but in no sense are they
``greater'' or ``less'' than dates.
$date = $date + $number.
as_d8() on the object, and for Date::Simple::Fmt this is the same as
calling format() on the object.
Marty Pauley <marty@kasei.com>
John Tobey <jtobey@john-edwin-tobey.org>
Yves Orton <demerphq@hotmail.com>
Copyright (C) 2001 Kasei.
Copyright (C) 2001,2002 John Tobey.
Copyright (C) 2004 Yves Orton.
This program is free software; you can redistribute it and/or
modify it under the terms of either:
a) the GNU General Public License;
either version 2 of the License, or (at your option) any later
version. You should have received a copy of the GNU General
Public License along with this program; see the file COPYING.
If not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA
b) the Perl Artistic License.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
the Date::Simple::Fmt manpage the Date::Simple::ISO manpage the Date::Simple::D8 manpage and of course the perl manpage
| Date::Simple - a simple date object |