Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Date::Simple.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Date::Simple 3"
.TH Date::Simple 3 "2002-12-06" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Date::Simple \- a simple date object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Date::Simple ('date', 'today');
.Ve
.PP
.Vb 2
\&    # Difference in days between two dates:
\&    $diff = date('2001-08-27') - date('1977-10-05');
.Ve
.PP
.Vb 3
\&    # Offset $n days from now:
\&    $date = today() + $n;
\&    print "$date\en";  # uses ISO 8601 format (YYYY-MM-DD)
.Ve
.PP
.Vb 5
\&    use Date::Simple ();
\&    my $date  = Date::Simple->new('1972-01-17');
\&    my $year  = $date->year;
\&    my $month = $date->month;
\&    my $day   = $date->day;
.Ve
.PP
.Vb 8
\&    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!\en";
\&    }
.Ve
.PP
.Vb 3
\&    if ($today > $tomorrow) {
\&        die "warp in space-time continuum";
\&    }
.Ve
.PP
.Vb 4
\&    print "Today is ";
\&    print(('Sun','Mon','Tues','Wednes','Thurs','Fri','Satur')
\&          [$today->day_of_week]);
\&    print "day.\en";
.Ve
.PP
.Vb 4
\&    # you can also do this:
\&    ($date cmp "2001-07-01")
\&    # and this
\&    ($date <=> [2001, 7, 1])
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Dates are complex enough without times and timezones.  This module may
be used to create simple date objects.  It handles:
.IP "Validation." 4
.IX Item "Validation."
Reject 1999\-02\-29 but accept 2000\-02\-29.
.IP "Interval arithmetic." 4
.IX Item "Interval arithmetic."
How many days were between two given dates?  What date comes N days
after today?
.IP "Day-of-week calculation." 4
.IX Item "Day-of-week calculation."
What day of the week is a given date?
.PP
It does \fBnot\fR deal with hours, minutes, seconds, and time zones.
.PP
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.
.PP
Gregorian dates up to year 9999 are handled correctly, but we rely on
Perl's builtin \f(CW\*(C`localtime\*(C'\fR function when the current date is
requested.  On some platforms, \f(CW\*(C`localtime\*(C'\fR may be vulnerable to
rollovers such as the Unix \f(CW\*(C`time_t\*(C'\fR wraparound of 18 January 2038.
.PP
Overloading is used so you can compare or subtract two dates using
standard numeric operators such as \f(CW\*(C`==\*(C'\fR, and the sum of a date object
and an integer is another date object.
.PP
Date::Simple objects are immutable.  After assigning \f(CW$date1\fR to
\&\f(CW$date2\fR, no change to \f(CW$date1\fR can affect \f(CW$date2\fR.  This means,
for example, that there is nothing like a \f(CW\*(C`set_year\*(C'\fR operation, and
\&\f(CW\*(C`$date++\*(C'\fR assigns a new object to \f(CW$date\fR.
.PP
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.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
Several functions take a string or numeric representation and generate
a corresponding date object.  The most general is \f(CW\*(C`new\*(C'\fR, whose
argument list may be empty (returning the current date), a string in
format YYYY-MM-DD or \s-1YYYYMMDD\s0, a list or arrayref of year, month, and
day number, or an existing date object.
.IP "Date::Simple\->new ([\s-1ARG\s0, ...])" 4
.IX Item "Date::Simple->new ([ARG, ...])"
.PD 0
.IP "date ([\s-1ARG\s0, ...])" 4
.IX Item "date ([ARG, ...])"
.PD
.Vb 1
\&    my $date = Date::Simple->new('1972-01-17');
.Ve
.Sp
The \f(CW\*(C`new\*(C'\fR 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, \f(CW\*(C`new\*(C'\fR dies.
.Sp
The \f(CW\*(C`date\*(C'\fR function provides the same functionality but must be
imported or qualified as \f(CW\*(C`Date::Simple::date\*(C'\fR.  (To import all public
functions, do \f(CW\*(C`use Date::Simple (':all');\*(C'\fR.)  This function returns
undef on all invalid input, rather than dying in some cases like
\&\f(CW\*(C`new\*(C'\fR.
.IP "\fItoday()\fR" 4
.IX Item "today()"
Returns the current date according to \f(CW\*(C`localtime\*(C'\fR.
.Sp
\&\fBCaution:\fR To get tomorrow's date (or any fixed offset from today),
do not use \f(CW\*(C`today + 1\*(C'\fR.  Perl parses this as \f(CW\*(C`today(+1)\*(C'\fR.  You need
to put empty parentheses after the function: \f(CW\*(C`today() + 1\*(C'\fR.
.IP "ymd (\s-1YEAR\s0, \s-1MONTH\s0, \s-1DAY\s0)" 4
.IX Item "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.
.Sp
Example:
.Sp
.Vb 2
\&    use Date::Simple ('ymd');
\&    $pbd = ymd(1987, 12, 18);
.Ve
.IP "d8 (\s-1STRING\s0)" 4
.IX Item "d8 (STRING)"
Parses \s-1STRING\s0 as \*(L"\s-1YYYYMMDD\s0\*(R" and returns the corresponding date object,
or undef if \s-1STRING\s0 has the wrong format or specifies an invalid date.
.Sp
Example:
.Sp
.Vb 2
\&    use Date::Simple ('d8');
\&    $doi = d8('17760704');
.Ve
.Sp
Mnemonic: The string matches \f(CW\*(C`/\ed{8}/\*(C'\fR.  Also, \*(L"d8\*(R" spells \*(L"date\*(R", if
8 is expanded phonetically.
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.IP "\s-1DATE\-\s0>next" 4
.IX Item "DATE->next"
.Vb 1
\&    my $tomorrow = $today->next;
.Ve
.Sp
Returns an object representing tomorrow.
.IP "\s-1DATE\-\s0>prev" 4
.IX Item "DATE->prev"
.Vb 1
\&    my $yesterday = $today->prev;
.Ve
.Sp
Returns an object representing yesterday.
.IP "\s-1DATE\-\s0>year" 4
.IX Item "DATE->year"
.Vb 1
\&    my $year  = $date->year;
.Ve
.Sp
Return the year of \s-1DATE\s0 as an integer.
.IP "\s-1DATE\-\s0>month" 4
.IX Item "DATE->month"
.Vb 1
\&    my $month = $date->month;
.Ve
.Sp
Return the month of \s-1DATE\s0 as an integer from 1 to 12.
.IP "\s-1DATE\-\s0>day" 4
.IX Item "DATE->day"
.Vb 1
\&    my $day   = $date->day;
.Ve
.Sp
Return the \s-1DATE\s0's day of the month as an integer from 1 to 31.
.IP "\s-1DATE\-\s0>day_of_week" 4
.IX Item "DATE->day_of_week"
Return a number representing \s-1DATE\s0's day of the week from 0 to 6, where
0 means Sunday.
.IP "\s-1DATE\-\s0>as_ymd" 4
.IX Item "DATE->as_ymd"
.Vb 1
\&    my ($year, $month, $day) = $date->as_ymd;
.Ve
.Sp
Returns a list of three numbers: year, month, and day.
.IP "\s-1DATE\-\s0>as_d8" 4
.IX Item "DATE->as_d8"
Returns the \*(L"d8\*(R" representation (see \f(CW\*(C`d8\*(C'\fR), like
\&\f(CW\*(C`$date\->format("%Y%m%d")\*(C'\fR.
.IP "\s-1DATE\-\s0>format (\s-1STRING\s0)" 4
.IX Item "DATE->format (STRING)"
.PD 0
.IP "\s-1DATE\-\s0>strftime (\s-1STRING\s0)" 4
.IX Item "DATE->strftime (STRING)"
.PD
These functions are equivalent.  Return a string representing the
date, in the format specified.  If you don't pass a parameter, an \s-1ISO\s0
8601 formatted date is returned.
.Sp
.Vb 3
\&    my $change_date = $date->format("%d %b %y");
\&    my $iso_date1 = $date->format("%Y-%m-%d");
\&    my $iso_date2 = $date->format;
.Ve
.Sp
The formatting parameter is similar to one you would pass to
\&\fIstrftime\fR\|(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.
.SH "OPERATORS"
.IX Header "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 \f(CW\*(C`date(ARG)\*(C'\fR, so an array
reference or \s-1ISO\s0 8601 string will work.
.IP "\s-1DATE\s0 + \s-1NUMBER\s0" 4
.IX Item "DATE + NUMBER"
.PD 0
.IP "\s-1DATE\s0 \- \s-1NUMBER\s0" 4
.IX Item "DATE - NUMBER"
.PD
You can construct a new date offset by a number of days using the \f(CW\*(C`+\*(C'\fR
and \f(CW\*(C`\-\*(C'\fR operators.
.IP "\s-1DATE1\s0 \- \s-1DATE2\s0" 4
.IX Item "DATE1 - DATE2"
You can subtract two dates to find the number of days between them.
.IP "\s-1DATE1\s0 == \s-1DATE2\s0" 4
.IX Item "DATE1 == DATE2"
.PD 0
.IP "\s-1DATE1\s0 < \s-1DATE2\s0" 4
.IX Item "DATE1 < DATE2"
.IP "\s-1DATE1\s0 <=> \s-1DATE2\s0" 4
.IX Item "DATE1 <=> DATE2"
.IP "\s-1DATE1\s0 cmp \s-1DATE2\s0" 4
.IX Item "DATE1 cmp DATE2"
.IP "etc." 4
.IX Item "etc."
.PD
You can compare two dates using the arithmetic or string comparison
operators.  Equality tests (\f(CW\*(C`==\*(C'\fR and \f(CW\*(C`eq\*(C'\fR) 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 \*(L"equal\*(R" to all dates, but in no sense are they
\&\*(L"greater\*(R" or \*(L"less\*(R" than dates.
.IP "\s-1DATE\s0 += \s-1NUMBER\s0" 4
.IX Item "DATE += NUMBER"
.PD 0
.IP "\s-1DATE\s0 \-= \s-1NUMBER\s0" 4
.IX Item "DATE -= NUMBER"
.PD
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 \f(CW\*(C`$date = $date + $number\*(C'\fR.
.ie n .IP """$date""" 4
.el .IP "``$date''" 4
.IX Item "$date"
You can interpolate a date instance directly into a string, in the
format specified by \s-1ISO\s0 8601 (eg: 2000\-01\-17).
.SH "UTILITIES"
.IX Header "UTILITIES"
.IP "leap_year (\s-1YEAR\s0)" 4
.IX Item "leap_year (YEAR)"
Returns true if \s-1YEAR\s0 is a leap year.
.IP "days_in_month (\s-1YEAR\s0, \s-1MONTH\s0)" 4
.IX Item "days_in_month (YEAR, MONTH)"
Returns the number of days in \s-1MONTH\s0, \s-1YEAR\s0.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\&    Marty Pauley <marty@kasei.com>
\&    John Tobey <jtobey@john-edwin-tobey.org>
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 2
\&      Copyright (C) 2001  Kasei
\&      Copyright (C) 2001,2002 John Tobey.
.Ve
.PP
.Vb 2
\&      This program is free software; you can redistribute it and/or
\&      modify it under the terms of either:
.Ve
.PP
.Vb 6
\&      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
.Ve
.PP
.Vb 1
\&      b) the Perl Artistic License.
.Ve
.PP
.Vb 3
\&      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.
.Ve