--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.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. \*(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-
+.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\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" 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 "DateTime 3"
+.TH DateTime 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+DateTime \- A date and time object
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use DateTime;
+\&
+\& $dt = DateTime\->new( year => 1964,
+\& month => 10,
+\& day => 16,
+\& hour => 16,
+\& minute => 12,
+\& second => 47,
+\& nanosecond => 500000000,
+\& time_zone => \*(AqAsia/Taipei\*(Aq,
+\& );
+\&
+\& $dt = DateTime\->from_epoch( epoch => $epoch );
+\& $dt = DateTime\->now; # same as ( epoch => time() )
+\&
+\& $year = $dt\->year;
+\& $month = $dt\->month; # 1\-12 \- also mon
+\&
+\& $day = $dt\->day; # 1\-31 \- also day_of_month, mday
+\&
+\& $dow = $dt\->day_of_week; # 1\-7 (Monday is 1) \- also dow, wday
+\&
+\& $hour = $dt\->hour; # 0\-23
+\& $minute = $dt\->minute; # 0\-59 \- also min
+\&
+\& $second = $dt\->second; # 0\-61 (leap seconds!) \- also sec
+\&
+\& $doy = $dt\->day_of_year; # 1\-366 (leap years) \- also doy
+\&
+\& $doq = $dt\->day_of_quarter; # 1.. \- also doq
+\&
+\& $qtr = $dt\->quarter; # 1\-4
+\&
+\& # all of the start\-at\-1 methods above have correponding start\-at\-0
+\& # methods, such as $dt\->day_of_month_0, $dt\->month_0 and so on
+\&
+\& $ymd = $dt\->ymd; # 2002\-12\-06
+\& $ymd = $dt\->ymd(\*(Aq/\*(Aq); # 2002/12/06 \- also date
+\&
+\& $mdy = $dt\->mdy; # 12\-06\-2002
+\& $mdy = $dt\->mdy(\*(Aq/\*(Aq); # 12/06/2002
+\&
+\& $dmy = $dt\->dmy; # 06\-12\-2002
+\& $dmy = $dt\->dmy(\*(Aq/\*(Aq); # 06/12/2002
+\&
+\& $hms = $dt\->hms; # 14:02:29
+\& $hms = $dt\->hms(\*(Aq!\*(Aq); # 14!02!29 \- also time
+\&
+\& $is_leap = $dt\->is_leap_year;
+\&
+\& # these are localizable, see Locales section
+\& $month_name = $dt\->month_name; # January, February, ...
+\& $month_abbr = $dt\->month_abbr; # Jan, Feb, ...
+\& $day_name = $dt\->day_name; # Monday, Tuesday, ...
+\& $day_abbr = $dt\->day_abbr; # Mon, Tue, ...
+\&
+\& # May not work for all possible datetime, see the docs on this
+\& # method for more details.
+\& $epoch_time = $dt\->epoch;
+\&
+\& $dt2 = $dt + $duration_object;
+\&
+\& $dt3 = $dt \- $duration_object;
+\&
+\& $duration_object = $dt \- $dt2;
+\&
+\& $dt\->set( year => 1882 );
+\&
+\& $dt\->set_time_zone( \*(AqAmerica/Chicago\*(Aq );
+\&
+\& $dt\->set_formatter( $formatter );
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+DateTime is a class for the representation of date/time combinations,
+and is part of the Perl DateTime project. For details on this project
+please see <http://datetime.perl.org/>. The DateTime site has a \s-1FAQ\s0
+which may help answer many \*(L"how do I do X?\*(R" questions. The \s-1FAQ\s0 is at
+<http://datetime.perl.org/?FAQ>.
+.PP
+It represents the Gregorian calendar, extended backwards in time
+before its creation (in 1582). This is sometimes known as the
+\&\*(L"proleptic Gregorian calendar\*(R". In this calendar, the first day of
+the calendar (the epoch), is the first day of year 1, which
+corresponds to the date which was (incorrectly) believed to be the
+birth of Jesus Christ.
+.PP
+The calendar represented does have a year 0, and in that way differs
+from how dates are often written using \*(L"\s-1BCE/CE\s0\*(R" or \*(L"\s-1BC/AD\s0\*(R".
+.PP
+For infinite datetimes, please see the
+DateTime::Infinite module.
+.SH "USAGE"
+.IX Header "USAGE"
+.SS "0\-based Versus 1\-based Numbers"
+.IX Subsection "0-based Versus 1-based Numbers"
+The DateTime.pm module follows a simple consistent logic for
+determining whether or not a given number is 0\-based or 1\-based.
+.PP
+Month, day of month, day of week, and day of year are 1\-based. Any
+method that is 1\-based also has an equivalent 0\-based method ending in
+\&\*(L"_0\*(R". So for example, this class provides both \f(CW\*(C`day_of_week()\*(C'\fR and
+\&\f(CW\*(C`day_of_week_0()\*(C'\fR methods.
+.PP
+The \f(CW\*(C`day_of_week_0()\*(C'\fR method still treats Monday as the first day of
+the week.
+.PP
+All \fItime\fR\-related numbers such as hour, minute, and second are
+0\-based.
+.PP
+Years are neither, as they can be both positive or negative, unlike
+any other datetime component. There \fIis\fR a year 0.
+.PP
+There is no \f(CW\*(C`quarter_0()\*(C'\fR method.
+.SS "Error Handling"
+.IX Subsection "Error Handling"
+Some errors may cause this module to die with an error string. This
+can only happen when calling constructor methods, methods that change
+the object, such as \f(CW\*(C`set()\*(C'\fR, or methods that take parameters.
+Methods that retrieve information about the object, such as \f(CW\*(C`year()\*(C'\fR
+or \f(CW\*(C`epoch()\*(C'\fR, will never die.
+.SS "Locales"
+.IX Subsection "Locales"
+All the object methods which return names or abbreviations return data
+based on a locale. This is done by setting the locale when
+constructing a DateTime object. There is also a \f(CW\*(C`DefaultLocale()\*(C'\fR
+class method which may be used to set the default locale for all
+DateTime objects created. If this is not set, then \*(L"en_US\*(R" is used.
+.SS "Floating DateTimes"
+.IX Subsection "Floating DateTimes"
+The default time zone for new DateTime objects, except where stated
+otherwise, is the \*(L"floating\*(R" time zone. This concept comes from the
+iCal standard. A floating datetime is one which is not anchored to
+any particular time zone. In addition, floating datetimes do not
+include leap seconds, since we cannot apply them without knowing the
+datetime's time zone.
+.PP
+The results of date math and comparison between a floating datetime
+and one with a real time zone are not really valid, because one
+includes leap seconds and the other does not. Similarly, the results
+of datetime math between two floating datetimes and two datetimes with
+time zones are not really comparable.
+.PP
+If you are planning to use any objects with a real time zone, it is
+strongly recommended that you \fBdo not\fR mix these with floating
+datetimes.
+.SS "Math"
+.IX Subsection "Math"
+If you are going to be using doing date math, please read the section
+\&\*(L"How Datetime Math is Done\*(R".
+.SS "Time Zone Warnings"
+.IX Subsection "Time Zone Warnings"
+Determining the local time zone for a system can be slow. If \f(CW$ENV{TZ}\fR is
+not set, it may involve reading a number of files in \fI/etc\fR or elsewhere. If
+you know that the local time zone won't change while your code is running, and
+you need to make many objects for the local time zone, it is strongly
+recommended that you retrieve the local time zone once and cache it:
+.PP
+.Vb 1
+\& our $App::LocalTZ = DateTime::TimeZone\->new( name => \*(Aqlocal\*(Aq );
+\&
+\& ... # then everywhere else
+\&
+\& my $dt = DateTime\->new( ..., time_zone => $App::LocalTZ );
+.Ve
+.PP
+DateTime itself does not do this internally because local time zones can
+change, and there's no good way to determine if it's changed without doing all
+the work to look it up.
+.PP
+Do not try to use named time zones (like \*(L"America/Chicago\*(R") with dates
+very far in the future (thousands of years). The current
+implementation of \f(CW\*(C`DateTime::TimeZone\*(C'\fR will use a huge amount of
+memory calculating all the \s-1DST\s0 changes from now until the future
+date. Use \s-1UTC\s0 or the floating time zone and you will be safe.
+.SS "Methods"
+.IX Subsection "Methods"
+\fIConstructors\fR
+.IX Subsection "Constructors"
+.PP
+All constructors can die when invalid parameters are given.
+.IP "\(bu" 4
+DateTime\->new( ... )
+.Sp
+This class method accepts parameters for each date and time component:
+\&\*(L"year\*(R", \*(L"month\*(R", \*(L"day\*(R", \*(L"hour\*(R", \*(L"minute\*(R", \*(L"second\*(R", \*(L"nanosecond\*(R".
+It also accepts \*(L"locale\*(R", \*(L"time_zone\*(R", and \*(L"formatter\*(R" parameters.
+.Sp
+.Vb 9
+\& my $dt = DateTime\->new( year => 1066,
+\& month => 10,
+\& day => 25,
+\& hour => 7,
+\& minute => 15,
+\& second => 47,
+\& nanosecond => 500000000,
+\& time_zone => \*(AqAmerica/Chicago\*(Aq,
+\& );
+.Ve
+.Sp
+DateTime validates the \*(L"month\*(R", \*(L"day\*(R", \*(L"hour\*(R", \*(L"minute\*(R", and \*(L"second\*(R",
+and \*(L"nanosecond\*(R" parameters. The valid values for these parameters are:
+.RS 4
+.IP "\(bu" 8
+month
+.Sp
+1\-12
+.IP "\(bu" 8
+day
+.Sp
+1\-31, and it must be within the valid range of days for the specified
+month
+.IP "\(bu" 8
+hour
+.Sp
+0\-23
+.IP "\(bu" 8
+minute
+.Sp
+0\-59
+.IP "\(bu" 8
+second
+.Sp
+0\-61 (to allow for leap seconds). Values of 60 or 61 are only allowed
+when they match actual leap seconds.
+.IP "\(bu" 8
+nanosecond
+.Sp
+>= 0
+.RE
+.RS 4
+.RE
+.PP
+Invalid parameter types (like an array reference) will cause the
+constructor to die.
+.PP
+The value for seconds may be from 0 to 61, to account for leap
+seconds. If you give a value greater than 59, DateTime does check to
+see that it really matches a valid leap second.
+.PP
+All of the parameters are optional except for \*(L"year\*(R". The \*(L"month\*(R" and
+\&\*(L"day\*(R" parameters both default to 1, while the \*(L"hour\*(R", \*(L"minute\*(R",
+\&\*(L"second\*(R", and \*(L"nanosecond\*(R" parameters all default to 0.
+.PP
+The \*(L"locale\*(R" parameter should be a string matching one of the valid
+locales, or a \f(CW\*(C`DateTime::Locale\*(C'\fR object. See the
+DateTime::Locale documentation for details.
+.PP
+The time_zone parameter can be either a scalar or a
+\&\f(CW\*(C`DateTime::TimeZone\*(C'\fR object. A string will simply be passed to the
+\&\f(CW\*(C`DateTime::TimeZone\->new\*(C'\fR method as its \*(L"name\*(R" parameter. This
+string may be an Olson \s-1DB\s0 time zone name (\*(L"America/Chicago\*(R"), an
+offset string (\*(L"+0630\*(R"), or the words \*(L"floating\*(R" or \*(L"local\*(R". See the
+\&\f(CW\*(C`DateTime::TimeZone\*(C'\fR documentation for more details.
+.PP
+The default time zone is \*(L"floating\*(R".
+.PP
+The \*(L"formatter\*(R" can be either a scalar or an object, but the class
+specified by the scalar or the object must implement a
+\&\f(CW\*(C`format_datetime()\*(C'\fR method.
+.PP
+Parsing Dates
+.IX Subsection "Parsing Dates"
+.PP
+\&\fBThis module does not parse dates!\fR That means there is no
+constructor to which you can pass things like \*(L"March 3, 1970 12:34\*(R".
+.PP
+Instead, take a look at the various \f(CW\*(C`DateTime::Format::*\*(C'\fR modules on
+\&\s-1CPAN\s0. These parse all sorts of different date formats, and you're
+bound to find something that can handle your particular needs.
+.PP
+Ambiguous Local Times
+.IX Subsection "Ambiguous Local Times"
+.PP
+Because of Daylight Saving Time, it is possible to specify a local
+time that is ambiguous. For example, in the \s-1US\s0 in 2003, the
+transition from to saving to standard time occurred on October 26, at
+02:00:00 local time. The local clock changed from 01:59:59 (saving
+time) to 01:00:00 (standard time). This means that the hour from
+01:00:00 through 01:59:59 actually occurs twice, though the \s-1UTC\s0 time
+continues to move forward.
+.PP
+If you specify an ambiguous time, then the latest \s-1UTC\s0 time is always
+used, in effect always choosing standard time. In this case, you can
+simply subtract an hour to the object in order to move to saving time,
+for example:
+.PP
+.Vb 9
+\& # This object represent 01:30:00 standard time
+\& my $dt = DateTime\->new( year => 2003,
+\& month => 10,
+\& day => 26,
+\& hour => 1,
+\& minute => 30,
+\& second => 0,
+\& time_zone => \*(AqAmerica/Chicago\*(Aq,
+\& );
+\&
+\& print $dt\->hms; # prints 01:30:00
+\&
+\& # Now the object represent 01:30:00 saving time
+\& $dt\->subtract( hours => 1 );
+\&
+\& print $dt\->hms; # still prints 01:30:00
+.Ve
+.PP
+Alternately, you could create the object with the \s-1UTC\s0 time zone, and
+then call the \f(CW\*(C`set_time_zone()\*(C'\fR method to change the time zone. This
+is a good way to ensure that the time is not ambiguous.
+.PP
+Invalid Local Times
+.IX Subsection "Invalid Local Times"
+.PP
+Another problem introduced by Daylight Saving Time is that certain
+local times just do not exist. For example, in the \s-1US\s0 in 2003, the
+transition from standard to saving time occurred on April 6, at the
+change to 2:00:00 local time. The local clock changes from 01:59:59
+(standard time) to 03:00:00 (saving time). This means that there is
+no 02:00:00 through 02:59:59 on April 6!
+.PP
+Attempting to create an invalid time currently causes a fatal error.
+This may change in future version of this module.
+.IP "\(bu" 4
+DateTime\->from_epoch( epoch => \f(CW$epoch\fR, ... )
+.Sp
+This class method can be used to construct a new DateTime object from
+an epoch time instead of components. Just as with the \f(CW\*(C`new()\*(C'\fR
+method, it accepts \*(L"time_zone\*(R", \*(L"locale\*(R", and \*(L"formatter\*(R" parameters.
+.Sp
+If the epoch value is not an integer, the part after the decimal will
+be converted to nanoseconds. This is done in order to be compatible
+with \f(CW\*(C`Time::HiRes\*(C'\fR. If the floating portion extends past 9 decimal
+places, it will be truncated to nine, so that 1.1234567891 will become
+1 second and 123,456,789 nanoseconds.
+.Sp
+By default, the returned object will be in the \s-1UTC\s0 time zone.
+.IP "\(bu" 4
+DateTime\->now( ... )
+.Sp
+This class method is equivalent to calling \f(CW\*(C`from_epoch()\*(C'\fR with the
+value returned from Perl's \f(CW\*(C`time()\*(C'\fR function. Just as with the
+\&\f(CW\*(C`new()\*(C'\fR method, it accepts \*(L"time_zone\*(R" and \*(L"locale\*(R" parameters.
+.Sp
+By default, the returned object will be in the \s-1UTC\s0 time zone.
+.IP "\(bu" 4
+DateTime\->today( ... )
+.Sp
+This class method is equivalent to:
+.Sp
+.Vb 1
+\& DateTime\->now\->truncate( to => \*(Aqday\*(Aq );
+.Ve
+.IP "\(bu" 4
+DateTime\->from_object( object => \f(CW$object\fR, ... )
+.Sp
+This class method can be used to construct a new DateTime object from
+any object that implements the \f(CW\*(C`utc_rd_values()\*(C'\fR method. All
+\&\f(CW\*(C`DateTime::Calendar\*(C'\fR modules must implement this method in order to
+provide cross-calendar compatibility. This method accepts a
+\&\*(L"locale\*(R" and \*(L"formatter\*(R" parameter
+.Sp
+If the object passed to this method has a \f(CW\*(C`time_zone()\*(C'\fR method, that
+is used to set the time zone of the newly created \f(CW\*(C`DateTime.pm\*(C'\fR
+object.
+.Sp
+Otherwise, the returned object will be in the floating time zone.
+.IP "\(bu" 4
+DateTime\->last_day_of_month( ... )
+.Sp
+This constructor takes the same arguments as can be given to the
+\&\f(CW\*(C`new()\*(C'\fR method, except for \*(L"day\*(R". Additionally, both \*(L"year\*(R" and
+\&\*(L"month\*(R" are required.
+.IP "\(bu" 4
+DateTime\->from_day_of_year( ... )
+.Sp
+This constructor takes the same arguments as can be given to the
+\&\f(CW\*(C`new()\*(C'\fR method, except that it does not accept a \*(L"month\*(R" or \*(L"day\*(R"
+argument. Instead, it requires both \*(L"year\*(R" and \*(L"day_of_year\*(R". The
+day of year must be between 1 and 366, and 366 is only allowed for
+leap years.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIclone()\fR
+.Sp
+This object method returns a new object that is replica of the object
+upon which the method is called.
+.PP
+\fI\*(L"Get\*(R" Methods\fR
+.IX Subsection "Get Methods"
+.PP
+This class has many methods for retrieving information about an
+object.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIyear()\fR
+.Sp
+Returns the year.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIce_year()\fR
+.Sp
+Returns the year according to the \s-1BCE/CE\s0 numbering system. The year
+before year 1 in this system is year \-1, aka \*(L"1 \s-1BCE\s0\*(R".
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIera_name()\fR
+.Sp
+Returns the long name of the current era, something like \*(L"Before
+Christ\*(R". See the Locales section for more details.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIera_abbr()\fR
+.Sp
+Returns the abbreviated name of the current era, something like \*(L"\s-1BC\s0\*(R".
+See the Locales section for more details.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIchristian_era()\fR
+.Sp
+Returns a string, either \*(L"\s-1BC\s0\*(R" or \*(L"\s-1AD\s0\*(R", according to the year.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIsecular_era()\fR
+.Sp
+Returns a string, either \*(L"\s-1BCE\s0\*(R" or \*(L"\s-1CE\s0\*(R", according to the year.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIyear_with_era()\fR
+.Sp
+Returns a string containing the year immediately followed by its era
+abbreviation. The year is the absolute value of \f(CW\*(C`ce_year()\*(C'\fR, so that
+year 1 is \*(L"1AD\*(R" and year 0 is \*(L"1BC\*(R".
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIyear_with_christian_era()\fR
+.Sp
+Like \f(CW\*(C`year_with_era()\*(C'\fR, but uses the \fIchristian_era()\fR to get the era
+name.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIyear_with_secular_era()\fR
+.Sp
+Like \f(CW\*(C`year_with_era()\*(C'\fR, but uses the \fIsecular_era()\fR method to get the
+era name.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fImonth()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fImon()\fR
+.Sp
+Returns the month of the year, from 1..12.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fImonth_name()\fR
+.Sp
+Returns the name of the current month. See the
+Locales section for more details.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fImonth_abbr()\fR
+.Sp
+Returns the abbreviated name of the current month. See the
+Locales section for more details.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIday_of_month()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIday()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fImday()\fR
+.Sp
+Returns the day of the month, from 1..31.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIday_of_week()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIwday()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIdow()\fR
+.Sp
+Returns the day of the week as a number, from 1..7, with 1 being
+Monday and 7 being Sunday.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIlocal_day_of_week()\fR
+.Sp
+Returns the day of the week as a number, from 1..7. The day
+corresponding to 1 will vary based on the locale.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIday_name()\fR
+.Sp
+Returns the name of the current day of the week. See the
+Locales section for more details.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIday_abbr()\fR
+.Sp
+Returns the abbreviated name of the current day of the week. See the
+Locales section for more details.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIday_of_year()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIdoy()\fR
+.Sp
+Returns the day of the year.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIquarter()\fR
+.Sp
+Returns the quarter of the year, from 1..4.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIquarter_name()\fR
+.Sp
+Returns the name of the current quarter. See the
+Locales section for more details.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIquarter_abbr()\fR
+.Sp
+Returns the abbreviated name of the current quarter. See the
+Locales section for more details.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIday_of_quarter()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIdoq()\fR
+.Sp
+Returns the day of the quarter.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIweekday_of_month()\fR
+.Sp
+Returns a number from 1..5 indicating which week day of the month this
+is. For example, June 9, 2003 is the second Monday of the month, and
+so this method returns 2 for that day.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->ymd( \f(CW$optional_separator\fR ) \- also \f(CW$dt\fR\->date(...)
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->mdy( \f(CW$optional_separator\fR )
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->dmy( \f(CW$optional_separator\fR )
+.Sp
+Each method returns the year, month, and day, in the order indicated
+by the method name. Years are zero-padded to four digits. Months and
+days are 0\-padded to two digits.
+.Sp
+By default, the values are separated by a dash (\-), but this can be
+overridden by passing a value to the method.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIhour()\fR
+.Sp
+Returns the hour of the day, from 0..23.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIhour_1()\fR
+.Sp
+Returns the hour of the day, from 1..24.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIhour_12()\fR
+.Sp
+Returns the hour of the day, from 1..12.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIhour_12_0()\fR
+.Sp
+Returns the hour of the day, from 0..11.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIam_or_pm()\fR
+.Sp
+Returns the appropriate localized abbreviation, depending on the
+current hour.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIminute()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fImin()\fR
+.Sp
+Returns the minute of the hour, from 0..59.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIsecond()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIsec()\fR
+.Sp
+Returns the second, from 0..61. The values 60 and 61 are used for
+leap seconds.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIfractional_second()\fR
+.Sp
+Returns the second, as a real number from 0.0 until 61.999999999
+.Sp
+The values 60 and 61 are used for leap seconds.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fImillisecond()\fR
+.Sp
+Returns the fractional part of the second as milliseconds (1E\-3 seconds).
+.Sp
+Half a second is 500 milliseconds.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fImicrosecond()\fR
+.Sp
+Returns the fractional part of the second as microseconds (1E\-6
+seconds). This value will be rounded to an integer.
+.Sp
+Half a second is 500_000 microseconds. This value will be rounded to
+an integer.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fInanosecond()\fR
+.Sp
+Returns the fractional part of the second as nanoseconds (1E\-9 seconds).
+.Sp
+Half a second is 500_000_000 nanoseconds.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->hms( \f(CW$optional_separator\fR )
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->time( \f(CW$optional_separator\fR )
+.Sp
+Returns the hour, minute, and second, all zero-padded to two digits.
+If no separator is specified, a colon (:) is used by default.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIdatetime()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIiso8601()\fR
+.Sp
+This method is equivalent to:
+.Sp
+.Vb 1
+\& $dt\->ymd(\*(Aq\-\*(Aq) . \*(AqT\*(Aq . $dt\->hms(\*(Aq:\*(Aq)
+.Ve
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIis_leap_year()\fR
+.Sp
+This method returns a true or false indicating whether or not the
+datetime object is in a leap year.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIweek()\fR
+.Sp
+.Vb 1
+\& ($week_year, $week_number) = $dt\->week;
+.Ve
+.Sp
+Returns information about the calendar week which contains this
+datetime object. The values returned by this method are also available
+separately through the week_year and week_number methods.
+.Sp
+The first week of the year is defined by \s-1ISO\s0 as the one which contains
+the fourth day of January, which is equivalent to saying that it's the
+first week to overlap the new year by at least four days.
+.Sp
+Typically the week year will be the same as the year that the object
+is in, but dates at the very beginning of a calendar year often end up
+in the last week of the prior year, and similarly, the final few days
+of the year may be placed in the first week of the next year.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIweek_year()\fR
+.Sp
+Returns the year of the week.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIweek_number()\fR
+.Sp
+Returns the week of the year, from 1..53.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIweek_of_month()\fR
+.Sp
+The week of the month, from 0..5. The first week of the month is the
+first week that contains a Thursday. This is based on the \s-1ICU\s0
+definition of week of month, and correlates to the \s-1ISO8601\s0 week of
+year definition. A day in the week \fIbefore\fR the week with the first
+Thursday will be week 0.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIjd()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fImjd()\fR
+.Sp
+These return the Julian Day and Modified Julian Day, respectively.
+The value returned is a floating point number. The fractional portion
+of the number represents the time portion of the datetime.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fItime_zone()\fR
+.Sp
+This returns the \f(CW\*(C`DateTime::TimeZone\*(C'\fR object for the datetime object.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIoffset()\fR
+.Sp
+This returns the offset from \s-1UTC\s0, in seconds, of the datetime object
+according to the time zone.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIis_dst()\fR
+.Sp
+Returns a boolean indicating whether or not the datetime object is
+currently in Daylight Saving Time or not.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fItime_zone_long_name()\fR
+.Sp
+This is a shortcut for \f(CW\*(C`$dt\->time_zone\->name\*(C'\fR. It's provided so
+that one can use \*(L"%{time_zone_long_name}\*(R" as a strftime format
+specifier.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fItime_zone_short_name()\fR
+.Sp
+This method returns the time zone abbreviation for the current time
+zone, such as \*(L"\s-1PST\s0\*(R" or \*(L"\s-1GMT\s0\*(R". These names are \fBnot\fR definitive, and
+should not be used in any application intended for general use by
+users around the world.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->strftime( \f(CW$format\fR, ... )
+.Sp
+This method implements functionality similar to the \f(CW\*(C`strftime()\*(C'\fR
+method in C. However, if given multiple format strings, then it will
+return multiple scalars, one for each format string.
+.Sp
+See the \*(L"strftime Patterns\*(R" section for a list of all possible
+strftime patterns.
+.Sp
+If you give a pattern that doesn't exist, then it is simply treated as
+text.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->format_cldr( \f(CW$format\fR, ... )
+.Sp
+This method implements formatting based on the \s-1CLDR\s0 date patterns. If
+given multiple format strings, then it will return multiple scalars,
+one for each format string.
+.Sp
+See the \*(L"\s-1CLDR\s0 Patterns\*(R" section for a list of all possible \s-1CLDR\s0
+patterns.
+.Sp
+If you give a pattern that doesn't exist, then it is simply treated as
+text.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIepoch()\fR
+.Sp
+Return the \s-1UTC\s0 epoch value for the datetime object. Internally, this
+is implemented using \f(CW\*(C`Time::Local\*(C'\fR, which uses the Unix epoch even on
+machines with a different epoch (such as MacOS). Datetimes before the
+start of the epoch will be returned as a negative number.
+.Sp
+The return value from this method is always an integer.
+.Sp
+Since the epoch does not account for leap seconds, the epoch time for
+1972\-12\-31T23:59:60 (\s-1UTC\s0) is exactly the same as that for
+1973\-01\-01T00:00:00.
+.Sp
+This module uses \f(CW\*(C`Time::Local\*(C'\fR to calculate the epoch, which may or
+may not handle epochs before 1904 or after 2038 (depending on the size
+of your system's integers, and whether or not Perl was compiled with
+64\-bit int support).
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIhires_epoch()\fR
+.Sp
+Returns the epoch as a floating point number. The floating point
+portion of the value represents the nanosecond value of the object.
+This method is provided for compatibility with the \f(CW\*(C`Time::HiRes\*(C'\fR
+module.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIis_finite()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->is_infinite
+.Sp
+These methods allow you to distinguish normal datetime objects from
+infinite ones. Infinite datetime objects are documented in
+DateTime::Infinite.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIutc_rd_values()\fR
+.Sp
+Returns the current \s-1UTC\s0 Rata Die days, seconds, and nanoseconds as a
+three element list. This exists primarily to allow other calendar
+modules to create objects based on the values provided by this object.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIlocal_rd_values()\fR
+.Sp
+Returns the current local Rata Die days, seconds, and nanoseconds as a
+three element list. This exists for the benefit of other modules
+which might want to use this information for date math, such as
+\&\f(CW\*(C`DateTime::Event::Recurrence\*(C'\fR.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIleap_seconds()\fR
+.Sp
+Returns the number of leap seconds that have happened up to the
+datetime represented by the object. For floating datetimes, this
+always returns 0.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIutc_rd_as_seconds()\fR
+.Sp
+Returns the current \s-1UTC\s0 Rata Die days and seconds purely as seconds.
+This number ignores any fractional seconds stored in the object,
+as well as leap seconds.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIlocal_rd_as_seconds()\fR \- deprecated
+.Sp
+Returns the current local Rata Die days and seconds purely as seconds.
+This number ignores any fractional seconds stored in the object,
+as well as leap seconds.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIlocale()\fR
+.Sp
+Returns the current locale object.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIformatter()\fR
+.Sp
+Returns current formatter object or class. See \*(L"Formatters And
+Stringification\*(R" for details.
+.PP
+\fI\*(L"Set\*(R" Methods\fR
+.IX Subsection "Set Methods"
+.PP
+The remaining methods provided by \f(CW\*(C`DateTime.pm\*(C'\fR, except where otherwise
+specified, return the object itself, thus making method chaining
+possible. For example:
+.PP
+.Vb 1
+\& my $dt = DateTime\->now\->set_time_zone( \*(AqAustralia/Sydney\*(Aq );
+\&
+\& my $first = DateTime
+\& \->last_day_of_month( year => 2003, month => 3 )
+\& \->add( days => 1 )
+\& \->subtract( seconds => 1 );
+.Ve
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->set( .. )
+.Sp
+This method can be used to change the local components of a date time,
+or its locale. This method accepts any parameter allowed by the
+\&\f(CW\*(C`new()\*(C'\fR method except for \*(L"time_zone\*(R". Time zones may be set using
+the \f(CW\*(C`set_time_zone()\*(C'\fR method.
+.Sp
+This method performs parameters validation just as is done in the
+\&\f(CW\*(C`new()\*(C'\fR method.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIset_year()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIset_month()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIset_day()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIset_hour()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIset_minute()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIset_second()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIset_nanosecond()\fR
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIset_locale()\fR
+.Sp
+These are shortcuts to calling \f(CW\*(C`set()\*(C'\fR with a single key. They all
+take a single parameter.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->truncate( to => ... )
+.Sp
+This method allows you to reset some of the local time components in
+the object to their \*(L"zero\*(R" values. The \*(L"to\*(R" parameter is used to
+specify which values to truncate, and it may be one of \*(L"year\*(R",
+\&\*(L"month\*(R", \*(L"week\*(R", \*(L"day\*(R", \*(L"hour\*(R", \*(L"minute\*(R", or \*(L"second\*(R". For example,
+if \*(L"month\*(R" is specified, then the local day becomes 1, and the hour,
+minute, and second all become 0.
+.Sp
+If \*(L"week\*(R" is given, then the datetime is set to the beginning of the
+week in which it occurs, and the time components are all set to 0.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->set_time_zone( \f(CW$tz\fR )
+.Sp
+This method accepts either a time zone object or a string that can be
+passed as the \*(L"name\*(R" parameter to \f(CW\*(C`DateTime::TimeZone\->new()\*(C'\fR.
+If the new time zone's offset is different from the old time zone,
+then the \fIlocal\fR time is adjusted accordingly.
+.Sp
+For example:
+.Sp
+.Vb 3
+\& my $dt = DateTime\->new( year => 2000, month => 5, day => 10,
+\& hour => 15, minute => 15,
+\& time_zone => \*(AqAmerica/Los_Angeles\*(Aq, );
+\&
+\& print $dt\->hour; # prints 15
+\&
+\& $dt\->set_time_zone( \*(AqAmerica/Chicago\*(Aq );
+\&
+\& print $dt\->hour; # prints 17
+.Ve
+.Sp
+If the old time zone was a floating time zone, then no adjustments to
+the local time are made, except to account for leap seconds. If the
+new time zone is floating, then the \fI\s-1UTC\s0\fR time is adjusted in order
+to leave the local time untouched.
+.Sp
+Fans of Tsai Ming-Liang's films will be happy to know that this does
+work:
+.Sp
+.Vb 1
+\& my $dt = DateTime\->now( time_zone => \*(AqAsia/Taipei\*(Aq );
+\&
+\& $dt\->set_time_zone( \*(AqEurope/Paris\*(Aq );
+.Ve
+.Sp
+Yes, now we can know \*(L"ni3 na4 bian1 ji2dian3?\*(R"
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->set_formatter( \f(CW$formatter\fR )
+.Sp
+Set the formatter for the object. See \*(L"Formatters And
+Stringification\*(R" for details.
+.PP
+\fIMath Methods\fR
+.IX Subsection "Math Methods"
+.PP
+Like the set methods, math related methods always return the object
+itself, to allow for chaining:
+.PP
+.Vb 1
+\& $dt\->add( days => 1 )\->subtract( seconds => 1 );
+.Ve
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->\fIduration_class()\fR
+.Sp
+This returns \f(CW\*(C`DateTime::Duration\*(C'\fR, but exists so that a subclass of
+\&\f(CW\*(C`DateTime.pm\*(C'\fR can provide a different value.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->add_duration( \f(CW$duration_object\fR )
+.Sp
+This method adds a \f(CW\*(C`DateTime::Duration\*(C'\fR to the current datetime. See
+the DateTime::Duration docs for more details.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->add( DateTime::Duration\->new parameters )
+.Sp
+This method is syntactic sugar around the \f(CW\*(C`add_duration()\*(C'\fR method. It
+simply creates a new \f(CW\*(C`DateTime::Duration\*(C'\fR object using the parameters
+given, and then calls the \f(CW\*(C`add_duration()\*(C'\fR method.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->subtract_duration( \f(CW$duration_object\fR )
+.Sp
+When given a \f(CW\*(C`DateTime::Duration\*(C'\fR object, this method simply calls
+\&\f(CW\*(C`invert()\*(C'\fR on that object and passes that new duration to the
+\&\f(CW\*(C`add_duration\*(C'\fR method.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->subtract( DateTime::Duration\->new parameters )
+.Sp
+Like \f(CW\*(C`add()\*(C'\fR, this is syntactic sugar for the \f(CW\*(C`subtract_duration()\*(C'\fR
+method.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->subtract_datetime( \f(CW$datetime\fR )
+.Sp
+This method returns a new \f(CW\*(C`DateTime::Duration\*(C'\fR object representing
+the difference between the two dates. The duration is \fBrelative\fR to
+the object from which \f(CW$datetime\fR is subtracted. For example:
+.Sp
+.Vb 2
+\& 2003\-03\-15 00:00:00.00000000
+\& \- 2003\-02\-15 00:00:00.00000000
+\&
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&
+\& = 1 month
+.Ve
+.Sp
+Note that this duration is not an absolute measure of the amount of
+time between the two datetimes, because the length of a month varies,
+as well as due to the presence of leap seconds.
+.Sp
+The returned duration may have deltas for months, days, minutes,
+seconds, and nanoseconds.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->delta_md( \f(CW$datetime\fR )
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->delta_days( \f(CW$datetime\fR )
+.Sp
+Each of these methods returns a new \f(CW\*(C`DateTime::Duration\*(C'\fR object
+representing some portion of the difference between two datetimes.
+The \f(CW\*(C`delta_md()\*(C'\fR method returns a duration which contains only the
+month and day portions of the duration is represented. The
+\&\f(CW\*(C`delta_days()\*(C'\fR method returns a duration which contains only days.
+.Sp
+The \f(CW\*(C`delta_md\*(C'\fR and \f(CW\*(C`delta_days\*(C'\fR methods truncate the duration so
+that any fractional portion of a day is ignored. Both of these
+methods operate on the date portion of a datetime only, and so
+effectively ignore the time zone.
+.Sp
+Unlike the subtraction methods, \fBthese methods always return a
+positive (or zero) duration\fR.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->delta_ms( \f(CW$datetime\fR )
+.Sp
+Returns a duration which contains only minutes and seconds. Any day
+and month differences to minutes are converted to minutes and
+seconds. This method also \fBalways return a positive (or zero)
+duration\fR.
+.IP "\(bu" 4
+\&\f(CW$dt\fR\->subtract_datetime_absolute( \f(CW$datetime\fR )
+.Sp
+This method returns a new \f(CW\*(C`DateTime::Duration\*(C'\fR object representing
+the difference between the two dates in seconds and nanoseconds. This
+is the only way to accurately measure the absolute amount of time
+between two datetimes, since units larger than a second do not
+represent a fixed number of seconds.
+.PP
+\fIClass Methods\fR
+.IX Subsection "Class Methods"
+.IP "\(bu" 4
+DateTime\->DefaultLocale( \f(CW$locale\fR )
+.Sp
+This can be used to specify the default locale to be used when
+creating DateTime objects. If unset, then \*(L"en_US\*(R" is used.
+.IP "\(bu" 4
+DateTime\->compare( \f(CW$dt1\fR, \f(CW$dt2\fR )
+.IP "\(bu" 4
+DateTime\->compare_ignore_floating( \f(CW$dt1\fR, \f(CW$dt2\fR )
+.Sp
+.Vb 1
+\& $cmp = DateTime\->compare( $dt1, $dt2 );
+\&
+\& $cmp = DateTime\->compare_ignore_floating( $dt1, $dt2 );
+.Ve
+.Sp
+Compare two DateTime objects. The semantics are compatible with Perl's
+\&\f(CW\*(C`sort()\*(C'\fR function; it returns \-1 if \f(CW$dt1\fR < \f(CW$dt2\fR, 0 if \f(CW$dt1\fR == \f(CW$dt2\fR, 1 if \f(CW$dt1\fR
+> \f(CW$dt2\fR.
+.Sp
+If one of the two DateTime objects has a floating time zone, it will
+first be converted to the time zone of the other object. This is what
+you want most of the time, but it can lead to inconsistent results
+when you compare a number of DateTime objects, some of which are
+floating, and some of which are in other time zones.
+.Sp
+If you want to have consistent results (because you want to sort a
+number of objects, for example), you can use the
+\&\f(CW\*(C`compare_ignore_floating()\*(C'\fR method:
+.Sp
+.Vb 1
+\& @dates = sort { DateTime\->compare_ignore_floating($a, $b) } @dates;
+.Ve
+.Sp
+In this case, objects with a floating time zone will be sorted as if
+they were \s-1UTC\s0 times.
+.Sp
+Since DateTime objects overload comparison operators, this:
+.Sp
+.Vb 1
+\& @dates = sort @dates;
+.Ve
+.Sp
+is equivalent to this:
+.Sp
+.Vb 1
+\& @dates = sort { DateTime\->compare($a, $b) } @dates;
+.Ve
+.Sp
+DateTime objects can be compared to any other calendar class that
+implements the \f(CW\*(C`utc_rd_values()\*(C'\fR method.
+.SS "How Datetime Math is Done"
+.IX Subsection "How Datetime Math is Done"
+It's important to have some understanding of how datetime math is
+implemented in order to effectively use this module and
+\&\f(CW\*(C`DateTime::Duration\*(C'\fR.
+.PP
+\fIMaking Things Simple\fR
+.IX Subsection "Making Things Simple"
+.PP
+If you want to simplify your life and not have to think too hard about
+the nitty-gritty of datetime math, I have several recommendations:
+.IP "\(bu" 4
+use the floating time zone
+.Sp
+If you do not care about time zones or leap seconds, use the
+\&\*(L"floating\*(R" timezone:
+.Sp
+.Vb 1
+\& my $dt = DateTime\->now( time_zone => \*(Aqfloating\*(Aq );
+.Ve
+.Sp
+Math done on two objects in the floating time zone produces very
+predictable results.
+.IP "\(bu" 4
+use \s-1UTC\s0 for all calculations
+.Sp
+If you do care about time zones (particularly \s-1DST\s0) or leap seconds,
+try to use non-UTC time zones for presentation and user input only.
+Convert to \s-1UTC\s0 immediately and convert back to the local time zone for
+presentation:
+.Sp
+.Vb 2
+\& my $dt = DateTime\->new( %user_input, time_zone => $user_tz );
+\& $dt\->set_time_zone(\*(AqUTC\*(Aq);
+\&
+\& # do various operations \- store it, retrieve it, add, subtract, etc.
+\&
+\& $dt\->set_time_zone($user_tz);
+\& print $dt\->datetime;
+.Ve
+.IP "\(bu" 4
+math on non-UTC time zones
+.Sp
+If you need to do date math on objects with non-UTC time zones, please
+read the caveats below carefully. The results \f(CW\*(C`DateTime.pm\*(C'\fR produces are
+predictable and correct, and mostly intuitive, but datetime math gets
+very ugly when time zones are involved, and there are a few strange
+corner cases involving subtraction of two datetimes across a \s-1DST\s0
+change.
+.Sp
+If you can always use the floating or \s-1UTC\s0 time zones, you can skip
+ahead to Leap Seconds and Date Math
+.IP "\(bu" 4
+date vs datetime math
+.Sp
+If you only care about the date (calendar) portion of a datetime, you
+should use either \f(CW\*(C`delta_md()\*(C'\fR or \f(CW\*(C`delta_days()\*(C'\fR, not
+\&\f(CW\*(C`subtract_datetime()\*(C'\fR. This will give predictable, unsurprising
+results, free from DST-related complications.
+.IP "\(bu" 4
+\&\fIsubtract_datetime()\fR and \fIadd_duration()\fR
+.Sp
+You must convert your datetime objects to the \s-1UTC\s0 time zone before
+doing date math if you want to make sure that the following formulas
+are always true:
+.Sp
+.Vb 3
+\& $dt2 \- $dt1 = $dur
+\& $dt1 + $dur = $dt2
+\& $dt2 \- $dur = $dt1
+.Ve
+.Sp
+Note that using \f(CW\*(C`delta_days\*(C'\fR ensures that this formula always works,
+regardless of the timezone of the objects involved, as does using
+\&\f(CW\*(C`subtract_datetime_absolute()\*(C'\fR. Other methods of subtraction are not
+always reversible.
+.PP
+\fIAdding a Duration to a Datetime\fR
+.IX Subsection "Adding a Duration to a Datetime"
+.PP
+The parts of a duration can be broken down into five parts. These are
+months, days, minutes, seconds, and nanoseconds. Adding one month to
+a date is different than adding 4 weeks or 28, 29, 30, or 31 days.
+Similarly, due to \s-1DST\s0 and leap seconds, adding a day can be different
+than adding 86,400 seconds, and adding a minute is not exactly the
+same as 60 seconds.
+.PP
+We cannot convert between these units, except for seconds and
+nanoseconds, because there is no fixed conversion between the two
+units, because of things like leap seconds, \s-1DST\s0 changes, etc.
+.PP
+\&\f(CW\*(C`DateTime.pm\*(C'\fR always adds (or subtracts) days, then months, minutes, and then
+seconds and nanoseconds. If there are any boundary overflows, these are
+normalized at each step. For the days and months the local (not \s-1UTC\s0) values
+are used. For minutes and seconds, the local values are used. This generally
+just works.
+.PP
+This means that adding one month and one day to February 28, 2003 will
+produce the date April 1, 2003, not March 29, 2003.
+.PP
+.Vb 1
+\& my $dt = DateTime\->new( year => 2003, month => 2, day => 28 );
+\&
+\& $dt\->add( months => 1, days => 1 );
+\&
+\& # 2003\-04\-01 \- the result
+.Ve
+.PP
+On the other hand, if we add months first, and then separately add
+days, we end up with March 29, 2003:
+.PP
+.Vb 1
+\& $dt\->add( months => 1 )\->add( days => 1 );
+\&
+\& # 2003\-03\-29
+.Ve
+.PP
+We see similar strangeness when math crosses a \s-1DST\s0 boundary:
+.PP
+.Vb 4
+\& my $dt = DateTime\->new( year => 2003, month => 4, day => 5,
+\& hour => 1, minute => 58,
+\& time_zone => "America/Chicago",
+\& );
+\&
+\& $dt\->add( days => 1, minutes => 3 );
+\& # 2003\-04\-06 02:01:00
+\&
+\& $dt\->add( minutes => 3 )\->add( days => 1 );
+\& # 2003\-04\-06 03:01:00
+.Ve
+.PP
+Note that if you converted the datetime object to \s-1UTC\s0 first you would
+get predictable results.
+.PP
+If you want to know how many seconds a duration object represents, you
+have to add it to a datetime to find out, so you could do:
+.PP
+.Vb 2
+\& my $now = DateTime\->now( time_zone => \*(AqUTC\*(Aq );
+\& my $later = $now\->clone\->add_duration($duration);
+\&
+\& my $seconds_dur = $later\->subtract_datetime_absolute($now);
+.Ve
+.PP
+This returns a duration which only contains seconds and nanoseconds.
+.PP
+If we were add the duration to a different datetime object we might
+get a different number of seconds.
+.PP
+If you need to do lots of work with durations, take a look at Rick
+Measham's \f(CW\*(C`DateTime::Format::Duration\*(C'\fR module, which lets you present
+information from durations in many useful ways.
+.PP
+There are other subtract/delta methods in DateTime.pm to generate
+different types of durations. These methods are
+\&\f(CW\*(C`subtract_datetime()\*(C'\fR, \f(CW\*(C`subtract_datetime_absolute()\*(C'\fR,
+\&\f(CW\*(C`delta_md()\*(C'\fR, \f(CW\*(C`delta_days()\*(C'\fR, and \f(CW\*(C`delta_ms()\*(C'\fR.
+.PP
+\fIDatetime Subtraction\fR
+.IX Subsection "Datetime Subtraction"
+.PP
+Date subtraction is done solely based on the two object's local
+datetimes, with one exception to handle \s-1DST\s0 changes. Also, if the two
+datetime objects are in different time zones, one of them is converted
+to the other's time zone first before subtraction. This is best
+explained through examples:
+.PP
+The first of these probably makes the most sense:
+.PP
+.Vb 4
+\& my $dt1 = DateTime\->new( year => 2003, month => 5, day => 6,
+\& time_zone => \*(AqAmerica/Chicago\*(Aq,
+\& );
+\& # not DST
+\&
+\& my $dt2 = DateTime\->new( year => 2003, month => 11, day => 6,
+\& time_zone => \*(AqAmerica/Chicago\*(Aq,
+\& );
+\& # is DST
+\&
+\& my $dur = $dt2\->subtract_datetime($dt1);
+\& # 6 months
+.Ve
+.PP
+Nice and simple.
+.PP
+This one is a little trickier, but still fairly logical:
+.PP
+.Vb 5
+\& my $dt1 = DateTime\->new( year => 2003, month => 4, day => 5,
+\& hour => 1, minute => 58,
+\& time_zone => "America/Chicago",
+\& );
+\& # is DST
+\&
+\& my $dt2 = DateTime\->new( year => 2003, month => 4, day => 7,
+\& hour => 2, minute => 1,
+\& time_zone => "America/Chicago",
+\& );
+\& # not DST
+\&
+\& my $dur = $dt2\->subtract_datetime($dt1);
+\& # 2 days and 3 minutes
+.Ve
+.PP
+Which contradicts the result this one gives, even though they both
+make sense:
+.PP
+.Vb 5
+\& my $dt1 = DateTime\->new( year => 2003, month => 4, day => 5,
+\& hour => 1, minute => 58,
+\& time_zone => "America/Chicago",
+\& );
+\& # is DST
+\&
+\& my $dt2 = DateTime\->new( year => 2003, month => 4, day => 6,
+\& hour => 3, minute => 1,
+\& time_zone => "America/Chicago",
+\& );
+\& # not DST
+\&
+\& my $dur = $dt2\->subtract_datetime($dt1);
+\& # 1 day and 3 minutes
+.Ve
+.PP
+This last example illustrates the \*(L"\s-1DST\s0\*(R" exception mentioned earlier.
+The exception accounts for the fact 2003\-04\-06 only lasts 23 hours.
+.PP
+And finally:
+.PP
+.Vb 4
+\& my $dt2 = DateTime\->new( year => 2003, month => 10, day => 26,
+\& hour => 1,
+\& time_zone => \*(AqAmerica/Chicago\*(Aq,
+\& );
+\&
+\& my $dt1 = $dt2\->clone\->subtract( hours => 1 );
+\&
+\& my $dur = $dt2\->subtract_datetime($dt1);
+\& # 60 minutes
+.Ve
+.PP
+This seems obvious until you realize that subtracting 60 minutes from
+\&\f(CW$dt2\fR in the above example still leaves the clock time at
+\&\*(L"01:00:00\*(R". This time we are accounting for a 25 hour day.
+.PP
+\fIReversibility\fR
+.IX Subsection "Reversibility"
+.PP
+Date math operations are not always reversible. This is because of
+the way that addition operations are ordered. As was discussed
+earlier, adding 1 day and 3 minutes in one call to \f(CW\*(C`add()\*(C'\fR is not the
+same as first adding 3 minutes and 1 day in two separate calls.
+.PP
+If we take a duration returned from \f(CW\*(C`subtract_datetime()\*(C'\fR and then
+try to add or subtract that duration from one of the datetimes we just
+used, we sometimes get interesting results:
+.PP
+.Vb 4
+\& my $dt1 = DateTime\->new( year => 2003, month => 4, day => 5,
+\& hour => 1, minute => 58,
+\& time_zone => "America/Chicago",
+\& );
+\&
+\& my $dt2 = DateTime\->new( year => 2003, month => 4, day => 6,
+\& hour => 3, minute => 1,
+\& time_zone => "America/Chicago",
+\& );
+\&
+\& my $dur = $dt2\->subtract_datetime($dt1);
+\& # 1 day and 3 minutes
+\&
+\& $dt1\->add_duration($dur);
+\& # gives us $dt2
+\&
+\& $dt2\->subtract_duration($dur);
+\& # gives us 2003\-04\-05 02:58:00 \- 1 hour later than $dt1
+.Ve
+.PP
+The \f(CW\*(C`subtract_dauration()\*(C'\fR operation gives us a (perhaps) unexpected
+answer because it first subtracts one day to get 2003\-04\-05T03:01:00
+and then subtracts 3 minutes to get the final result.
+.PP
+If we explicitly reverse the order we can get the original value of
+\&\f(CW$dt1\fR. This can be facilitated by \f(CW\*(C`DateTime::Duration\*(C'\fR's
+\&\f(CW\*(C`calendar_duration()\*(C'\fR and \f(CW\*(C`clock_duration()\*(C'\fR methods:
+.PP
+.Vb 2
+\& $dt2\->subtract_duration( $dur\->clock_duration )
+\& \->subtract_duration( $dur\->calendar_duration );
+.Ve
+.PP
+\fILeap Seconds and Date Math\fR
+.IX Subsection "Leap Seconds and Date Math"
+.PP
+The presence of leap seconds can cause even more anomalies in date
+math. For example, the following is a legal datetime:
+.PP
+.Vb 3
+\& my $dt = DateTime\->new( year => 1972, month => 12, day => 31,
+\& hour => 23, minute => 59, second => 60,
+\& time_zone => \*(AqUTC\*(Aq );
+.Ve
+.PP
+If we do the following:
+.PP
+.Vb 1
+\& $dt\->add( months => 1 );
+.Ve
+.PP
+Then the datetime is now \*(L"1973\-02\-01 00:00:00\*(R", because there is no
+23:59:60 on 1973\-01\-31.
+.PP
+Leap seconds also force us to distinguish between minutes and seconds
+during date math. Given the following datetime:
+.PP
+.Vb 3
+\& my $dt = DateTime\->new( year => 1972, month => 12, day => 31,
+\& hour => 23, minute => 59, second => 30,
+\& time_zone => \*(AqUTC\*(Aq );
+.Ve
+.PP
+we will get different results when adding 1 minute than we get if we
+add 60 seconds. This is because in this case, the last minute of the
+day, beginning at 23:59:00, actually contains 61 seconds.
+.PP
+Here are the results we get:
+.PP
+.Vb 1
+\& # 1972\-12\-31 23:59:30 \- our starting datetime
+\&
+\& $dt\->clone\->add( minutes => 1 );
+\& # 1973\-01\-01 00:00:30 \- one minute later
+\&
+\& $dt\->clone\->add( seconds => 60 );
+\& # 1973\-01\-01 00:00:29 \- 60 seconds later
+\&
+\& $dt\->clone\->add( seconds => 61 );
+\& # 1973\-01\-01 00:00:30 \- 61 seconds later
+.Ve
+.PP
+\fILocal vs. \s-1UTC\s0 and 24 hours vs. 1 day\fR
+.IX Subsection "Local vs. UTC and 24 hours vs. 1 day"
+.PP
+When math crosses a daylight saving boundary, a single day may have
+more or less than 24 hours.
+.PP
+For example, if you do this:
+.PP
+.Vb 5
+\& my $dt = DateTime\->new( year => 2003, month => 4, day => 5,
+\& hour => 2,
+\& time_zone => \*(AqAmerica/Chicago\*(Aq,
+\& );
+\& $dt\->add( days => 1 );
+.Ve
+.PP
+then you will produce an \fIinvalid\fR local time, and therefore an
+exception will be thrown.
+.PP
+However, this works:
+.PP
+.Vb 5
+\& my $dt = DateTime\->new( year => 2003, month => 4, day => 5,
+\& hour => 2,
+\& time_zone => \*(AqAmerica/Chicago\*(Aq,
+\& );
+\& $dt\->add( hours => 24 );
+.Ve
+.PP
+and produces a datetime with the local time of \*(L"03:00\*(R".
+.PP
+If all this makes your head hurt, there is a simple alternative. Just
+convert your datetime object to the \*(L"\s-1UTC\s0\*(R" time zone before doing date
+math on it, and switch it back to the local time zone afterwards.
+This avoids the possibility of having date math throw an exception,
+and makes sure that 1 day equals 24 hours. Of course, this may not
+always be desirable, so caveat user!
+.SS "Overloading"
+.IX Subsection "Overloading"
+This module explicitly overloads the addition (+), subtraction (\-),
+string and numeric comparison operators. This means that the
+following all do sensible things:
+.PP
+.Vb 1
+\& my $new_dt = $dt + $duration_obj;
+\&
+\& my $new_dt = $dt \- $duration_obj;
+\&
+\& my $duration_obj = $dt \- $new_dt;
+\&
+\& foreach my $dt ( sort @dts ) { ... }
+.Ve
+.PP
+Additionally, the fallback parameter is set to true, so other
+derivable operators (+=, \-=, etc.) will work properly. Do not expect
+increment (++) or decrement (\-\-) to do anything useful.
+.PP
+If you attempt to sort DateTime objects with non\-DateTime.pm objects
+or scalars (strings, number, whatever) then an exception will be
+thrown. Using the string comparison operators, \f(CW\*(C`eq\*(C'\fR or \f(CW\*(C`ne\*(C'\fR, to
+compare a DateTime.pm always returns false.
+.PP
+The module also overloads stringification to use the \f(CW\*(C`iso8601()\*(C'\fR
+method.
+.SS "Formatters And Stringification"
+.IX Subsection "Formatters And Stringification"
+You can optionally specify a \*(L"formatter\*(R", which is usually a
+DateTime::Format::* object/class, to control the stringification of
+the DateTime object.
+.PP
+Any of the constructor methods can accept a formatter argument:
+.PP
+.Vb 2
+\& my $formatter = DateTime::Format::Strptime\->new(...);
+\& my $dt = DateTime\->new(year => 2004, formatter => $formatter);
+.Ve
+.PP
+Or, you can set it afterwards:
+.PP
+.Vb 2
+\& $dt\->set_formatter($formatter);
+\& $formatter = $dt\->formatter();
+.Ve
+.PP
+Once you set the formatter, the overloaded stringification method will
+use the formatter. If unspecified, the \f(CW\*(C`iso8601()\*(C'\fR method is used.
+.PP
+A formatter can be handy when you know that in your application you
+want to stringify your DateTime objects into a special format all the
+time, for example to a different language.
+.PP
+If you provide a formatter class name or object, it must implement a
+\&\f(CW\*(C`format_datetime\*(C'\fR method. This method will be called with just the
+DateTime object as its argument.
+.SS "strftime Patterns"
+.IX Subsection "strftime Patterns"
+The following patterns are allowed in the format string given to the
+\&\f(CW\*(C`$dt\->strftime()\*(C'\fR method:
+.IP "\(bu" 4
+\&\f(CW%a\fR
+.Sp
+The abbreviated weekday name.
+.IP "\(bu" 4
+\&\f(CW%A\fR
+.Sp
+The full weekday name.
+.IP "\(bu" 4
+\&\f(CW%b\fR
+.Sp
+The abbreviated month name.
+.IP "\(bu" 4
+\&\f(CW%B\fR
+.Sp
+The full month name.
+.IP "\(bu" 4
+\&\f(CW%c\fR
+.Sp
+The default datetime format for the object's locale.
+.IP "\(bu" 4
+\&\f(CW%C\fR
+.Sp
+The century number (year/100) as a 2\-digit integer.
+.IP "\(bu" 4
+\&\f(CW%d\fR
+.Sp
+The day of the month as a decimal number (range 01 to 31).
+.IP "\(bu" 4
+\&\f(CW%D\fR
+.Sp
+Equivalent to \f(CW%m\fR/%d/%y. This is not a good standard format if you
+want folks from both the United States and the rest of the world to
+understand the date!
+.IP "\(bu" 4
+\&\f(CW%e\fR
+.Sp
+Like \f(CW%d\fR, the day of the month as a decimal number, but a leading zero
+is replaced by a space.
+.IP "\(bu" 4
+\&\f(CW%F\fR
+.Sp
+Equivalent to \f(CW%Y\fR\-%m\-%d (the \s-1ISO\s0 8601 date format)
+.IP "\(bu" 4
+\&\f(CW%G\fR
+.Sp
+The \s-1ISO\s0 8601 year with century as a decimal number. The 4\-digit year
+corresponding to the \s-1ISO\s0 week number (see \f(CW%V\fR). This has the same
+format and value as \f(CW%Y\fR, except that if the \s-1ISO\s0 week number belongs to
+the previous or next year, that year is used instead. (\s-1TZ\s0)
+.IP "\(bu" 4
+\&\f(CW%g\fR
+.Sp
+Like \f(CW%G\fR, but without century, i.e., with a 2\-digit year (00\-99).
+.IP "\(bu" 4
+\&\f(CW%h\fR
+.Sp
+Equivalent to \f(CW%b\fR.
+.IP "\(bu" 4
+\&\f(CW%H\fR
+.Sp
+The hour as a decimal number using a 24\-hour clock (range 00 to 23).
+.IP "\(bu" 4
+\&\f(CW%I\fR
+.Sp
+The hour as a decimal number using a 12\-hour clock (range 01 to 12).
+.IP "\(bu" 4
+\&\f(CW%j\fR
+.Sp
+The day of the year as a decimal number (range 001 to 366).
+.IP "\(bu" 4
+\&\f(CW%k\fR
+.Sp
+The hour (24\-hour clock) as a decimal number (range 0 to 23); single
+digits are preceded by a blank. (See also \f(CW%H\fR.)
+.IP "\(bu" 4
+\&\f(CW%l\fR
+.Sp
+The hour (12\-hour clock) as a decimal number (range 1 to 12); single
+digits are preceded by a blank. (See also \f(CW%I\fR.)
+.IP "\(bu" 4
+\&\f(CW%m\fR
+.Sp
+The month as a decimal number (range 01 to 12).
+.IP "\(bu" 4
+\&\f(CW%M\fR
+.Sp
+The minute as a decimal number (range 00 to 59).
+.IP "\(bu" 4
+\&\f(CW%n\fR
+.Sp
+A newline character.
+.IP "\(bu" 4
+\&\f(CW%N\fR
+.Sp
+The fractional seconds digits. Default is 9 digits (nanoseconds).
+.Sp
+.Vb 3
+\& %3N milliseconds (3 digits)
+\& %6N microseconds (6 digits)
+\& %9N nanoseconds (9 digits)
+.Ve
+.IP "\(bu" 4
+\&\f(CW%p\fR
+.Sp
+Either `\s-1AM\s0' or `\s-1PM\s0' according to the given time value, or the
+corresponding strings for the current locale. Noon is treated as `pm'
+and midnight as `am'.
+.IP "\(bu" 4
+\&\f(CW%P\fR
+.Sp
+Like \f(CW%p\fR but in lowercase: `am' or `pm' or a corresponding string for
+the current locale.
+.IP "\(bu" 4
+\&\f(CW%r\fR
+.Sp
+The time in a.m. or p.m. notation. In the \s-1POSIX\s0 locale this is
+equivalent to `%I:%M:%S \f(CW%p\fR'.
+.IP "\(bu" 4
+\&\f(CW%R\fR
+.Sp
+The time in 24\-hour notation (%H:%M). (\s-1SU\s0) For a version including the
+seconds, see \f(CW%T\fR below.
+.IP "\(bu" 4
+\&\f(CW%s\fR
+.Sp
+The number of seconds since the epoch.
+.IP "\(bu" 4
+\&\f(CW%S\fR
+.Sp
+The second as a decimal number (range 00 to 61).
+.IP "\(bu" 4
+\&\f(CW%t\fR
+.Sp
+A tab character.
+.IP "\(bu" 4
+\&\f(CW%T\fR
+.Sp
+The time in 24\-hour notation (%H:%M:%S).
+.IP "\(bu" 4
+\&\f(CW%u\fR
+.Sp
+The day of the week as a decimal, range 1 to 7, Monday being 1. See
+also \f(CW%w\fR.
+.IP "\(bu" 4
+\&\f(CW%U\fR
+.Sp
+The week number of the current year as a decimal number, range 00 to
+53, starting with the first Sunday as the first day of week 01. See
+also \f(CW%V\fR and \f(CW%W\fR.
+.IP "\(bu" 4
+\&\f(CW%V\fR
+.Sp
+The \s-1ISO\s0 8601:1988 week number of the current year as a decimal number,
+range 01 to 53, where week 1 is the first week that has at least 4
+days in the current year, and with Monday as the first day of the
+week. See also \f(CW%U\fR and \f(CW%W\fR.
+.IP "\(bu" 4
+\&\f(CW%w\fR
+.Sp
+The day of the week as a decimal, range 0 to 6, Sunday being 0. See
+also \f(CW%u\fR.
+.IP "\(bu" 4
+\&\f(CW%W\fR
+.Sp
+The week number of the current year as a decimal number, range 00 to
+53, starting with the first Monday as the first day of week 01.
+.IP "\(bu" 4
+\&\f(CW%x\fR
+.Sp
+The default date format for the object's locale.
+.IP "\(bu" 4
+\&\f(CW%X\fR
+.Sp
+The default time format for the object's locale.
+.IP "\(bu" 4
+\&\f(CW%y\fR
+.Sp
+The year as a decimal number without a century (range 00 to 99).
+.IP "\(bu" 4
+\&\f(CW%Y\fR
+.Sp
+The year as a decimal number including the century.
+.IP "\(bu" 4
+\&\f(CW%z\fR
+.Sp
+The time-zone as hour offset from \s-1UTC\s0. Required to emit
+RFC822\-conformant dates (using \*(L"%a, \f(CW%d\fR \f(CW%b\fR \f(CW%Y\fR \f(CW%H:\fR%M:%S \f(CW%z\fR\*(R").
+.IP "\(bu" 4
+\&\f(CW%Z\fR
+.Sp
+The time zone or name or abbreviation.
+.IP "\(bu" 4
+%%
+.Sp
+A literal `%' character.
+.IP "\(bu" 4
+%{method}
+.Sp
+Any method name may be specified using the format \f(CW\*(C`%{method}\*(C'\fR name
+where \*(L"method\*(R" is a valid \f(CW\*(C`DateTime.pm\*(C'\fR object method.
+.SS "\s-1CLDR\s0 Patterns"
+.IX Subsection "CLDR Patterns"
+The \s-1CLDR\s0 pattern language is both more powerful and more complex than
+strftime. Unlike strftime patterns, you often have to explicitly
+escape text that you do not want formatted, as the patterns are simply
+letters without any prefix.
+.PP
+For example, \*(L"yyyy-MM-dd\*(R" is a valid \s-1CLDR\s0 pattern. If you want to
+include any lower or upper case \s-1ASCII\s0 characters as-is, you can
+surround them with single quotes ('). If you want to include a single
+quote, you must escape it as two single quotes ('').
+.PP
+.Vb 2
+\& \*(AqToday is \*(Aq EEEE
+\& \*(AqIt is now\*(Aq h \*(Aqo\*(Aq\*(Aqclock\*(Aq a
+.Ve
+.PP
+Spaces and any non-letter text will always be passed through as-is.
+.PP
+Many \s-1CLDR\s0 patterns which produce numbers will pad the number with
+leading zeroes depending on the length of the format specifier. For
+example, \*(L"h\*(R" represents the current hour from 1\-12. If you specify
+\&\*(L"hh\*(R" then the 1\-9 will have a leading zero prepended.
+.PP
+However, \s-1CLDR\s0 often uses five of a letter to represent the narrow form
+of a pattern. This inconsistency is necessary for backwards
+compatibility.
+.PP
+\&\s-1CLDR\s0 often distinguishes between the \*(L"format\*(R" and \*(L"stand-alone\*(R" forms
+of a pattern. The format pattern is used when the thing in question is
+being placed into a larger string. The stand-alone form is used when
+displaying that item by itself, for example in a calendar.
+.PP
+It also often provides three sizes for each item, wide (the full
+name), abbreviated, and narrow. The narrow form is often just a single
+character, for example \*(L"T\*(R" for \*(L"Tuesday\*(R", and may not be unique.
+.PP
+\&\s-1CLDR\s0 provides a fairly complex system for localizing time zones that
+we ignore entirely. The time zone patterns just use the information
+provided by \f(CW\*(C`DateTime::TimeZone\*(C'\fR, and \fIdo not follow the \s-1CLDR\s0 spec\fR.
+.PP
+The output of a \s-1CLDR\s0 pattern is always localized, when applicable.
+.PP
+\&\s-1CLDR\s0 provides the following patterns:
+.IP "\(bu" 4
+G{1,3}
+.Sp
+The abbreviated era (\s-1BC\s0, \s-1AD\s0).
+.IP "\(bu" 4
+\&\s-1GGGG\s0
+.Sp
+The wide era (Before Christ, Anno Domini).
+.IP "\(bu" 4
+\&\s-1GGGGG\s0
+.Sp
+The narrow era, if it exists (and it mostly doesn't).
+.IP "\(bu" 4
+y and y{3,}
+.Sp
+The year, zero-prefixed as needed. Negative years will start with a \*(L"\-\*(R",
+and this will be included in the length calculation.
+.Sp
+In other, words the \*(L"yyyyy\*(R" pattern will format year \-1234 as \*(L"\-1234\*(R", not
+\&\*(L"\-01234\*(R".
+.IP "\(bu" 4
+yy
+.Sp
+This is a special case. It always produces a two-digit year, so \*(L"1976\*(R" becomes
+\&\*(L"76\*(R". Negative years will start with a \*(L"\-\*(R", making them one character longer.
+.IP "\(bu" 4
+Y{1,}
+.Sp
+The week of the year, from \f(CW\*(C`$dt\->week_year()\*(C'\fR.
+.IP "\(bu" 4
+u{1,}
+.Sp
+Same as \*(L"y\*(R" except that \*(L"uu\*(R" is not a special case.
+.IP "\(bu" 4
+Q{1,2}
+.Sp
+The quarter as a number (1..4).
+.IP "\(bu" 4
+\&\s-1QQQ\s0
+.Sp
+The abbreviated format form for the quarter.
+.IP "\(bu" 4
+\&\s-1QQQQ\s0
+.Sp
+The wide format form for the quarter.
+.IP "\(bu" 4
+q{1,2}
+.Sp
+The quarter as a number (1..4).
+.IP "\(bu" 4
+qqq
+.Sp
+The abbreviated stand-alone form for the quarter.
+.IP "\(bu" 4
+qqqq
+.Sp
+The wide stand-alone form for the quarter.
+.IP "\(bu" 4
+M{1,2]
+.Sp
+The numerical month.
+.IP "\(bu" 4
+\&\s-1MMM\s0
+.Sp
+The abbreviated format form for the month.
+.IP "\(bu" 4
+\&\s-1MMMM\s0
+.Sp
+The wide format form for the month.
+.IP "\(bu" 4
+\&\s-1MMMMM\s0
+.Sp
+The narrow format form for the month.
+.IP "\(bu" 4
+L{1,2]
+.Sp
+The numerical month.
+.IP "\(bu" 4
+\&\s-1LLL\s0
+.Sp
+The abbreviated stand-alone form for the month.
+.IP "\(bu" 4
+\&\s-1LLLL\s0
+.Sp
+The wide stand-alone form for the month.
+.IP "\(bu" 4
+\&\s-1LLLLL\s0
+.Sp
+The narrow stand-alone form for the month.
+.IP "\(bu" 4
+w{1,2}
+.Sp
+The week of the year, from \f(CW\*(C`$dt\->week_number()\*(C'\fR.
+.IP "\(bu" 4
+W
+.Sp
+The week of the month, from \f(CW\*(C`$dt\->week_of_month()\*(C'\fR.
+.IP "\(bu" 4
+d{1,2}
+.Sp
+The numeric day of of the month.
+.IP "\(bu" 4
+D{1,3}
+.Sp
+The numeric day of of the year.
+.IP "\(bu" 4
+F
+.Sp
+The day of the week in the month, from \f(CW\*(C`$dt\->weekday_of_month()\*(C'\fR.
+.IP "\(bu" 4
+g{1,}
+.Sp
+The modified Julian day, from \f(CW\*(C`$dt\->mjd()\*(C'\fR.
+.IP "\(bu" 4
+E{1,3} and eee
+.Sp
+The abbreviated format form for the day of the week.
+.IP "\(bu" 4
+\&\s-1EEEE\s0 and eeee
+.Sp
+The wide format form for the day of the week.
+.IP "\(bu" 4
+\&\s-1EEEEE\s0 and eeeee
+.Sp
+The narrow format form for the day of the week.
+.IP "\(bu" 4
+e{1,2}
+.Sp
+The \fIlocal\fR numeric day of the week, from 1 to 7. This number depends
+on what day is considered the first day of the week, which varies by
+locale. For example, in the \s-1US\s0, Sunday is the first day of the week,
+so this returns 2 for Monday.
+.IP "\(bu" 4
+c
+.Sp
+The numeric day of the week from 1 to 7, treating Monday as the first
+of the week, regardless of locale.
+.IP "\(bu" 4
+ccc
+.Sp
+The abbreviated stand-alone form for the day of the week.
+.IP "\(bu" 4
+cccc
+.Sp
+The wide stand-alone form for the day of the week.
+.IP "\(bu" 4
+ccccc
+.Sp
+The narrow format form for the day of the week.
+.IP "\(bu" 4
+a
+.Sp
+The localized form of \s-1AM\s0 or \s-1PM\s0 for the time.
+.IP "\(bu" 4
+h{1,2}
+.Sp
+The hour from 1\-12.
+.IP "\(bu" 4
+H{1,2}
+.Sp
+The hour from 0\-23.
+.IP "\(bu" 4
+K{1,2}
+.Sp
+The hour from 0\-11.
+.IP "\(bu" 4
+k{1,2}
+.Sp
+The hour from 1\-24.
+.IP "\(bu" 4
+j{1,2}
+.Sp
+The hour, in 12 or 24 hour form, based on the preferred form for the
+locale. In other words, this is equivalent to either \*(L"h{1,2}\*(R" or
+\&\*(L"H{1,2}\*(R".
+.IP "\(bu" 4
+m{1,2}
+.Sp
+The minute.
+.IP "\(bu" 4
+s{1,2}
+.Sp
+The second.
+.IP "\(bu" 4
+S{1,}
+.Sp
+The fractional portion of the seconds, rounded based on the length of
+the specifier. This returned \fIwithout\fR a leading decimal point, but
+may have leading or trailing zeroes.
+.IP "\(bu" 4
+A{1,}
+.Sp
+The millisecond of the day, based on the current time. In other words,
+if it is 12:00:00.00, this returns 43200000.
+.IP "\(bu" 4
+z{1,3}
+.Sp
+The time zone short name.
+.IP "\(bu" 4
+zzzz
+.Sp
+The time zone long name.
+.IP "\(bu" 4
+Z{1,3}
+.Sp
+The time zone short name and the offset as one string, so something
+like \*(L"\s-1CDT\-0500\s0\*(R".
+.IP "\(bu" 4
+\&\s-1ZZZZ\s0
+.Sp
+The time zone long name.
+.IP "\(bu" 4
+v{1,3}
+.Sp
+The time zone short name.
+.IP "\(bu" 4
+vvvv
+.Sp
+The time zone long name.
+.IP "\(bu" 4
+V{1,3}
+.Sp
+The time zone short name.
+.IP "\(bu" 4
+\&\s-1VVVV\s0
+.Sp
+The time zone long name.
+.SH "DateTime.pm and Storable"
+.IX Header "DateTime.pm and Storable"
+DateTime implements Storable hooks in order to reduce the size of a
+serialized DateTime object.
+.SH "KNOWN BUGS"
+.IX Header "KNOWN BUGS"
+The tests in \fI20infinite.t\fR seem to fail on some machines,
+particularly on Win32. This appears to be related to Perl's internal
+handling of \s-1IEEE\s0 infinity and NaN, and seems to be highly
+platform/compiler/phase of moon dependent.
+.PP
+If you don't plan to use infinite datetimes you can probably ignore
+this. This will be fixed (somehow) in future versions.
+.SH "SUPPORT"
+.IX Header "SUPPORT"
+Support for this module is provided via the datetime@perl.org email
+list. See http://datetime.perl.org/?MailingList for details.
+.PP
+Please submit bugs to the \s-1CPAN\s0 \s-1RT\s0 system at
+http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime or via email
+at bug\-datetime@rt.cpan.org.
+.SH "DONATIONS"
+.IX Header "DONATIONS"
+If you'd like to thank me for the work I've done on this module,
+please consider making a \*(L"donation\*(R" to me via PayPal. I spend a lot of
+free time creating free software, and would appreciate any support
+you'd care to offer.
+.PP
+Please note that \fBI am not suggesting that you must do this\fR in order
+for me to continue working on this particular software. I will
+continue to do so, inasmuch as I have in the past, for as long as it
+interests me.
+.PP
+Similarly, a donation made in this way will probably not make me work
+on this software much more, unless I get so many donations that I can
+consider working on free software full time, which seems unlikely at
+best.
+.PP
+To donate, log into PayPal and send money to autarch@urth.org or use
+the button on this page:
+<http://www.urth.org/~autarch/fs\-donation.html>
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Dave Rolsky <autarch@urth.org>
+.PP
+However, please see the \s-1CREDITS\s0 file for more details on who I really
+stole all the code from.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (c) 2003\-2009 David Rolsky. All rights reserved. This
+program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.PP
+Portions of the code in this distribution are derived from other
+works. Please see the \s-1CREDITS\s0 file for more details.
+.PP
+The full text of the license can be found in the \s-1LICENSE\s0 file included
+with this module.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+datetime@perl.org mailing list
+.PP
+http://datetime.perl.org/
projects / catagits/Gitalist.git / blobdiff