Provided by: libdate-simple-perl_3.0300-1build4_amd64 bug

NAME

       Date::Simple - a simple date object

SYNOPSIS

           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])

DESCRIPTION

       Dates are complex enough without times and timezones.  This module may be used to create
       simple date objects.  It handles:

       Validation.
           Reject 1999-02-29 but accept 2000-02-29.

       Interval arithmetic.
           How many days were between two given dates?  What date comes N days after today?

       Day-of-week calculation.
           What day of the week is a given date?

       Transparent date formatting.
           How should a date object be formatted.

       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.

   Controlling output format.
       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:

       Date::Simple::ISO
           Identical to Date::Simple in every respect but name.

       Date::Simple::D8
           Uses the D8 format (%Y%m%d) as the default format for printing. Uses XS for the
           overloaded stringification.

       Date::Simple::Fmt
           Uses the perl implemented 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.

CONSTRUCTORS

       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.

       Date::Simple->new ([ARG, ...])
       date ([ARG, ...])
               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_fmt (FMT,[ARG, ...])
           Equivelent to "date" but creates a Date::Simple::Fmt object instead. The format is
           expected to be a valid POSIX::strftime format string.

       date_iso ([ARG, ...])
           Identical to "date" but creates a Date::Simple::ISO object instead.

       date_d8 ([ARG, ...])
           Equivelent to "date" but creates a Date::Simple::D8 object instead.

       today()
           Returns the current date according to "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".

       ymd (YEAR, MONTH, DAY)
           Returns a date object with the given year, month, and day numbers.  If the arguments
           do not specify a valid date, undef is returned.

           Example:

               use Date::Simple ('ymd');
               $pbd = ymd(1987, 12, 18);

       d8 (STRING)
           Parses STRING as "YYYYMMDD" and returns the corresponding date object, or undef if
           STRING has the wrong format or specifies an invalid date.

           Example:

               use Date::Simple ('d8');
               $doi = d8('17760704');

           Mnemonic: The string matches "/\d{8}/".  Also, "d8" spells "date", if 8 is expanded
           phonetically.

INSTANCE METHODS

       DATE->next
               my $tomorrow = $today->next;

           Returns an object representing tomorrow.

       DATE->prev
              my $yesterday = $today->prev;

           Returns an object representing yesterday.

       DATE->year
               my $year  = $date->year;

           Return the year of DATE as an integer.

       DATE->month
               my $month = $date->month;

           Return the month of DATE as an integer from 1 to 12.

       DATE->day
               my $day   = $date->day;

           Return the DATE's day of the month as an integer from 1 to 31.

       DATE->day_of_week
           Return a number representing DATE's day of the week from 0 to 6, where 0 means Sunday.

       DATE->as_ymd
               my ($year, $month, $day) = $date->as_ymd;

           Returns a list of three numbers: year, month, and day.

       DATE->as_d8
           Returns the "d8" representation (see "d8"), like "$date->format("%Y%m%d")".

       DATE->as_iso
           Returns the ISO 8601 representation of the date (eg '2004-01-01'), like
           "$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.

       DATE->as_str ([STRING])
       DATE->format ([STRING])
       DATE->strftime ([STRING])
           These functions are equivalent.  Return a string representing the date, in the format
           specified.  If you don't pass a parameter, the default date format for the object is
           used if one has been specified, otherwise uses the default date format for the class
           the object is a member of, or as a last fallback uses the
           $Date::Simple::Standard_Format which is changeable, but probably shouldn't be
           modified. See "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.

       DATE->default_format ([FORMAT])
           This method sets or gets the default_format for the DATE object or class that it is
           called on.

OPERATORS

       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.

       DATE + NUMBER
       DATE - NUMBER
           You can construct a new date offset by a number of days using the "+" and "-"
           operators.

       DATE1 - DATE2
           You can subtract two dates to find the number of days between them.

       DATE1 == DATE2
       DATE1 < DATE2
       DATE1 <=> DATE2
       DATE1 cmp DATE2
       etc.
           You can compare two dates using the arithmetic or string comparison operators.
           Equality tests ("==" 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 += NUMBER
       DATE -= NUMBER
           You can increment or decrement a date by a number of days using the += and -=
           operators.  This actually generates a new date object and is equivalent to "$date =
           $date + $number".

       "$date"
           You can interpolate a date instance directly into a string, in the format specified by
           ISO 8601 (eg: 2000-01-17) for Date::Simple and Date::Simple::ISO, for Date::Simple::D8
           this is the same as calling as_d8() on the object, and for Date::Simple::Fmt this is
           the same as calling format() on the object.

UTILITIES

       leap_year (YEAR)
           Returns true if YEAR is a leap year.

       days_in_month (YEAR, MONTH)
           Returns the number of days in MONTH, YEAR.

       leap_year (YEAR)
           Returns true if YEAR is a leap year.

       days_in_month (YEAR, MONTH)
           Returns the number of days in MONTH, YEAR.

AUTHOR

           Marty Pauley <marty@kasei.com>
           John Tobey <jtobey@john-edwin-tobey.org>
           Yves Orton <demerphq@hotmail.com>

COPYRIGHT

             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.

SEE ALSO

       Date::Simple::Fmt Date::Simple::ISO Date::Simple::D8 and of course perl