=> T
\& NUM must be in the range 1\-7.
\&
\& % These return the NUMth value of the %B and %b formats
\& % respectively. In English, that would yield:
\& % => February
\& % => Feb
\& NUM must be in the range 1\-12 (or 01\-12).
\&
\& % These return the NUMth value of the %p format. In
\& English, that would yield:
\& %
=> AM
\& %
=> PM
\& NUM must be in the range 1\-2.
\&
\& % These return the NUMth value of the %E format. In
\& English, that would yield:
\& % => 1st
\& % => 53rd
\& NUM must be in the range 1\-53.
.Ve
.PP
If a lone percent is the final character in a format, it is ignored.
.PP
The formats used in this routine were originally based on date.pl (version
3.2) by Terry McGonigal, as well as a couple taken from different versions
of the Solaris \fIdate\fR\|(1) command. Also, several have been added which are
unique to Date::Manip.
.PP
\&\s-1NOTE\s0 1:
.PP
The ls format (%l) applies to date within the past \s-1OR\s0 future 6 months!
Any date that is before the date \s-1NOW\s0 \- 6 months, or that is on or
after the date \s-1NOW\s0 + 6 months will have the year printed out.
.PP
The later time must be on or after so that there is no ambiguity. If it
is now 2000\-06\-06\-12:00:00, then the date 1999\-12\-06\-12:00:00 will be
written as \*(L"Dec 6 12:00\*(R" but the date 2000\-12\-06\-12:00:00 will be written
as \*(L"Dec 6 2000\*(R".
.PP
\&\s-1NOTE\s0 2:
.PP
The \f(CW%U\fR, \f(CW%W\fR, \f(CW%L\fR, \f(CW%G\fR, and \f(CW%J\fR formats are used to support the \s-1ISO\-8601\s0 format:
YYYY-wWW-D. In this format, a date is written as a year, the week of the
year, and the day of the week. Technically, the week may be considered to
start on any day of the week, but Sunday and Monday are the both common
choices, so both are supported.
.PP
The \f(CW%W\fR and \f(CW%G\fR formats return the week-of-year and the year treating weeks
as starting on Monday.
.PP
The \f(CW%U\fR and \f(CW%L\fR formats return the week-of-year and the year treating weeks
as starting on Sunday.
.PP
Most of the time, the \f(CW%L\fR and \f(CW%G\fR formats returns the same value as the \f(CW%Y\fR
format, but there is a problem with days occurring in the first or last week
of the year.
.PP
The \s-1ISO\-8601\s0 representation of Jan 1, 1993 written in the YYYY-wWW-D format
is actually 1992\-W53\-5. In other words, Jan 1 is treated as being in the
last week of the preceding year. Depending on the year, days in the first
week of a year may belong to the previous year, and days in the final week
of a year may belong to the next year. The week is assigned to the year
which has most of the days. For example, if the week starts on Sunday,
then the last week of 2003 is 2003\-12\-28 to 2004\-01\-03. This week is
assigned to 2003 since 4 of the days in it are in 2003 and only 3 of them
are in 2004. The first week of 2004 starts on 2004\-01\-04.
.PP
The \f(CW%U\fR and \f(CW%W\fR formats return a week-of-year number from 01 to 53. \f(CW%L\fR and
\&\f(CW%G\fR return the corresponding year, and to get this type of information,
you should always use the (%W,%G) combination or (%U,%L) combination. \f(CW%Y\fR
should not be used as it will yield incorrect results.
.PP
\&\f(CW%J\fR returns the full \s-1ISO\-8601\s0 format (%G\-W%W\-%w).
.PP
\&\s-1NOTE\s0 3:
.PP
The \f(CW%s\fR and \f(CW%o\fR formats return negative values if the date is before
the start of the epoch. Other Unix utilities would return an error, or
a zero, so if you are going to use Date::Manip in conjunction with these,
be sure to check for a negative value.
.PP
\&\s-1NOTE\s0 4:
.PP
The \f(CW%z\fR format returns the offset in the \s-1RFC\s0 822 specified format
+0500 . Most offsets are full hour amounts, so this is not a problem,
but some offsets are irregular (+05:17:30). In this case, the string
returned is +051730 which isn't \s-1RFC\s0 822 compliant, but since \s-1RFC\s0 822
ignores this situation, I had to decide between returning an incorrect
value, or breaking strict compliance, and I chose the second option.
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
None known.
.SH "BUGS AND QUESTIONS"
.IX Header "BUGS AND QUESTIONS"
Please refer to the Date::Manip::Problems documentation for
information on submitting bug reports or questions to the author.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Date::Manip \- main module documentation
.SH "LICENSE"
.IX Header "LICENSE"
This script is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Sullivan Beck (sbeck@cpan.org)