local-lib5/man/man3/DateTime.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "DateTime 3"
 127 .TH DateTime 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 DateTime \- A date and time object
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&  use DateTime;
 138 \&
 139 \&  $dt = DateTime\->new( year   => 1964,
 140 \&                       month  => 10,
 141 \&                       day    => 16,
 142 \&                       hour   => 16,
 143 \&                       minute => 12,
 144 \&                       second => 47,
 145 \&                       nanosecond => 500000000,
 146 \&                       time_zone => \*(AqAsia/Taipei\*(Aq,
 147 \&                     );
 148 \&
 149 \&  $dt = DateTime\->from_epoch( epoch => $epoch );
 150 \&  $dt = DateTime\->now; # same as ( epoch => time() )
 151 \&
 152 \&  $year   = $dt\->year;
 153 \&  $month  = $dt\->month;          # 1\-12 \- also mon
 154 \&
 155 \&  $day    = $dt\->day;            # 1\-31 \- also day_of_month, mday
 156 \&
 157 \&  $dow    = $dt\->day_of_week;    # 1\-7 (Monday is 1) \- also dow, wday
 158 \&
 159 \&  $hour   = $dt\->hour;           # 0\-23
 160 \&  $minute = $dt\->minute;         # 0\-59 \- also min
 161 \&
 162 \&  $second = $dt\->second;         # 0\-61 (leap seconds!) \- also sec
 163 \&
 164 \&  $doy    = $dt\->day_of_year;    # 1\-366 (leap years) \- also doy
 165 \&
 166 \&  $doq    = $dt\->day_of_quarter; # 1.. \- also doq
 167 \&
 168 \&  $qtr    = $dt\->quarter;        # 1\-4
 169 \&
 170 \&  # all of the start\-at\-1 methods above have correponding start\-at\-0
 171 \&  # methods, such as $dt\->day_of_month_0, $dt\->month_0 and so on
 172 \&
 173 \&  $ymd    = $dt\->ymd;           # 2002\-12\-06
 174 \&  $ymd    = $dt\->ymd(\*(Aq/\*(Aq);      # 2002/12/06 \- also date
 175 \&
 176 \&  $mdy    = $dt\->mdy;           # 12\-06\-2002
 177 \&  $mdy    = $dt\->mdy(\*(Aq/\*(Aq);      # 12/06/2002
 178 \&
 179 \&  $dmy    = $dt\->dmy;           # 06\-12\-2002
 180 \&  $dmy    = $dt\->dmy(\*(Aq/\*(Aq);      # 06/12/2002
 181 \&
 182 \&  $hms    = $dt\->hms;           # 14:02:29
 183 \&  $hms    = $dt\->hms(\*(Aq!\*(Aq);      # 14!02!29 \- also time
 184 \&
 185 \&  $is_leap  = $dt\->is_leap_year;
 186 \&
 187 \&  # these are localizable, see Locales section
 188 \&  $month_name  = $dt\->month_name; # January, February, ...
 189 \&  $month_abbr  = $dt\->month_abbr; # Jan, Feb, ...
 190 \&  $day_name    = $dt\->day_name;   # Monday, Tuesday, ...
 191 \&  $day_abbr    = $dt\->day_abbr;   # Mon, Tue, ...
 192 \&
 193 \&  # May not work for all possible datetime, see the docs on this
 194 \&  # method for more details.
 195 \&  $epoch_time  = $dt\->epoch;
 196 \&
 197 \&  $dt2 = $dt + $duration_object;
 198 \&
 199 \&  $dt3 = $dt \- $duration_object;
 200 \&
 201 \&  $duration_object = $dt \- $dt2;
 202 \&
 203 \&  $dt\->set( year => 1882 );
 204 \&
 205 \&  $dt\->set_time_zone( \*(AqAmerica/Chicago\*(Aq );
 206 \&
 207 \&  $dt\->set_formatter( $formatter );
 208 .Ve
 209 .SH "DESCRIPTION"
 210 .IX Header "DESCRIPTION"
 211 DateTime is a class for the representation of date/time combinations,
 212 and is part of the Perl DateTime project.  For details on this project
 213 please see <http://datetime.perl.org/>.  The DateTime site has a \s-1FAQ\s0
 214 which may help answer many \*(L"how do I do X?\*(R" questions.  The \s-1FAQ\s0 is at
 215 <http://datetime.perl.org/?FAQ>.
 216 .PP
 217 It represents the Gregorian calendar, extended backwards in time
 218 before its creation (in 1582).  This is sometimes known as the
 219 \&\*(L"proleptic Gregorian calendar\*(R".  In this calendar, the first day of
 220 the calendar (the epoch), is the first day of year 1, which
 221 corresponds to the date which was (incorrectly) believed to be the
 222 birth of Jesus Christ.
 223 .PP
 224 The calendar represented does have a year 0, and in that way differs
 225 from how dates are often written using \*(L"\s-1BCE/CE\s0\*(R" or \*(L"\s-1BC/AD\s0\*(R".
 226 .PP
 227 For infinite datetimes, please see the
 228 DateTime::Infinite module.
 229 .SH "USAGE"
 230 .IX Header "USAGE"
 231 .SS "0\-based Versus 1\-based Numbers"
 232 .IX Subsection "0-based Versus 1-based Numbers"
 233 The DateTime.pm module follows a simple consistent logic for
 234 determining whether or not a given number is 0\-based or 1\-based.
 235 .PP
 236 Month, day of month, day of week, and day of year are 1\-based.  Any
 237 method that is 1\-based also has an equivalent 0\-based method ending in
 238 \&\*(L"_0\*(R".  So for example, this class provides both \f(CW\*(C`day_of_week()\*(C'\fR and
 239 \&\f(CW\*(C`day_of_week_0()\*(C'\fR methods.
 240 .PP
 241 The \f(CW\*(C`day_of_week_0()\*(C'\fR method still treats Monday as the first day of
 242 the week.
 243 .PP
 244 All \fItime\fR\-related numbers such as hour, minute, and second are
 245 0\-based.
 246 .PP
 247 Years are neither, as they can be both positive or negative, unlike
 248 any other datetime component.  There \fIis\fR a year 0.
 249 .PP
 250 There is no \f(CW\*(C`quarter_0()\*(C'\fR method.
 251 .SS "Error Handling"
 252 .IX Subsection "Error Handling"
 253 Some errors may cause this module to die with an error string.  This
 254 can only happen when calling constructor methods, methods that change
 255 the object, such as \f(CW\*(C`set()\*(C'\fR, or methods that take parameters.
 256 Methods that retrieve information about the object, such as \f(CW\*(C`year()\*(C'\fR
 257 or \f(CW\*(C`epoch()\*(C'\fR, will never die.
 258 .SS "Locales"
 259 .IX Subsection "Locales"
 260 All the object methods which return names or abbreviations return data
 261 based on a locale.  This is done by setting the locale when
 262 constructing a DateTime object.  There is also a \f(CW\*(C`DefaultLocale()\*(C'\fR
 263 class method which may be used to set the default locale for all
 264 DateTime objects created.  If this is not set, then \*(L"en_US\*(R" is used.
 265 .SS "Floating DateTimes"
 266 .IX Subsection "Floating DateTimes"
 267 The default time zone for new DateTime objects, except where stated
 268 otherwise, is the \*(L"floating\*(R" time zone.  This concept comes from the
 269 iCal standard.  A floating datetime is one which is not anchored to
 270 any particular time zone.  In addition, floating datetimes do not
 271 include leap seconds, since we cannot apply them without knowing the
 272 datetime's time zone.
 273 .PP
 274 The results of date math and comparison between a floating datetime
 275 and one with a real time zone are not really valid, because one
 276 includes leap seconds and the other does not.  Similarly, the results
 277 of datetime math between two floating datetimes and two datetimes with
 278 time zones are not really comparable.
 279 .PP
 280 If you are planning to use any objects with a real time zone, it is
 281 strongly recommended that you \fBdo not\fR mix these with floating
 282 datetimes.
 283 .SS "Math"
 284 .IX Subsection "Math"
 285 If you are going to be using doing date math, please read the section
 286 \&\*(L"How Datetime Math is Done\*(R".
 287 .SS "Time Zone Warnings"
 288 .IX Subsection "Time Zone Warnings"
 289 Determining the local time zone for a system can be slow. If \f(CW$ENV{TZ}\fR is
 290 not set, it may involve reading a number of files in \fI/etc\fR or elsewhere. If
 291 you know that the local time zone won't change while your code is running, and
 292 you need to make many objects for the local time zone, it is strongly
 293 recommended that you retrieve the local time zone once and cache it:
 294 .PP
 295 .Vb 1
 296 \&  our $App::LocalTZ = DateTime::TimeZone\->new( name => \*(Aqlocal\*(Aq );
 297 \&
 298 \&  ... # then everywhere else
 299 \&
 300 \&  my $dt = DateTime\->new( ..., time_zone => $App::LocalTZ );
 301 .Ve
 302 .PP
 303 DateTime itself does not do this internally because local time zones can
 304 change, and there's no good way to determine if it's changed without doing all
 305 the work to look it up.
 306 .PP
 307 Do not try to use named time zones (like \*(L"America/Chicago\*(R") with dates
 308 very far in the future (thousands of years). The current
 309 implementation of \f(CW\*(C`DateTime::TimeZone\*(C'\fR will use a huge amount of
 310 memory calculating all the \s-1DST\s0 changes from now until the future
 311 date. Use \s-1UTC\s0 or the floating time zone and you will be safe.
 312 .SS "Methods"
 313 .IX Subsection "Methods"
 314 \fIConstructors\fR
 315 .IX Subsection "Constructors"
 316 .PP
 317 All constructors can die when invalid parameters are given.
 318 .IP "\(bu" 4
 319 DateTime\->new( ... )
 320 .Sp
 321 This class method accepts parameters for each date and time component:
 322 \&\*(L"year\*(R", \*(L"month\*(R", \*(L"day\*(R", \*(L"hour\*(R", \*(L"minute\*(R", \*(L"second\*(R", \*(L"nanosecond\*(R".
 323 It also accepts \*(L"locale\*(R", \*(L"time_zone\*(R", and \*(L"formatter\*(R" parameters.
 324 .Sp
 325 .Vb 9
 326 \&  my $dt = DateTime\->new( year   => 1066,
 327 \&                          month  => 10,
 328 \&                          day    => 25,
 329 \&                          hour   => 7,
 330 \&                          minute => 15,
 331 \&                          second => 47,
 332 \&                          nanosecond => 500000000,
 333 \&                          time_zone  => \*(AqAmerica/Chicago\*(Aq,
 334 \&                        );
 335 .Ve
 336 .Sp
 337 DateTime validates the \*(L"month\*(R", \*(L"day\*(R", \*(L"hour\*(R", \*(L"minute\*(R", and \*(L"second\*(R",
 338 and \*(L"nanosecond\*(R" parameters.  The valid values for these parameters are:
 339 .RS 4
 340 .IP "\(bu" 8
 341 month
 342 .Sp
 343 1\-12
 344 .IP "\(bu" 8
 345 day
 346 .Sp
 347 1\-31, and it must be within the valid range of days for the specified
 348 month
 349 .IP "\(bu" 8
 350 hour
 351 .Sp
 352 0\-23
 353 .IP "\(bu" 8
 354 minute
 355 .Sp
 356 0\-59
 357 .IP "\(bu" 8
 358 second
 359 .Sp
 360 0\-61 (to allow for leap seconds).  Values of 60 or 61 are only allowed
 361 when they match actual leap seconds.
 362 .IP "\(bu" 8
 363 nanosecond
 364 .Sp
 365 >= 0
 366 .RE
 367 .RS 4
 368 .RE
 369 .PP
 370 Invalid parameter types (like an array reference) will cause the
 371 constructor to die.
 372 .PP
 373 The value for seconds may be from 0 to 61, to account for leap
 374 seconds.  If you give a value greater than 59, DateTime does check to
 375 see that it really matches a valid leap second.
 376 .PP
 377 All of the parameters are optional except for \*(L"year\*(R".  The \*(L"month\*(R" and
 378 \&\*(L"day\*(R" parameters both default to 1, while the \*(L"hour\*(R", \*(L"minute\*(R",
 379 \&\*(L"second\*(R", and \*(L"nanosecond\*(R" parameters all default to 0.
 380 .PP
 381 The \*(L"locale\*(R" parameter should be a string matching one of the valid
 382 locales, or a \f(CW\*(C`DateTime::Locale\*(C'\fR object.  See the
 383 DateTime::Locale documentation for details.
 384 .PP
 385 The time_zone parameter can be either a scalar or a
 386 \&\f(CW\*(C`DateTime::TimeZone\*(C'\fR object.  A string will simply be passed to the
 387 \&\f(CW\*(C`DateTime::TimeZone\->new\*(C'\fR method as its \*(L"name\*(R" parameter.  This
 388 string may be an Olson \s-1DB\s0 time zone name (\*(L"America/Chicago\*(R"), an
 389 offset string (\*(L"+0630\*(R"), or the words \*(L"floating\*(R" or \*(L"local\*(R".  See the
 390 \&\f(CW\*(C`DateTime::TimeZone\*(C'\fR documentation for more details.
 391 .PP
 392 The default time zone is \*(L"floating\*(R".
 393 .PP
 394 The \*(L"formatter\*(R" can be either a scalar or an object, but the class
 395 specified by the scalar or the object must implement a
 396 \&\f(CW\*(C`format_datetime()\*(C'\fR method.
 397 .PP
 398 Parsing Dates
 399 .IX Subsection "Parsing Dates"
 400 .PP
 401 \&\fBThis module does not parse dates!\fR That means there is no
 402 constructor to which you can pass things like \*(L"March 3, 1970 12:34\*(R".
 403 .PP
 404 Instead, take a look at the various \f(CW\*(C`DateTime::Format::*\*(C'\fR modules on
 405 \&\s-1CPAN\s0. These parse all sorts of different date formats, and you're
 406 bound to find something that can handle your particular needs.
 407 .PP
 408 Ambiguous Local Times
 409 .IX Subsection "Ambiguous Local Times"
 410 .PP
 411 Because of Daylight Saving Time, it is possible to specify a local
 412 time that is ambiguous.  For example, in the \s-1US\s0 in 2003, the
 413 transition from to saving to standard time occurred on October 26, at
 414 02:00:00 local time.  The local clock changed from 01:59:59 (saving
 415 time) to 01:00:00 (standard time).  This means that the hour from
 416 01:00:00 through 01:59:59 actually occurs twice, though the \s-1UTC\s0 time
 417 continues to move forward.
 418 .PP
 419 If you specify an ambiguous time, then the latest \s-1UTC\s0 time is always
 420 used, in effect always choosing standard time.  In this case, you can
 421 simply subtract an hour to the object in order to move to saving time,
 422 for example:
 423 .PP
 424 .Vb 9
 425 \&  # This object represent 01:30:00 standard time
 426 \&  my $dt = DateTime\->new( year   => 2003,
 427 \&                          month  => 10,
 428 \&                          day    => 26,
 429 \&                          hour   => 1,
 430 \&                          minute => 30,
 431 \&                          second => 0,
 432 \&                          time_zone => \*(AqAmerica/Chicago\*(Aq,
 433 \&                        );
 434 \&
 435 \&  print $dt\->hms;  # prints 01:30:00
 436 \&
 437 \&  # Now the object represent 01:30:00 saving time
 438 \&  $dt\->subtract( hours => 1 );
 439 \&
 440 \&  print $dt\->hms;  # still prints 01:30:00
 441 .Ve
 442 .PP
 443 Alternately, you could create the object with the \s-1UTC\s0 time zone, and
 444 then call the \f(CW\*(C`set_time_zone()\*(C'\fR method to change the time zone.  This
 445 is a good way to ensure that the time is not ambiguous.
 446 .PP
 447 Invalid Local Times
 448 .IX Subsection "Invalid Local Times"
 449 .PP
 450 Another problem introduced by Daylight Saving Time is that certain
 451 local times just do not exist.  For example, in the \s-1US\s0 in 2003, the
 452 transition from standard to saving time occurred on April 6, at the
 453 change to 2:00:00 local time.  The local clock changes from 01:59:59
 454 (standard time) to 03:00:00 (saving time).  This means that there is
 455 no 02:00:00 through 02:59:59 on April 6!
 456 .PP
 457 Attempting to create an invalid time currently causes a fatal error.
 458 This may change in future version of this module.
 459 .IP "\(bu" 4
 460 DateTime\->from_epoch( epoch => \f(CW$epoch\fR, ... )
 461 .Sp
 462 This class method can be used to construct a new DateTime object from
 463 an epoch time instead of components.  Just as with the \f(CW\*(C`new()\*(C'\fR
 464 method, it accepts \*(L"time_zone\*(R", \*(L"locale\*(R", and \*(L"formatter\*(R" parameters.
 465 .Sp
 466 If the epoch value is not an integer, the part after the decimal will
 467 be converted to nanoseconds.  This is done in order to be compatible
 468 with \f(CW\*(C`Time::HiRes\*(C'\fR.  If the floating portion extends past 9 decimal
 469 places, it will be truncated to nine, so that 1.1234567891 will become
 470 1 second and 123,456,789 nanoseconds.
 471 .Sp
 472 By default, the returned object will be in the \s-1UTC\s0 time zone.
 473 .IP "\(bu" 4
 474 DateTime\->now( ... )
 475 .Sp
 476 This class method is equivalent to calling \f(CW\*(C`from_epoch()\*(C'\fR with the
 477 value returned from Perl's \f(CW\*(C`time()\*(C'\fR function.  Just as with the
 478 \&\f(CW\*(C`new()\*(C'\fR method, it accepts \*(L"time_zone\*(R" and \*(L"locale\*(R" parameters.
 479 .Sp
 480 By default, the returned object will be in the \s-1UTC\s0 time zone.
 481 .IP "\(bu" 4
 482 DateTime\->today( ... )
 483 .Sp
 484 This class method is equivalent to:
 485 .Sp
 486 .Vb 1
 487 \&  DateTime\->now\->truncate( to => \*(Aqday\*(Aq );
 488 .Ve
 489 .IP "\(bu" 4
 490 DateTime\->from_object( object => \f(CW$object\fR, ... )
 491 .Sp
 492 This class method can be used to construct a new DateTime object from
 493 any object that implements the \f(CW\*(C`utc_rd_values()\*(C'\fR method.  All
 494 \&\f(CW\*(C`DateTime::Calendar\*(C'\fR modules must implement this method in order to
 495 provide cross-calendar compatibility.  This method accepts a
 496 \&\*(L"locale\*(R" and \*(L"formatter\*(R" parameter
 497 .Sp
 498 If the object passed to this method has a \f(CW\*(C`time_zone()\*(C'\fR method, that
 499 is used to set the time zone of the newly created \f(CW\*(C`DateTime.pm\*(C'\fR
 500 object.
 501 .Sp
 502 Otherwise, the returned object will be in the floating time zone.
 503 .IP "\(bu" 4
 504 DateTime\->last_day_of_month( ... )
 505 .Sp
 506 This constructor takes the same arguments as can be given to the
 507 \&\f(CW\*(C`new()\*(C'\fR method, except for \*(L"day\*(R".  Additionally, both \*(L"year\*(R" and
 508 \&\*(L"month\*(R" are required.
 509 .IP "\(bu" 4
 510 DateTime\->from_day_of_year( ... )
 511 .Sp
 512 This constructor takes the same arguments as can be given to the
 513 \&\f(CW\*(C`new()\*(C'\fR method, except that it does not accept a \*(L"month\*(R" or \*(L"day\*(R"
 514 argument.  Instead, it requires both \*(L"year\*(R" and \*(L"day_of_year\*(R".  The
 515 day of year must be between 1 and 366, and 366 is only allowed for
 516 leap years.
 517 .IP "\(bu" 4
 518 \&\f(CW$dt\fR\->\fIclone()\fR
 519 .Sp
 520 This object method returns a new object that is replica of the object
 521 upon which the method is called.
 522 .PP
 523 \fI\*(L"Get\*(R" Methods\fR
 524 .IX Subsection "Get Methods"
 525 .PP
 526 This class has many methods for retrieving information about an
 527 object.
 528 .IP "\(bu" 4
 529 \&\f(CW$dt\fR\->\fIyear()\fR
 530 .Sp
 531 Returns the year.
 532 .IP "\(bu" 4
 533 \&\f(CW$dt\fR\->\fIce_year()\fR
 534 .Sp
 535 Returns the year according to the \s-1BCE/CE\s0 numbering system.  The year
 536 before year 1 in this system is year \-1, aka \*(L"1 \s-1BCE\s0\*(R".
 537 .IP "\(bu" 4
 538 \&\f(CW$dt\fR\->\fIera_name()\fR
 539 .Sp
 540 Returns the long name of the current era, something like \*(L"Before
 541 Christ\*(R".  See the Locales section for more details.
 542 .IP "\(bu" 4
 543 \&\f(CW$dt\fR\->\fIera_abbr()\fR
 544 .Sp
 545 Returns the abbreviated name of the current era, something like \*(L"\s-1BC\s0\*(R".
 546 See the Locales section for more details.
 547 .IP "\(bu" 4
 548 \&\f(CW$dt\fR\->\fIchristian_era()\fR
 549 .Sp
 550 Returns a string, either \*(L"\s-1BC\s0\*(R" or \*(L"\s-1AD\s0\*(R", according to the year.
 551 .IP "\(bu" 4
 552 \&\f(CW$dt\fR\->\fIsecular_era()\fR
 553 .Sp
 554 Returns a string, either \*(L"\s-1BCE\s0\*(R" or \*(L"\s-1CE\s0\*(R", according to the year.
 555 .IP "\(bu" 4
 556 \&\f(CW$dt\fR\->\fIyear_with_era()\fR
 557 .Sp
 558 Returns a string containing the year immediately followed by its era
 559 abbreviation.  The year is the absolute value of \f(CW\*(C`ce_year()\*(C'\fR, so that
 560 year 1 is \*(L"1AD\*(R" and year 0 is \*(L"1BC\*(R".
 561 .IP "\(bu" 4
 562 \&\f(CW$dt\fR\->\fIyear_with_christian_era()\fR
 563 .Sp
 564 Like \f(CW\*(C`year_with_era()\*(C'\fR, but uses the \fIchristian_era()\fR to get the era
 565 name.
 566 .IP "\(bu" 4
 567 \&\f(CW$dt\fR\->\fIyear_with_secular_era()\fR
 568 .Sp
 569 Like \f(CW\*(C`year_with_era()\*(C'\fR, but uses the \fIsecular_era()\fR method to get the
 570 era name.
 571 .IP "\(bu" 4
 572 \&\f(CW$dt\fR\->\fImonth()\fR
 573 .IP "\(bu" 4
 574 \&\f(CW$dt\fR\->\fImon()\fR
 575 .Sp
 576 Returns the month of the year, from 1..12.
 577 .IP "\(bu" 4
 578 \&\f(CW$dt\fR\->\fImonth_name()\fR
 579 .Sp
 580 Returns the name of the current month.  See the
 581 Locales section for more details.
 582 .IP "\(bu" 4
 583 \&\f(CW$dt\fR\->\fImonth_abbr()\fR
 584 .Sp
 585 Returns the abbreviated name of the current month.  See the
 586 Locales section for more details.
 587 .IP "\(bu" 4
 588 \&\f(CW$dt\fR\->\fIday_of_month()\fR
 589 .IP "\(bu" 4
 590 \&\f(CW$dt\fR\->\fIday()\fR
 591 .IP "\(bu" 4
 592 \&\f(CW$dt\fR\->\fImday()\fR
 593 .Sp
 594 Returns the day of the month, from 1..31.
 595 .IP "\(bu" 4
 596 \&\f(CW$dt\fR\->\fIday_of_week()\fR
 597 .IP "\(bu" 4
 598 \&\f(CW$dt\fR\->\fIwday()\fR
 599 .IP "\(bu" 4
 600 \&\f(CW$dt\fR\->\fIdow()\fR
 601 .Sp
 602 Returns the day of the week as a number, from 1..7, with 1 being
 603 Monday and 7 being Sunday.
 604 .IP "\(bu" 4
 605 \&\f(CW$dt\fR\->\fIlocal_day_of_week()\fR
 606 .Sp
 607 Returns the day of the week as a number, from 1..7. The day
 608 corresponding to 1 will vary based on the locale.
 609 .IP "\(bu" 4
 610 \&\f(CW$dt\fR\->\fIday_name()\fR
 611 .Sp
 612 Returns the name of the current day of the week.  See the
 613 Locales section for more details.
 614 .IP "\(bu" 4
 615 \&\f(CW$dt\fR\->\fIday_abbr()\fR
 616 .Sp
 617 Returns the abbreviated name of the current day of the week.  See the
 618 Locales section for more details.
 619 .IP "\(bu" 4
 620 \&\f(CW$dt\fR\->\fIday_of_year()\fR
 621 .IP "\(bu" 4
 622 \&\f(CW$dt\fR\->\fIdoy()\fR
 623 .Sp
 624 Returns the day of the year.
 625 .IP "\(bu" 4
 626 \&\f(CW$dt\fR\->\fIquarter()\fR
 627 .Sp
 628 Returns the quarter of the year, from 1..4.
 629 .IP "\(bu" 4
 630 \&\f(CW$dt\fR\->\fIquarter_name()\fR
 631 .Sp
 632 Returns the name of the current quarter.  See the
 633 Locales section for more details.
 634 .IP "\(bu" 4
 635 \&\f(CW$dt\fR\->\fIquarter_abbr()\fR
 636 .Sp
 637 Returns the abbreviated name of the current quarter.  See the
 638 Locales section for more details.
 639 .IP "\(bu" 4
 640 \&\f(CW$dt\fR\->\fIday_of_quarter()\fR
 641 .IP "\(bu" 4
 642 \&\f(CW$dt\fR\->\fIdoq()\fR
 643 .Sp
 644 Returns the day of the quarter.
 645 .IP "\(bu" 4
 646 \&\f(CW$dt\fR\->\fIweekday_of_month()\fR
 647 .Sp
 648 Returns a number from 1..5 indicating which week day of the month this
 649 is.  For example, June 9, 2003 is the second Monday of the month, and
 650 so this method returns 2 for that day.
 651 .IP "\(bu" 4
 652 \&\f(CW$dt\fR\->ymd( \f(CW$optional_separator\fR ) \- also \f(CW$dt\fR\->date(...)
 653 .IP "\(bu" 4
 654 \&\f(CW$dt\fR\->mdy( \f(CW$optional_separator\fR )
 655 .IP "\(bu" 4
 656 \&\f(CW$dt\fR\->dmy( \f(CW$optional_separator\fR )
 657 .Sp
 658 Each method returns the year, month, and day, in the order indicated
 659 by the method name.  Years are zero-padded to four digits.  Months and
 660 days are 0\-padded to two digits.
 661 .Sp
 662 By default, the values are separated by a dash (\-), but this can be
 663 overridden by passing a value to the method.
 664 .IP "\(bu" 4
 665 \&\f(CW$dt\fR\->\fIhour()\fR
 666 .Sp
 667 Returns the hour of the day, from 0..23.
 668 .IP "\(bu" 4
 669 \&\f(CW$dt\fR\->\fIhour_1()\fR
 670 .Sp
 671 Returns the hour of the day, from 1..24.
 672 .IP "\(bu" 4
 673 \&\f(CW$dt\fR\->\fIhour_12()\fR
 674 .Sp
 675 Returns the hour of the day, from 1..12.
 676 .IP "\(bu" 4
 677 \&\f(CW$dt\fR\->\fIhour_12_0()\fR
 678 .Sp
 679 Returns the hour of the day, from 0..11.
 680 .IP "\(bu" 4
 681 \&\f(CW$dt\fR\->\fIam_or_pm()\fR
 682 .Sp
 683 Returns the appropriate localized abbreviation, depending on the
 684 current hour.
 685 .IP "\(bu" 4
 686 \&\f(CW$dt\fR\->\fIminute()\fR
 687 .IP "\(bu" 4
 688 \&\f(CW$dt\fR\->\fImin()\fR
 689 .Sp
 690 Returns the minute of the hour, from 0..59.
 691 .IP "\(bu" 4
 692 \&\f(CW$dt\fR\->\fIsecond()\fR
 693 .IP "\(bu" 4
 694 \&\f(CW$dt\fR\->\fIsec()\fR
 695 .Sp
 696 Returns the second, from 0..61.  The values 60 and 61 are used for
 697 leap seconds.
 698 .IP "\(bu" 4
 699 \&\f(CW$dt\fR\->\fIfractional_second()\fR
 700 .Sp
 701 Returns the second, as a real number from 0.0 until 61.999999999
 702 .Sp
 703 The values 60 and 61 are used for leap seconds.
 704 .IP "\(bu" 4
 705 \&\f(CW$dt\fR\->\fImillisecond()\fR
 706 .Sp
 707 Returns the fractional part of the second as milliseconds (1E\-3 seconds).
 708 .Sp
 709 Half a second is 500 milliseconds.
 710 .IP "\(bu" 4
 711 \&\f(CW$dt\fR\->\fImicrosecond()\fR
 712 .Sp
 713 Returns the fractional part of the second as microseconds (1E\-6
 714 seconds).  This value will be rounded to an integer.
 715 .Sp
 716 Half a second is 500_000 microseconds.  This value will be rounded to
 717 an integer.
 718 .IP "\(bu" 4
 719 \&\f(CW$dt\fR\->\fInanosecond()\fR
 720 .Sp
 721 Returns the fractional part of the second as nanoseconds (1E\-9 seconds).
 722 .Sp
 723 Half a second is 500_000_000 nanoseconds.
 724 .IP "\(bu" 4
 725 \&\f(CW$dt\fR\->hms( \f(CW$optional_separator\fR )
 726 .IP "\(bu" 4
 727 \&\f(CW$dt\fR\->time( \f(CW$optional_separator\fR )
 728 .Sp
 729 Returns the hour, minute, and second, all zero-padded to two digits.
 730 If no separator is specified, a colon (:) is used by default.
 731 .IP "\(bu" 4
 732 \&\f(CW$dt\fR\->\fIdatetime()\fR
 733 .IP "\(bu" 4
 734 \&\f(CW$dt\fR\->\fIiso8601()\fR
 735 .Sp
 736 This method is equivalent to:
 737 .Sp
 738 .Vb 1
 739 \&  $dt\->ymd(\*(Aq\-\*(Aq) . \*(AqT\*(Aq . $dt\->hms(\*(Aq:\*(Aq)
 740 .Ve
 741 .IP "\(bu" 4
 742 \&\f(CW$dt\fR\->\fIis_leap_year()\fR
 743 .Sp
 744 This method returns a true or false indicating whether or not the
 745 datetime object is in a leap year.
 746 .IP "\(bu" 4
 747 \&\f(CW$dt\fR\->\fIweek()\fR
 748 .Sp
 749 .Vb 1
 750 \& ($week_year, $week_number) = $dt\->week;
 751 .Ve
 752 .Sp
 753 Returns information about the calendar week which contains this
 754 datetime object. The values returned by this method are also available
 755 separately through the week_year and week_number methods.
 756 .Sp
 757 The first week of the year is defined by \s-1ISO\s0 as the one which contains
 758 the fourth day of January, which is equivalent to saying that it's the
 759 first week to overlap the new year by at least four days.
 760 .Sp
 761 Typically the week year will be the same as the year that the object
 762 is in, but dates at the very beginning of a calendar year often end up
 763 in the last week of the prior year, and similarly, the final few days
 764 of the year may be placed in the first week of the next year.
 765 .IP "\(bu" 4
 766 \&\f(CW$dt\fR\->\fIweek_year()\fR
 767 .Sp
 768 Returns the year of the week.
 769 .IP "\(bu" 4
 770 \&\f(CW$dt\fR\->\fIweek_number()\fR
 771 .Sp
 772 Returns the week of the year, from 1..53.
 773 .IP "\(bu" 4
 774 \&\f(CW$dt\fR\->\fIweek_of_month()\fR
 775 .Sp
 776 The week of the month, from 0..5.  The first week of the month is the
 777 first week that contains a Thursday.  This is based on the \s-1ICU\s0
 778 definition of week of month, and correlates to the \s-1ISO8601\s0 week of
 779 year definition.  A day in the week \fIbefore\fR the week with the first
 780 Thursday will be week 0.
 781 .IP "\(bu" 4
 782 \&\f(CW$dt\fR\->\fIjd()\fR
 783 .IP "\(bu" 4
 784 \&\f(CW$dt\fR\->\fImjd()\fR
 785 .Sp
 786 These return the Julian Day and Modified Julian Day, respectively.
 787 The value returned is a floating point number.  The fractional portion
 788 of the number represents the time portion of the datetime.
 789 .IP "\(bu" 4
 790 \&\f(CW$dt\fR\->\fItime_zone()\fR
 791 .Sp
 792 This returns the \f(CW\*(C`DateTime::TimeZone\*(C'\fR object for the datetime object.
 793 .IP "\(bu" 4
 794 \&\f(CW$dt\fR\->\fIoffset()\fR
 795 .Sp
 796 This returns the offset from \s-1UTC\s0, in seconds, of the datetime object
 797 according to the time zone.
 798 .IP "\(bu" 4
 799 \&\f(CW$dt\fR\->\fIis_dst()\fR
 800 .Sp
 801 Returns a boolean indicating whether or not the datetime object is
 802 currently in Daylight Saving Time or not.
 803 .IP "\(bu" 4
 804 \&\f(CW$dt\fR\->\fItime_zone_long_name()\fR
 805 .Sp
 806 This is a shortcut for \f(CW\*(C`$dt\->time_zone\->name\*(C'\fR.  It's provided so
 807 that one can use \*(L"%{time_zone_long_name}\*(R" as a strftime format
 808 specifier.
 809 .IP "\(bu" 4
 810 \&\f(CW$dt\fR\->\fItime_zone_short_name()\fR
 811 .Sp
 812 This method returns the time zone abbreviation for the current time
 813 zone, such as \*(L"\s-1PST\s0\*(R" or \*(L"\s-1GMT\s0\*(R".  These names are \fBnot\fR definitive, and
 814 should not be used in any application intended for general use by
 815 users around the world.
 816 .IP "\(bu" 4
 817 \&\f(CW$dt\fR\->strftime( \f(CW$format\fR, ... )
 818 .Sp
 819 This method implements functionality similar to the \f(CW\*(C`strftime()\*(C'\fR
 820 method in C.  However, if given multiple format strings, then it will
 821 return multiple scalars, one for each format string.
 822 .Sp
 823 See the \*(L"strftime Patterns\*(R" section for a list of all possible
 824 strftime patterns.
 825 .Sp
 826 If you give a pattern that doesn't exist, then it is simply treated as
 827 text.
 828 .IP "\(bu" 4
 829 \&\f(CW$dt\fR\->format_cldr( \f(CW$format\fR, ... )
 830 .Sp
 831 This method implements formatting based on the \s-1CLDR\s0 date patterns.  If
 832 given multiple format strings, then it will return multiple scalars,
 833 one for each format string.
 834 .Sp
 835 See the \*(L"\s-1CLDR\s0 Patterns\*(R" section for a list of all possible \s-1CLDR\s0
 836 patterns.
 837 .Sp
 838 If you give a pattern that doesn't exist, then it is simply treated as
 839 text.
 840 .IP "\(bu" 4
 841 \&\f(CW$dt\fR\->\fIepoch()\fR
 842 .Sp
 843 Return the \s-1UTC\s0 epoch value for the datetime object.  Internally, this
 844 is implemented using \f(CW\*(C`Time::Local\*(C'\fR, which uses the Unix epoch even on
 845 machines with a different epoch (such as MacOS).  Datetimes before the
 846 start of the epoch will be returned as a negative number.
 847 .Sp
 848 The return value from this method is always an integer.
 849 .Sp
 850 Since the epoch does not account for leap seconds, the epoch time for
 851 1972\-12\-31T23:59:60 (\s-1UTC\s0) is exactly the same as that for
 852 1973\-01\-01T00:00:00.
 853 .Sp
 854 This module uses \f(CW\*(C`Time::Local\*(C'\fR to calculate the epoch, which may or
 855 may not handle epochs before 1904 or after 2038 (depending on the size
 856 of your system's integers, and whether or not Perl was compiled with
 857 64\-bit int support).
 858 .IP "\(bu" 4
 859 \&\f(CW$dt\fR\->\fIhires_epoch()\fR
 860 .Sp
 861 Returns the epoch as a floating point number.  The floating point
 862 portion of the value represents the nanosecond value of the object.
 863 This method is provided for compatibility with the \f(CW\*(C`Time::HiRes\*(C'\fR
 864 module.
 865 .IP "\(bu" 4
 866 \&\f(CW$dt\fR\->\fIis_finite()\fR
 867 .IP "\(bu" 4
 868 \&\f(CW$dt\fR\->is_infinite
 869 .Sp
 870 These methods allow you to distinguish normal datetime objects from
 871 infinite ones.  Infinite datetime objects are documented in
 872 DateTime::Infinite.
 873 .IP "\(bu" 4
 874 \&\f(CW$dt\fR\->\fIutc_rd_values()\fR
 875 .Sp
 876 Returns the current \s-1UTC\s0 Rata Die days, seconds, and nanoseconds as a
 877 three element list.  This exists primarily to allow other calendar
 878 modules to create objects based on the values provided by this object.
 879 .IP "\(bu" 4
 880 \&\f(CW$dt\fR\->\fIlocal_rd_values()\fR
 881 .Sp
 882 Returns the current local Rata Die days, seconds, and nanoseconds as a
 883 three element list.  This exists for the benefit of other modules
 884 which might want to use this information for date math, such as
 885 \&\f(CW\*(C`DateTime::Event::Recurrence\*(C'\fR.
 886 .IP "\(bu" 4
 887 \&\f(CW$dt\fR\->\fIleap_seconds()\fR
 888 .Sp
 889 Returns the number of leap seconds that have happened up to the
 890 datetime represented by the object.  For floating datetimes, this
 891 always returns 0.
 892 .IP "\(bu" 4
 893 \&\f(CW$dt\fR\->\fIutc_rd_as_seconds()\fR
 894 .Sp
 895 Returns the current \s-1UTC\s0 Rata Die days and seconds purely as seconds.
 896 This number ignores any fractional seconds stored in the object,
 897 as well as leap seconds.
 898 .IP "\(bu" 4
 899 \&\f(CW$dt\fR\->\fIlocal_rd_as_seconds()\fR \- deprecated
 900 .Sp
 901 Returns the current local Rata Die days and seconds purely as seconds.
 902 This number ignores any fractional seconds stored in the object,
 903 as well as leap seconds.
 904 .IP "\(bu" 4
 905 \&\f(CW$dt\fR\->\fIlocale()\fR
 906 .Sp
 907 Returns the current locale object.
 908 .IP "\(bu" 4
 909 \&\f(CW$dt\fR\->\fIformatter()\fR
 910 .Sp
 911 Returns current formatter object or class. See \*(L"Formatters And
 912 Stringification\*(R" for details.
 913 .PP
 914 \fI\*(L"Set\*(R" Methods\fR
 915 .IX Subsection "Set Methods"
 916 .PP
 917 The remaining methods provided by \f(CW\*(C`DateTime.pm\*(C'\fR, except where otherwise
 918 specified, return the object itself, thus making method chaining
 919 possible. For example:
 920 .PP
 921 .Vb 1
 922 \&  my $dt = DateTime\->now\->set_time_zone( \*(AqAustralia/Sydney\*(Aq );
 923 \&
 924 \&  my $first = DateTime
 925 \&                \->last_day_of_month( year => 2003, month => 3 )
 926 \&                \->add( days => 1 )
 927 \&                \->subtract( seconds => 1 );
 928 .Ve
 929 .IP "\(bu" 4
 930 \&\f(CW$dt\fR\->set( .. )
 931 .Sp
 932 This method can be used to change the local components of a date time,
 933 or its locale.  This method accepts any parameter allowed by the
 934 \&\f(CW\*(C`new()\*(C'\fR method except for \*(L"time_zone\*(R".  Time zones may be set using
 935 the \f(CW\*(C`set_time_zone()\*(C'\fR method.
 936 .Sp
 937 This method performs parameters validation just as is done in the
 938 \&\f(CW\*(C`new()\*(C'\fR method.
 939 .IP "\(bu" 4
 940 \&\f(CW$dt\fR\->\fIset_year()\fR
 941 .IP "\(bu" 4
 942 \&\f(CW$dt\fR\->\fIset_month()\fR
 943 .IP "\(bu" 4
 944 \&\f(CW$dt\fR\->\fIset_day()\fR
 945 .IP "\(bu" 4
 946 \&\f(CW$dt\fR\->\fIset_hour()\fR
 947 .IP "\(bu" 4
 948 \&\f(CW$dt\fR\->\fIset_minute()\fR
 949 .IP "\(bu" 4
 950 \&\f(CW$dt\fR\->\fIset_second()\fR
 951 .IP "\(bu" 4
 952 \&\f(CW$dt\fR\->\fIset_nanosecond()\fR
 953 .IP "\(bu" 4
 954 \&\f(CW$dt\fR\->\fIset_locale()\fR
 955 .Sp
 956 These are shortcuts to calling \f(CW\*(C`set()\*(C'\fR with a single key.  They all
 957 take a single parameter.
 958 .IP "\(bu" 4
 959 \&\f(CW$dt\fR\->truncate( to => ... )
 960 .Sp
 961 This method allows you to reset some of the local time components in
 962 the object to their \*(L"zero\*(R" values.  The \*(L"to\*(R" parameter is used to
 963 specify which values to truncate, and it may be one of \*(L"year\*(R",
 964 \&\*(L"month\*(R", \*(L"week\*(R", \*(L"day\*(R", \*(L"hour\*(R", \*(L"minute\*(R", or \*(L"second\*(R".  For example,
 965 if \*(L"month\*(R" is specified, then the local day becomes 1, and the hour,
 966 minute, and second all become 0.
 967 .Sp
 968 If \*(L"week\*(R" is given, then the datetime is set to the beginning of the
 969 week in which it occurs, and the time components are all set to 0.
 970 .IP "\(bu" 4
 971 \&\f(CW$dt\fR\->set_time_zone( \f(CW$tz\fR )
 972 .Sp
 973 This method accepts either a time zone object or a string that can be
 974 passed as the \*(L"name\*(R" parameter to \f(CW\*(C`DateTime::TimeZone\->new()\*(C'\fR.
 975 If the new time zone's offset is different from the old time zone,
 976 then the \fIlocal\fR time is adjusted accordingly.
 977 .Sp
 978 For example:
 979 .Sp
 980 .Vb 3
 981 \&  my $dt = DateTime\->new( year => 2000, month => 5, day => 10,
 982 \&                          hour => 15, minute => 15,
 983 \&                          time_zone => \*(AqAmerica/Los_Angeles\*(Aq, );
 984 \&
 985 \&  print $dt\->hour; # prints 15
 986 \&
 987 \&  $dt\->set_time_zone( \*(AqAmerica/Chicago\*(Aq );
 988 \&
 989 \&  print $dt\->hour; # prints 17
 990 .Ve
 991 .Sp
 992 If the old time zone was a floating time zone, then no adjustments to
 993 the local time are made, except to account for leap seconds.  If the
 994 new time zone is floating, then the \fI\s-1UTC\s0\fR time is adjusted in order
 995 to leave the local time untouched.
 996 .Sp
 997 Fans of Tsai Ming-Liang's films will be happy to know that this does
 998 work:
 999 .Sp
1000 .Vb 1
1001 \&  my $dt = DateTime\->now( time_zone => \*(AqAsia/Taipei\*(Aq );
1002 \&
1003 \&  $dt\->set_time_zone( \*(AqEurope/Paris\*(Aq );
1004 .Ve
1005 .Sp
1006 Yes, now we can know \*(L"ni3 na4 bian1 ji2dian3?\*(R"
1007 .IP "\(bu" 4
1008 \&\f(CW$dt\fR\->set_formatter( \f(CW$formatter\fR )
1009 .Sp
1010 Set the formatter for the object. See \*(L"Formatters And
1011 Stringification\*(R" for details.
1012 .PP
1013 \fIMath Methods\fR
1014 .IX Subsection "Math Methods"
1015 .PP
1016 Like the set methods, math related methods always return the object
1017 itself, to allow for chaining:
1018 .PP
1019 .Vb 1
1020 \&  $dt\->add( days => 1 )\->subtract( seconds => 1 );
1021 .Ve
1022 .IP "\(bu" 4
1023 \&\f(CW$dt\fR\->\fIduration_class()\fR
1024 .Sp
1025 This returns \f(CW\*(C`DateTime::Duration\*(C'\fR, but exists so that a subclass of
1026 \&\f(CW\*(C`DateTime.pm\*(C'\fR can provide a different value.
1027 .IP "\(bu" 4
1028 \&\f(CW$dt\fR\->add_duration( \f(CW$duration_object\fR )
1029 .Sp
1030 This method adds a \f(CW\*(C`DateTime::Duration\*(C'\fR to the current datetime.  See
1031 the DateTime::Duration docs for more details.
1032 .IP "\(bu" 4
1033 \&\f(CW$dt\fR\->add( DateTime::Duration\->new parameters )
1034 .Sp
1035 This method is syntactic sugar around the \f(CW\*(C`add_duration()\*(C'\fR method.  It
1036 simply creates a new \f(CW\*(C`DateTime::Duration\*(C'\fR object using the parameters
1037 given, and then calls the \f(CW\*(C`add_duration()\*(C'\fR method.
1038 .IP "\(bu" 4
1039 \&\f(CW$dt\fR\->subtract_duration( \f(CW$duration_object\fR )
1040 .Sp
1041 When given a \f(CW\*(C`DateTime::Duration\*(C'\fR object, this method simply calls
1042 \&\f(CW\*(C`invert()\*(C'\fR on that object and passes that new duration to the
1043 \&\f(CW\*(C`add_duration\*(C'\fR method.
1044 .IP "\(bu" 4
1045 \&\f(CW$dt\fR\->subtract( DateTime::Duration\->new parameters )
1046 .Sp
1047 Like \f(CW\*(C`add()\*(C'\fR, this is syntactic sugar for the \f(CW\*(C`subtract_duration()\*(C'\fR
1048 method.
1049 .IP "\(bu" 4
1050 \&\f(CW$dt\fR\->subtract_datetime( \f(CW$datetime\fR )
1051 .Sp
1052 This method returns a new \f(CW\*(C`DateTime::Duration\*(C'\fR object representing
1053 the difference between the two dates.  The duration is \fBrelative\fR to
1054 the object from which \f(CW$datetime\fR is subtracted.  For example:
1055 .Sp
1056 .Vb 2
1057 \&    2003\-03\-15 00:00:00.00000000
1058 \& \-  2003\-02\-15 00:00:00.00000000
1059 \&
1060 \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1061 \&
1062 \& = 1 month
1063 .Ve
1064 .Sp
1065 Note that this duration is not an absolute measure of the amount of
1066 time between the two datetimes, because the length of a month varies,
1067 as well as due to the presence of leap seconds.
1068 .Sp
1069 The returned duration may have deltas for months, days, minutes,
1070 seconds, and nanoseconds.
1071 .IP "\(bu" 4
1072 \&\f(CW$dt\fR\->delta_md( \f(CW$datetime\fR )
1073 .IP "\(bu" 4
1074 \&\f(CW$dt\fR\->delta_days( \f(CW$datetime\fR )
1075 .Sp
1076 Each of these methods returns a new \f(CW\*(C`DateTime::Duration\*(C'\fR object
1077 representing some portion of the difference between two datetimes.
1078 The \f(CW\*(C`delta_md()\*(C'\fR method returns a duration which contains only the
1079 month and day portions of the duration is represented.  The
1080 \&\f(CW\*(C`delta_days()\*(C'\fR method returns a duration which contains only days.
1081 .Sp
1082 The \f(CW\*(C`delta_md\*(C'\fR and \f(CW\*(C`delta_days\*(C'\fR methods truncate the duration so
1083 that any fractional portion of a day is ignored.  Both of these
1084 methods operate on the date portion of a datetime only, and so
1085 effectively ignore the time zone.
1086 .Sp
1087 Unlike the subtraction methods, \fBthese methods always return a
1088 positive (or zero) duration\fR.
1089 .IP "\(bu" 4
1090 \&\f(CW$dt\fR\->delta_ms( \f(CW$datetime\fR )
1091 .Sp
1092 Returns a duration which contains only minutes and seconds.  Any day
1093 and month differences to minutes are converted to minutes and
1094 seconds. This method also \fBalways return a positive (or zero)
1095 duration\fR.
1096 .IP "\(bu" 4
1097 \&\f(CW$dt\fR\->subtract_datetime_absolute( \f(CW$datetime\fR )
1098 .Sp
1099 This method returns a new \f(CW\*(C`DateTime::Duration\*(C'\fR object representing
1100 the difference between the two dates in seconds and nanoseconds.  This
1101 is the only way to accurately measure the absolute amount of time
1102 between two datetimes, since units larger than a second do not
1103 represent a fixed number of seconds.
1104 .PP
1105 \fIClass Methods\fR
1106 .IX Subsection "Class Methods"
1107 .IP "\(bu" 4
1108 DateTime\->DefaultLocale( \f(CW$locale\fR )
1109 .Sp
1110 This can be used to specify the default locale to be used when
1111 creating DateTime objects.  If unset, then \*(L"en_US\*(R" is used.
1112 .IP "\(bu" 4
1113 DateTime\->compare( \f(CW$dt1\fR, \f(CW$dt2\fR )
1114 .IP "\(bu" 4
1115 DateTime\->compare_ignore_floating( \f(CW$dt1\fR, \f(CW$dt2\fR )
1116 .Sp
1117 .Vb 1
1118 \&  $cmp = DateTime\->compare( $dt1, $dt2 );
1119 \&
1120 \&  $cmp = DateTime\->compare_ignore_floating( $dt1, $dt2 );
1121 .Ve
1122 .Sp
1123 Compare two DateTime objects.  The semantics are compatible with Perl's
1124 \&\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
1125 > \f(CW$dt2\fR.
1126 .Sp
1127 If one of the two DateTime objects has a floating time zone, it will
1128 first be converted to the time zone of the other object.  This is what
1129 you want most of the time, but it can lead to inconsistent results
1130 when you compare a number of DateTime objects, some of which are
1131 floating, and some of which are in other time zones.
1132 .Sp
1133 If you want to have consistent results (because you want to sort a
1134 number of objects, for example), you can use the
1135 \&\f(CW\*(C`compare_ignore_floating()\*(C'\fR method:
1136 .Sp
1137 .Vb 1
1138 \&  @dates = sort { DateTime\->compare_ignore_floating($a, $b) } @dates;
1139 .Ve
1140 .Sp
1141 In this case, objects with a floating time zone will be sorted as if
1142 they were \s-1UTC\s0 times.
1143 .Sp
1144 Since DateTime objects overload comparison operators, this:
1145 .Sp
1146 .Vb 1
1147 \&  @dates = sort @dates;
1148 .Ve
1149 .Sp
1150 is equivalent to this:
1151 .Sp
1152 .Vb 1
1153 \&  @dates = sort { DateTime\->compare($a, $b) } @dates;
1154 .Ve
1155 .Sp
1156 DateTime objects can be compared to any other calendar class that
1157 implements the \f(CW\*(C`utc_rd_values()\*(C'\fR method.
1158 .SS "How Datetime Math is Done"
1159 .IX Subsection "How Datetime Math is Done"
1160 It's important to have some understanding of how datetime math is
1161 implemented in order to effectively use this module and
1162 \&\f(CW\*(C`DateTime::Duration\*(C'\fR.
1163 .PP
1164 \fIMaking Things Simple\fR
1165 .IX Subsection "Making Things Simple"
1166 .PP
1167 If you want to simplify your life and not have to think too hard about
1168 the nitty-gritty of datetime math, I have several recommendations:
1169 .IP "\(bu" 4
1170 use the floating time zone
1171 .Sp
1172 If you do not care about time zones or leap seconds, use the
1173 \&\*(L"floating\*(R" timezone:
1174 .Sp
1175 .Vb 1
1176 \&  my $dt = DateTime\->now( time_zone => \*(Aqfloating\*(Aq );
1177 .Ve
1178 .Sp
1179 Math done on two objects in the floating time zone produces very
1180 predictable results.
1181 .IP "\(bu" 4
1182 use \s-1UTC\s0 for all calculations
1183 .Sp
1184 If you do care about time zones (particularly \s-1DST\s0) or leap seconds,
1185 try to use non-UTC time zones for presentation and user input only.
1186 Convert to \s-1UTC\s0 immediately and convert back to the local time zone for
1187 presentation:
1188 .Sp
1189 .Vb 2
1190 \&  my $dt = DateTime\->new( %user_input, time_zone => $user_tz );
1191 \&  $dt\->set_time_zone(\*(AqUTC\*(Aq);
1192 \&
1193 \&  # do various operations \- store it, retrieve it, add, subtract, etc.
1194 \&
1195 \&  $dt\->set_time_zone($user_tz);
1196 \&  print $dt\->datetime;
1197 .Ve
1198 .IP "\(bu" 4
1199 math on non-UTC time zones
1200 .Sp
1201 If you need to do date math on objects with non-UTC time zones, please
1202 read the caveats below carefully.  The results \f(CW\*(C`DateTime.pm\*(C'\fR produces are
1203 predictable and correct, and mostly intuitive, but datetime math gets
1204 very ugly when time zones are involved, and there are a few strange
1205 corner cases involving subtraction of two datetimes across a \s-1DST\s0
1206 change.
1207 .Sp
1208 If you can always use the floating or \s-1UTC\s0 time zones, you can skip
1209 ahead to Leap Seconds and Date Math
1210 .IP "\(bu" 4
1211 date vs datetime math
1212 .Sp
1213 If you only care about the date (calendar) portion of a datetime, you
1214 should use either \f(CW\*(C`delta_md()\*(C'\fR or \f(CW\*(C`delta_days()\*(C'\fR, not
1215 \&\f(CW\*(C`subtract_datetime()\*(C'\fR.  This will give predictable, unsurprising
1216 results, free from DST-related complications.
1217 .IP "\(bu" 4
1218 \&\fIsubtract_datetime()\fR and \fIadd_duration()\fR
1219 .Sp
1220 You must convert your datetime objects to the \s-1UTC\s0 time zone before
1221 doing date math if you want to make sure that the following formulas
1222 are always true:
1223 .Sp
1224 .Vb 3
1225 \&  $dt2 \- $dt1 = $dur
1226 \&  $dt1 + $dur = $dt2
1227 \&  $dt2 \- $dur = $dt1
1228 .Ve
1229 .Sp
1230 Note that using \f(CW\*(C`delta_days\*(C'\fR ensures that this formula always works,
1231 regardless of the timezone of the objects involved, as does using
1232 \&\f(CW\*(C`subtract_datetime_absolute()\*(C'\fR. Other methods of subtraction are not
1233 always reversible.
1234 .PP
1235 \fIAdding a Duration to a Datetime\fR
1236 .IX Subsection "Adding a Duration to a Datetime"
1237 .PP
1238 The parts of a duration can be broken down into five parts.  These are
1239 months, days, minutes, seconds, and nanoseconds.  Adding one month to
1240 a date is different than adding 4 weeks or 28, 29, 30, or 31 days.
1241 Similarly, due to \s-1DST\s0 and leap seconds, adding a day can be different
1242 than adding 86,400 seconds, and adding a minute is not exactly the
1243 same as 60 seconds.
1244 .PP
1245 We cannot convert between these units, except for seconds and
1246 nanoseconds, because there is no fixed conversion between the two
1247 units, because of things like leap seconds, \s-1DST\s0 changes, etc.
1248 .PP
1249 \&\f(CW\*(C`DateTime.pm\*(C'\fR always adds (or subtracts) days, then months, minutes, and then
1250 seconds and nanoseconds.  If there are any boundary overflows, these are
1251 normalized at each step.  For the days and months the local (not \s-1UTC\s0) values
1252 are used.  For minutes and seconds, the local values are used.  This generally
1253 just works.
1254 .PP
1255 This means that adding one month and one day to February 28, 2003 will
1256 produce the date April 1, 2003, not March 29, 2003.
1257 .PP
1258 .Vb 1
1259 \&  my $dt = DateTime\->new( year => 2003, month => 2, day => 28 );
1260 \&
1261 \&  $dt\->add( months => 1, days => 1 );
1262 \&
1263 \&  # 2003\-04\-01 \- the result
1264 .Ve
1265 .PP
1266 On the other hand, if we add months first, and then separately add
1267 days, we end up with March 29, 2003:
1268 .PP
1269 .Vb 1
1270 \&  $dt\->add( months => 1 )\->add( days => 1 );
1271 \&
1272 \&  # 2003\-03\-29
1273 .Ve
1274 .PP
1275 We see similar strangeness when math crosses a \s-1DST\s0 boundary:
1276 .PP
1277 .Vb 4
1278 \&  my $dt = DateTime\->new( year => 2003, month => 4, day => 5,
1279 \&                          hour => 1, minute => 58,
1280 \&                          time_zone => "America/Chicago",
1281 \&                        );
1282 \&
1283 \&  $dt\->add( days => 1, minutes => 3 );
1284 \&  # 2003\-04\-06 02:01:00
1285 \&
1286 \&  $dt\->add( minutes => 3 )\->add( days => 1 );
1287 \&  # 2003\-04\-06 03:01:00
1288 .Ve
1289 .PP
1290 Note that if you converted the datetime object to \s-1UTC\s0 first you would
1291 get predictable results.
1292 .PP
1293 If you want to know how many seconds a duration object represents, you
1294 have to add it to a datetime to find out, so you could do:
1295 .PP
1296 .Vb 2
1297 \& my $now = DateTime\->now( time_zone => \*(AqUTC\*(Aq );
1298 \& my $later = $now\->clone\->add_duration($duration);
1299 \&
1300 \& my $seconds_dur = $later\->subtract_datetime_absolute($now);
1301 .Ve
1302 .PP
1303 This returns a duration which only contains seconds and nanoseconds.
1304 .PP
1305 If we were add the duration to a different datetime object we might
1306 get a different number of seconds.
1307 .PP
1308 If you need to do lots of work with durations, take a look at Rick
1309 Measham's \f(CW\*(C`DateTime::Format::Duration\*(C'\fR module, which lets you present
1310 information from durations in many useful ways.
1311 .PP
1312 There are other subtract/delta methods in DateTime.pm to generate
1313 different types of durations.  These methods are
1314 \&\f(CW\*(C`subtract_datetime()\*(C'\fR, \f(CW\*(C`subtract_datetime_absolute()\*(C'\fR,
1315 \&\f(CW\*(C`delta_md()\*(C'\fR, \f(CW\*(C`delta_days()\*(C'\fR, and \f(CW\*(C`delta_ms()\*(C'\fR.
1316 .PP
1317 \fIDatetime Subtraction\fR
1318 .IX Subsection "Datetime Subtraction"
1319 .PP
1320 Date subtraction is done solely based on the two object's local
1321 datetimes, with one exception to handle \s-1DST\s0 changes.  Also, if the two
1322 datetime objects are in different time zones, one of them is converted
1323 to the other's time zone first before subtraction.  This is best
1324 explained through examples:
1325 .PP
1326 The first of these probably makes the most sense:
1327 .PP
1328 .Vb 4
1329 \&    my $dt1 = DateTime\->new( year => 2003, month => 5, day => 6,
1330 \&                             time_zone => \*(AqAmerica/Chicago\*(Aq,
1331 \&                           );
1332 \&    # not DST
1333 \&
1334 \&    my $dt2 = DateTime\->new( year => 2003, month => 11, day => 6,
1335 \&                             time_zone => \*(AqAmerica/Chicago\*(Aq,
1336 \&                           );
1337 \&    # is DST
1338 \&
1339 \&    my $dur = $dt2\->subtract_datetime($dt1);
1340 \&    # 6 months
1341 .Ve
1342 .PP
1343 Nice and simple.
1344 .PP
1345 This one is a little trickier, but still fairly logical:
1346 .PP
1347 .Vb 5
1348 \&    my $dt1 = DateTime\->new( year => 2003, month => 4, day => 5,
1349 \&                             hour => 1, minute => 58,
1350 \&                             time_zone => "America/Chicago",
1351 \&                           );
1352 \&    # is DST
1353 \&
1354 \&    my $dt2 = DateTime\->new( year => 2003, month => 4, day => 7,
1355 \&                             hour => 2, minute => 1,
1356 \&                             time_zone => "America/Chicago",
1357 \&                           );
1358 \&    # not DST
1359 \&
1360 \&    my $dur = $dt2\->subtract_datetime($dt1);
1361 \&    # 2 days and 3 minutes
1362 .Ve
1363 .PP
1364 Which contradicts the result this one gives, even though they both
1365 make sense:
1366 .PP
1367 .Vb 5
1368 \&    my $dt1 = DateTime\->new( year => 2003, month => 4, day => 5,
1369 \&                             hour => 1, minute => 58,
1370 \&                             time_zone => "America/Chicago",
1371 \&                           );
1372 \&    # is DST
1373 \&
1374 \&    my $dt2 = DateTime\->new( year => 2003, month => 4, day => 6,
1375 \&                             hour => 3, minute => 1,
1376 \&                             time_zone => "America/Chicago",
1377 \&                           );
1378 \&    # not DST
1379 \&
1380 \&    my $dur = $dt2\->subtract_datetime($dt1);
1381 \&    # 1 day and 3 minutes
1382 .Ve
1383 .PP
1384 This last example illustrates the \*(L"\s-1DST\s0\*(R" exception mentioned earlier.
1385 The exception accounts for the fact 2003\-04\-06 only lasts 23 hours.
1386 .PP
1387 And finally:
1388 .PP
1389 .Vb 4
1390 \&    my $dt2 = DateTime\->new( year => 2003, month => 10, day => 26,
1391 \&                             hour => 1,
1392 \&                             time_zone => \*(AqAmerica/Chicago\*(Aq,
1393 \&                           );
1394 \&
1395 \&    my $dt1 = $dt2\->clone\->subtract( hours => 1 );
1396 \&
1397 \&    my $dur = $dt2\->subtract_datetime($dt1);
1398 \&    # 60 minutes
1399 .Ve
1400 .PP
1401 This seems obvious until you realize that subtracting 60 minutes from
1402 \&\f(CW$dt2\fR in the above example still leaves the clock time at
1403 \&\*(L"01:00:00\*(R".  This time we are accounting for a 25 hour day.
1404 .PP
1405 \fIReversibility\fR
1406 .IX Subsection "Reversibility"
1407 .PP
1408 Date math operations are not always reversible.  This is because of
1409 the way that addition operations are ordered.  As was discussed
1410 earlier, adding 1 day and 3 minutes in one call to \f(CW\*(C`add()\*(C'\fR is not the
1411 same as first adding 3 minutes and 1 day in two separate calls.
1412 .PP
1413 If we take a duration returned from \f(CW\*(C`subtract_datetime()\*(C'\fR and then
1414 try to add or subtract that duration from one of the datetimes we just
1415 used, we sometimes get interesting results:
1416 .PP
1417 .Vb 4
1418 \&  my $dt1 = DateTime\->new( year => 2003, month => 4, day => 5,
1419 \&                           hour => 1, minute => 58,
1420 \&                           time_zone => "America/Chicago",
1421 \&                         );
1422 \&
1423 \&  my $dt2 = DateTime\->new( year => 2003, month => 4, day => 6,
1424 \&                           hour => 3, minute => 1,
1425 \&                           time_zone => "America/Chicago",
1426 \&                         );
1427 \&
1428 \&  my $dur = $dt2\->subtract_datetime($dt1);
1429 \&  # 1 day and 3 minutes
1430 \&
1431 \&  $dt1\->add_duration($dur);
1432 \&  # gives us $dt2
1433 \&
1434 \&  $dt2\->subtract_duration($dur);
1435 \&  # gives us 2003\-04\-05 02:58:00 \- 1 hour later than $dt1
1436 .Ve
1437 .PP
1438 The \f(CW\*(C`subtract_dauration()\*(C'\fR operation gives us a (perhaps) unexpected
1439 answer because it first subtracts one day to get 2003\-04\-05T03:01:00
1440 and then subtracts 3 minutes to get the final result.
1441 .PP
1442 If we explicitly reverse the order we can get the original value of
1443 \&\f(CW$dt1\fR. This can be facilitated by \f(CW\*(C`DateTime::Duration\*(C'\fR's
1444 \&\f(CW\*(C`calendar_duration()\*(C'\fR and \f(CW\*(C`clock_duration()\*(C'\fR methods:
1445 .PP
1446 .Vb 2
1447 \&  $dt2\->subtract_duration( $dur\->clock_duration )
1448 \&      \->subtract_duration( $dur\->calendar_duration );
1449 .Ve
1450 .PP
1451 \fILeap Seconds and Date Math\fR
1452 .IX Subsection "Leap Seconds and Date Math"
1453 .PP
1454 The presence of leap seconds can cause even more anomalies in date
1455 math.  For example, the following is a legal datetime:
1456 .PP
1457 .Vb 3
1458 \&  my $dt = DateTime\->new( year => 1972, month => 12, day => 31,
1459 \&                          hour => 23, minute => 59, second => 60,
1460 \&                          time_zone => \*(AqUTC\*(Aq );
1461 .Ve
1462 .PP
1463 If we do the following:
1464 .PP
1465 .Vb 1
1466 \& $dt\->add( months => 1 );
1467 .Ve
1468 .PP
1469 Then the datetime is now \*(L"1973\-02\-01 00:00:00\*(R", because there is no
1470 23:59:60 on 1973\-01\-31.
1471 .PP
1472 Leap seconds also force us to distinguish between minutes and seconds
1473 during date math.  Given the following datetime:
1474 .PP
1475 .Vb 3
1476 \&  my $dt = DateTime\->new( year => 1972, month => 12, day => 31,
1477 \&                          hour => 23, minute => 59, second => 30,
1478 \&                          time_zone => \*(AqUTC\*(Aq );
1479 .Ve
1480 .PP
1481 we will get different results when adding 1 minute than we get if we
1482 add 60 seconds.  This is because in this case, the last minute of the
1483 day, beginning at 23:59:00, actually contains 61 seconds.
1484 .PP
1485 Here are the results we get:
1486 .PP
1487 .Vb 1
1488 \&  # 1972\-12\-31 23:59:30 \- our starting datetime
1489 \&
1490 \&  $dt\->clone\->add( minutes => 1 );
1491 \&  # 1973\-01\-01 00:00:30 \- one minute later
1492 \&
1493 \&  $dt\->clone\->add( seconds => 60 );
1494 \&  # 1973\-01\-01 00:00:29 \- 60 seconds later
1495 \&
1496 \&  $dt\->clone\->add( seconds => 61 );
1497 \&  # 1973\-01\-01 00:00:30 \- 61 seconds later
1498 .Ve
1499 .PP
1500 \fILocal vs. \s-1UTC\s0 and 24 hours vs. 1 day\fR
1501 .IX Subsection "Local vs. UTC and 24 hours vs. 1 day"
1502 .PP
1503 When math crosses a daylight saving boundary, a single day may have
1504 more or less than 24 hours.
1505 .PP
1506 For example, if you do this:
1507 .PP
1508 .Vb 5
1509 \&  my $dt = DateTime\->new( year => 2003, month => 4, day => 5,
1510 \&                          hour => 2,
1511 \&                          time_zone => \*(AqAmerica/Chicago\*(Aq,
1512 \&                        );
1513 \&  $dt\->add( days => 1 );
1514 .Ve
1515 .PP
1516 then you will produce an \fIinvalid\fR local time, and therefore an
1517 exception will be thrown.
1518 .PP
1519 However, this works:
1520 .PP
1521 .Vb 5
1522 \&  my $dt = DateTime\->new( year => 2003, month => 4, day => 5,
1523 \&                          hour => 2,
1524 \&                          time_zone => \*(AqAmerica/Chicago\*(Aq,
1525 \&                        );
1526 \&  $dt\->add( hours => 24 );
1527 .Ve
1528 .PP
1529 and produces a datetime with the local time of \*(L"03:00\*(R".
1530 .PP
1531 If all this makes your head hurt, there is a simple alternative.  Just
1532 convert your datetime object to the \*(L"\s-1UTC\s0\*(R" time zone before doing date
1533 math on it, and switch it back to the local time zone afterwards.
1534 This avoids the possibility of having date math throw an exception,
1535 and makes sure that 1 day equals 24 hours.  Of course, this may not
1536 always be desirable, so caveat user!
1537 .SS "Overloading"
1538 .IX Subsection "Overloading"
1539 This module explicitly overloads the addition (+), subtraction (\-),
1540 string and numeric comparison operators.  This means that the
1541 following all do sensible things:
1542 .PP
1543 .Vb 1
1544 \&  my $new_dt = $dt + $duration_obj;
1545 \&
1546 \&  my $new_dt = $dt \- $duration_obj;
1547 \&
1548 \&  my $duration_obj = $dt \- $new_dt;
1549 \&
1550 \&  foreach my $dt ( sort @dts ) { ... }
1551 .Ve
1552 .PP
1553 Additionally, the fallback parameter is set to true, so other
1554 derivable operators (+=, \-=, etc.) will work properly.  Do not expect
1555 increment (++) or decrement (\-\-) to do anything useful.
1556 .PP
1557 If you attempt to sort DateTime objects with non\-DateTime.pm objects
1558 or scalars (strings, number, whatever) then an exception will be
1559 thrown. Using the string comparison operators, \f(CW\*(C`eq\*(C'\fR or \f(CW\*(C`ne\*(C'\fR, to
1560 compare a DateTime.pm always returns false.
1561 .PP
1562 The module also overloads stringification to use the \f(CW\*(C`iso8601()\*(C'\fR
1563 method.
1564 .SS "Formatters And Stringification"
1565 .IX Subsection "Formatters And Stringification"
1566 You can optionally specify a \*(L"formatter\*(R", which is usually a
1567 DateTime::Format::* object/class, to control the stringification of
1568 the DateTime object.
1569 .PP
1570 Any of the constructor methods can accept a formatter argument:
1571 .PP
1572 .Vb 2
1573 \&  my $formatter = DateTime::Format::Strptime\->new(...);
1574 \&  my $dt = DateTime\->new(year => 2004, formatter => $formatter);
1575 .Ve
1576 .PP
1577 Or, you can set it afterwards:
1578 .PP
1579 .Vb 2
1580 \&  $dt\->set_formatter($formatter);
1581 \&  $formatter = $dt\->formatter();
1582 .Ve
1583 .PP
1584 Once you set the formatter, the overloaded stringification method will
1585 use the formatter. If unspecified, the \f(CW\*(C`iso8601()\*(C'\fR method is used.
1586 .PP
1587 A formatter can be handy when you know that in your application you
1588 want to stringify your DateTime objects into a special format all the
1589 time, for example to a different language.
1590 .PP
1591 If you provide a formatter class name or object, it must implement a
1592 \&\f(CW\*(C`format_datetime\*(C'\fR method. This method will be called with just the
1593 DateTime object as its argument.
1594 .SS "strftime Patterns"
1595 .IX Subsection "strftime Patterns"
1596 The following patterns are allowed in the format string given to the
1597 \&\f(CW\*(C`$dt\->strftime()\*(C'\fR method:
1598 .IP "\(bu" 4
1599 \&\f(CW%a\fR
1600 .Sp
1601 The abbreviated weekday name.
1602 .IP "\(bu" 4
1603 \&\f(CW%A\fR
1604 .Sp
1605 The full weekday name.
1606 .IP "\(bu" 4
1607 \&\f(CW%b\fR
1608 .Sp
1609 The abbreviated month name.
1610 .IP "\(bu" 4
1611 \&\f(CW%B\fR
1612 .Sp
1613 The full month name.
1614 .IP "\(bu" 4
1615 \&\f(CW%c\fR
1616 .Sp
1617 The default datetime format for the object's locale.
1618 .IP "\(bu" 4
1619 \&\f(CW%C\fR
1620 .Sp
1621 The century number (year/100) as a 2\-digit integer.
1622 .IP "\(bu" 4
1623 \&\f(CW%d\fR
1624 .Sp
1625 The day of the month as a decimal number (range 01 to 31).
1626 .IP "\(bu" 4
1627 \&\f(CW%D\fR
1628 .Sp
1629 Equivalent to \f(CW%m\fR/%d/%y.  This is not a good standard format if you
1630 want folks from both the United States and the rest of the world to
1631 understand the date!
1632 .IP "\(bu" 4
1633 \&\f(CW%e\fR
1634 .Sp
1635 Like \f(CW%d\fR, the day of the month as a decimal number, but a leading zero
1636 is replaced by a space.
1637 .IP "\(bu" 4
1638 \&\f(CW%F\fR
1639 .Sp
1640 Equivalent to \f(CW%Y\fR\-%m\-%d (the \s-1ISO\s0 8601 date format)
1641 .IP "\(bu" 4
1642 \&\f(CW%G\fR
1643 .Sp
1644 The \s-1ISO\s0 8601 year with century as a decimal number.  The 4\-digit year
1645 corresponding to the \s-1ISO\s0 week number (see \f(CW%V\fR).  This has the same
1646 format and value as \f(CW%Y\fR, except that if the \s-1ISO\s0 week number belongs to
1647 the previous or next year, that year is used instead. (\s-1TZ\s0)
1648 .IP "\(bu" 4
1649 \&\f(CW%g\fR
1650 .Sp
1651 Like \f(CW%G\fR, but without century, i.e., with a 2\-digit year (00\-99).
1652 .IP "\(bu" 4
1653 \&\f(CW%h\fR
1654 .Sp
1655 Equivalent to \f(CW%b\fR.
1656 .IP "\(bu" 4
1657 \&\f(CW%H\fR
1658 .Sp
1659 The hour as a decimal number using a 24\-hour clock (range 00 to 23).
1660 .IP "\(bu" 4
1661 \&\f(CW%I\fR
1662 .Sp
1663 The hour as a decimal number using a 12\-hour clock (range 01 to 12).
1664 .IP "\(bu" 4
1665 \&\f(CW%j\fR
1666 .Sp
1667 The day of the year as a decimal number (range 001 to 366).
1668 .IP "\(bu" 4
1669 \&\f(CW%k\fR
1670 .Sp
1671 The hour (24\-hour clock) as a decimal number (range 0 to 23); single
1672 digits are preceded by a blank. (See also \f(CW%H\fR.)
1673 .IP "\(bu" 4
1674 \&\f(CW%l\fR
1675 .Sp
1676 The hour (12\-hour clock) as a decimal number (range 1 to 12); single
1677 digits are preceded by a blank. (See also \f(CW%I\fR.)
1678 .IP "\(bu" 4
1679 \&\f(CW%m\fR
1680 .Sp
1681 The month as a decimal number (range 01 to 12).
1682 .IP "\(bu" 4
1683 \&\f(CW%M\fR
1684 .Sp
1685 The minute as a decimal number (range 00 to 59).
1686 .IP "\(bu" 4
1687 \&\f(CW%n\fR
1688 .Sp
1689 A newline character.
1690 .IP "\(bu" 4
1691 \&\f(CW%N\fR
1692 .Sp
1693 The fractional seconds digits. Default is 9 digits (nanoseconds).
1694 .Sp
1695 .Vb 3
1696 \&  %3N   milliseconds (3 digits)
1697 \&  %6N   microseconds (6 digits)
1698 \&  %9N   nanoseconds  (9 digits)
1699 .Ve
1700 .IP "\(bu" 4
1701 \&\f(CW%p\fR
1702 .Sp
1703 Either `\s-1AM\s0' or `\s-1PM\s0' according to the given time value, or the
1704 corresponding strings for the current locale.  Noon is treated as `pm'
1705 and midnight as `am'.
1706 .IP "\(bu" 4
1707 \&\f(CW%P\fR
1708 .Sp
1709 Like \f(CW%p\fR but in lowercase: `am' or `pm' or a corresponding string for
1710 the current locale.
1711 .IP "\(bu" 4
1712 \&\f(CW%r\fR
1713 .Sp
1714 The time in a.m.  or p.m. notation.  In the \s-1POSIX\s0 locale this is
1715 equivalent to `%I:%M:%S \f(CW%p\fR'.
1716 .IP "\(bu" 4
1717 \&\f(CW%R\fR
1718 .Sp
1719 The time in 24\-hour notation (%H:%M). (\s-1SU\s0) For a version including the
1720 seconds, see \f(CW%T\fR below.
1721 .IP "\(bu" 4
1722 \&\f(CW%s\fR
1723 .Sp
1724 The number of seconds since the epoch.
1725 .IP "\(bu" 4
1726 \&\f(CW%S\fR
1727 .Sp
1728 The second as a decimal number (range 00 to 61).
1729 .IP "\(bu" 4
1730 \&\f(CW%t\fR
1731 .Sp
1732 A tab character.
1733 .IP "\(bu" 4
1734 \&\f(CW%T\fR
1735 .Sp
1736 The time in 24\-hour notation (%H:%M:%S).
1737 .IP "\(bu" 4
1738 \&\f(CW%u\fR
1739 .Sp
1740 The day of the week as a decimal, range 1 to 7, Monday being 1.  See
1741 also \f(CW%w\fR.
1742 .IP "\(bu" 4
1743 \&\f(CW%U\fR
1744 .Sp
1745 The week number of the current year as a decimal number, range 00 to
1746 53, starting with the first Sunday as the first day of week 01. See
1747 also \f(CW%V\fR and \f(CW%W\fR.
1748 .IP "\(bu" 4
1749 \&\f(CW%V\fR
1750 .Sp
1751 The \s-1ISO\s0 8601:1988 week number of the current year as a decimal number,
1752 range 01 to 53, where week 1 is the first week that has at least 4
1753 days in the current year, and with Monday as the first day of the
1754 week. See also \f(CW%U\fR and \f(CW%W\fR.
1755 .IP "\(bu" 4
1756 \&\f(CW%w\fR
1757 .Sp
1758 The day of the week as a decimal, range 0 to 6, Sunday being 0.  See
1759 also \f(CW%u\fR.
1760 .IP "\(bu" 4
1761 \&\f(CW%W\fR
1762 .Sp
1763 The week number of the current year as a decimal number, range 00 to
1764 53, starting with the first Monday as the first day of week 01.
1765 .IP "\(bu" 4
1766 \&\f(CW%x\fR
1767 .Sp
1768 The default date format for the object's locale.
1769 .IP "\(bu" 4
1770 \&\f(CW%X\fR
1771 .Sp
1772 The default time format for the object's locale.
1773 .IP "\(bu" 4
1774 \&\f(CW%y\fR
1775 .Sp
1776 The year as a decimal number without a century (range 00 to 99).
1777 .IP "\(bu" 4
1778 \&\f(CW%Y\fR
1779 .Sp
1780 The year as a decimal number including the century.
1781 .IP "\(bu" 4
1782 \&\f(CW%z\fR
1783 .Sp
1784 The time-zone as hour offset from \s-1UTC\s0.  Required to emit
1785 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").
1786 .IP "\(bu" 4
1787 \&\f(CW%Z\fR
1788 .Sp
1789 The time zone or name or abbreviation.
1790 .IP "\(bu" 4
1791 %%
1792 .Sp
1793 A literal `%' character.
1794 .IP "\(bu" 4
1795 %{method}
1796 .Sp
1797 Any method name may be specified using the format \f(CW\*(C`%{method}\*(C'\fR name
1798 where \*(L"method\*(R" is a valid \f(CW\*(C`DateTime.pm\*(C'\fR object method.
1799 .SS "\s-1CLDR\s0 Patterns"
1800 .IX Subsection "CLDR Patterns"
1801 The \s-1CLDR\s0 pattern language is both more powerful and more complex than
1802 strftime. Unlike strftime patterns, you often have to explicitly
1803 escape text that you do not want formatted, as the patterns are simply
1804 letters without any prefix.
1805 .PP
1806 For example, \*(L"yyyy-MM-dd\*(R" is a valid \s-1CLDR\s0 pattern. If you want to
1807 include any lower or upper case \s-1ASCII\s0 characters as-is, you can
1808 surround them with single quotes ('). If you want to include a single
1809 quote, you must escape it as two single quotes ('').
1810 .PP
1811 .Vb 2
1812 \&  \*(AqToday is \*(Aq EEEE
1813 \&  \*(AqIt is now\*(Aq h \*(Aqo\*(Aq\*(Aqclock\*(Aq a
1814 .Ve
1815 .PP
1816 Spaces and any non-letter text will always be passed through as-is.
1817 .PP
1818 Many \s-1CLDR\s0 patterns which produce numbers will pad the number with
1819 leading zeroes depending on the length of the format specifier. For
1820 example, \*(L"h\*(R" represents the current hour from 1\-12. If you specify
1821 \&\*(L"hh\*(R" then the 1\-9 will have a leading zero prepended.
1822 .PP
1823 However, \s-1CLDR\s0 often uses five of a letter to represent the narrow form
1824 of a pattern. This inconsistency is necessary for backwards
1825 compatibility.
1826 .PP
1827 \&\s-1CLDR\s0 often distinguishes between the \*(L"format\*(R" and \*(L"stand-alone\*(R" forms
1828 of a pattern. The format pattern is used when the thing in question is
1829 being placed into a larger string. The stand-alone form is used when
1830 displaying that item by itself, for example in a calendar.
1831 .PP
1832 It also often provides three sizes for each item, wide (the full
1833 name), abbreviated, and narrow. The narrow form is often just a single
1834 character, for example \*(L"T\*(R" for \*(L"Tuesday\*(R", and may not be unique.
1835 .PP
1836 \&\s-1CLDR\s0 provides a fairly complex system for localizing time zones that
1837 we ignore entirely. The time zone patterns just use the information
1838 provided by \f(CW\*(C`DateTime::TimeZone\*(C'\fR, and \fIdo not follow the \s-1CLDR\s0 spec\fR.
1839 .PP
1840 The output of a \s-1CLDR\s0 pattern is always localized, when applicable.
1841 .PP
1842 \&\s-1CLDR\s0 provides the following patterns:
1843 .IP "\(bu" 4
1844 G{1,3}
1845 .Sp
1846 The abbreviated era (\s-1BC\s0, \s-1AD\s0).
1847 .IP "\(bu" 4
1848 \&\s-1GGGG\s0
1849 .Sp
1850 The wide era (Before Christ, Anno Domini).
1851 .IP "\(bu" 4
1852 \&\s-1GGGGG\s0
1853 .Sp
1854 The narrow era, if it exists (and it mostly doesn't).
1855 .IP "\(bu" 4
1856 y and y{3,}
1857 .Sp
1858 The year, zero-prefixed as needed. Negative years will start with a \*(L"\-\*(R",
1859 and this will be included in the length calculation.
1860 .Sp
1861 In other, words the \*(L"yyyyy\*(R" pattern will format year \-1234 as \*(L"\-1234\*(R", not
1862 \&\*(L"\-01234\*(R".
1863 .IP "\(bu" 4
1864 yy
1865 .Sp
1866 This is a special case. It always produces a two-digit year, so \*(L"1976\*(R" becomes
1867 \&\*(L"76\*(R". Negative years will start with a \*(L"\-\*(R", making them one character longer.
1868 .IP "\(bu" 4
1869 Y{1,}
1870 .Sp
1871 The week of the year, from \f(CW\*(C`$dt\->week_year()\*(C'\fR.
1872 .IP "\(bu" 4
1873 u{1,}
1874 .Sp
1875 Same as \*(L"y\*(R" except that \*(L"uu\*(R" is not a special case.
1876 .IP "\(bu" 4
1877 Q{1,2}
1878 .Sp
1879 The quarter as a number (1..4).
1880 .IP "\(bu" 4
1881 \&\s-1QQQ\s0
1882 .Sp
1883 The abbreviated format form for the quarter.
1884 .IP "\(bu" 4
1885 \&\s-1QQQQ\s0
1886 .Sp
1887 The wide format form for the quarter.
1888 .IP "\(bu" 4
1889 q{1,2}
1890 .Sp
1891 The quarter as a number (1..4).
1892 .IP "\(bu" 4
1893 qqq
1894 .Sp
1895 The abbreviated stand-alone form for the quarter.
1896 .IP "\(bu" 4
1897 qqqq
1898 .Sp
1899 The wide stand-alone form for the quarter.
1900 .IP "\(bu" 4
1901 M{1,2]
1902 .Sp
1903 The numerical month.
1904 .IP "\(bu" 4
1905 \&\s-1MMM\s0
1906 .Sp
1907 The abbreviated format form for the month.
1908 .IP "\(bu" 4
1909 \&\s-1MMMM\s0
1910 .Sp
1911 The wide format form for the month.
1912 .IP "\(bu" 4
1913 \&\s-1MMMMM\s0
1914 .Sp
1915 The narrow format form for the month.
1916 .IP "\(bu" 4
1917 L{1,2]
1918 .Sp
1919 The numerical month.
1920 .IP "\(bu" 4
1921 \&\s-1LLL\s0
1922 .Sp
1923 The abbreviated stand-alone form for the month.
1924 .IP "\(bu" 4
1925 \&\s-1LLLL\s0
1926 .Sp
1927 The wide stand-alone form for the month.
1928 .IP "\(bu" 4
1929 \&\s-1LLLLL\s0
1930 .Sp
1931 The narrow stand-alone form for the month.
1932 .IP "\(bu" 4
1933 w{1,2}
1934 .Sp
1935 The week of the year, from \f(CW\*(C`$dt\->week_number()\*(C'\fR.
1936 .IP "\(bu" 4
1937 W
1938 .Sp
1939 The week of the month, from \f(CW\*(C`$dt\->week_of_month()\*(C'\fR.
1940 .IP "\(bu" 4
1941 d{1,2}
1942 .Sp
1943 The numeric day of of the month.
1944 .IP "\(bu" 4
1945 D{1,3}
1946 .Sp
1947 The numeric day of of the year.
1948 .IP "\(bu" 4
1949 F
1950 .Sp
1951 The day of the week in the month, from \f(CW\*(C`$dt\->weekday_of_month()\*(C'\fR.
1952 .IP "\(bu" 4
1953 g{1,}
1954 .Sp
1955 The modified Julian day, from \f(CW\*(C`$dt\->mjd()\*(C'\fR.
1956 .IP "\(bu" 4
1957 E{1,3} and eee
1958 .Sp
1959 The abbreviated format form for the day of the week.
1960 .IP "\(bu" 4
1961 \&\s-1EEEE\s0 and eeee
1962 .Sp
1963 The wide format form for the day of the week.
1964 .IP "\(bu" 4
1965 \&\s-1EEEEE\s0 and eeeee
1966 .Sp
1967 The narrow format form for the day of the week.
1968 .IP "\(bu" 4
1969 e{1,2}
1970 .Sp
1971 The \fIlocal\fR numeric day of the week, from 1 to 7. This number depends
1972 on what day is considered the first day of the week, which varies by
1973 locale. For example, in the \s-1US\s0, Sunday is the first day of the week,
1974 so this returns 2 for Monday.
1975 .IP "\(bu" 4
1976 c
1977 .Sp
1978 The numeric day of the week from 1 to 7, treating Monday as the first
1979 of the week, regardless of locale.
1980 .IP "\(bu" 4
1981 ccc
1982 .Sp
1983 The abbreviated stand-alone form for the day of the week.
1984 .IP "\(bu" 4
1985 cccc
1986 .Sp
1987 The wide stand-alone form for the day of the week.
1988 .IP "\(bu" 4
1989 ccccc
1990 .Sp
1991 The narrow format form for the day of the week.
1992 .IP "\(bu" 4
1993 a
1994 .Sp
1995 The localized form of \s-1AM\s0 or \s-1PM\s0 for the time.
1996 .IP "\(bu" 4
1997 h{1,2}
1998 .Sp
1999 The hour from 1\-12.
2000 .IP "\(bu" 4
2001 H{1,2}
2002 .Sp
2003 The hour from 0\-23.
2004 .IP "\(bu" 4
2005 K{1,2}
2006 .Sp
2007 The hour from 0\-11.
2008 .IP "\(bu" 4
2009 k{1,2}
2010 .Sp
2011 The hour from 1\-24.
2012 .IP "\(bu" 4
2013 j{1,2}
2014 .Sp
2015 The hour, in 12 or 24 hour form, based on the preferred form for the
2016 locale. In other words, this is equivalent to either \*(L"h{1,2}\*(R" or
2017 \&\*(L"H{1,2}\*(R".
2018 .IP "\(bu" 4
2019 m{1,2}
2020 .Sp
2021 The minute.
2022 .IP "\(bu" 4
2023 s{1,2}
2024 .Sp
2025 The second.
2026 .IP "\(bu" 4
2027 S{1,}
2028 .Sp
2029 The fractional portion of the seconds, rounded based on the length of
2030 the specifier. This returned \fIwithout\fR a leading decimal point, but
2031 may have leading or trailing zeroes.
2032 .IP "\(bu" 4
2033 A{1,}
2034 .Sp
2035 The millisecond of the day, based on the current time. In other words,
2036 if it is 12:00:00.00, this returns 43200000.
2037 .IP "\(bu" 4
2038 z{1,3}
2039 .Sp
2040 The time zone short name.
2041 .IP "\(bu" 4
2042 zzzz
2043 .Sp
2044 The time zone long name.
2045 .IP "\(bu" 4
2046 Z{1,3}
2047 .Sp
2048 The time zone short name and the offset as one string, so something
2049 like \*(L"\s-1CDT\-0500\s0\*(R".
2050 .IP "\(bu" 4
2051 \&\s-1ZZZZ\s0
2052 .Sp
2053 The time zone long name.
2054 .IP "\(bu" 4
2055 v{1,3}
2056 .Sp
2057 The time zone short name.
2058 .IP "\(bu" 4
2059 vvvv
2060 .Sp
2061 The time zone long name.
2062 .IP "\(bu" 4
2063 V{1,3}
2064 .Sp
2065 The time zone short name.
2066 .IP "\(bu" 4
2067 \&\s-1VVVV\s0
2068 .Sp
2069 The time zone long name.
2070 .SH "DateTime.pm and Storable"
2071 .IX Header "DateTime.pm and Storable"
2072 DateTime implements Storable hooks in order to reduce the size of a
2073 serialized DateTime object.
2074 .SH "KNOWN BUGS"
2075 .IX Header "KNOWN BUGS"
2076 The tests in \fI20infinite.t\fR seem to fail on some machines,
2077 particularly on Win32.  This appears to be related to Perl's internal
2078 handling of \s-1IEEE\s0 infinity and NaN, and seems to be highly
2079 platform/compiler/phase of moon dependent.
2080 .PP
2081 If you don't plan to use infinite datetimes you can probably ignore
2082 this.  This will be fixed (somehow) in future versions.
2083 .SH "SUPPORT"
2084 .IX Header "SUPPORT"
2085 Support for this module is provided via the datetime@perl.org email
2086 list. See http://datetime.perl.org/?MailingList for details.
2087 .PP
2088 Please submit bugs to the \s-1CPAN\s0 \s-1RT\s0 system at
2089 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime or via email
2090 at bug\-datetime@rt.cpan.org.
2091 .SH "DONATIONS"
2092 .IX Header "DONATIONS"
2093 If you'd like to thank me for the work I've done on this module,
2094 please consider making a \*(L"donation\*(R" to me via PayPal. I spend a lot of
2095 free time creating free software, and would appreciate any support
2096 you'd care to offer.
2097 .PP
2098 Please note that \fBI am not suggesting that you must do this\fR in order
2099 for me to continue working on this particular software. I will
2100 continue to do so, inasmuch as I have in the past, for as long as it
2101 interests me.
2102 .PP
2103 Similarly, a donation made in this way will probably not make me work
2104 on this software much more, unless I get so many donations that I can
2105 consider working on free software full time, which seems unlikely at
2106 best.
2107 .PP
2108 To donate, log into PayPal and send money to autarch@urth.org or use
2109 the button on this page:
2110 <http://www.urth.org/~autarch/fs\-donation.html>
2111 .SH "AUTHOR"
2112 .IX Header "AUTHOR"
2113 Dave Rolsky <autarch@urth.org>
2114 .PP
2115 However, please see the \s-1CREDITS\s0 file for more details on who I really
2116 stole all the code from.
2117 .SH "COPYRIGHT"
2118 .IX Header "COPYRIGHT"
2119 Copyright (c) 2003\-2009 David Rolsky.  All rights reserved.  This
2120 program is free software; you can redistribute it and/or modify it
2121 under the same terms as Perl itself.
2122 .PP
2123 Portions of the code in this distribution are derived from other
2124 works.  Please see the \s-1CREDITS\s0 file for more details.
2125 .PP
2126 The full text of the license can be found in the \s-1LICENSE\s0 file included
2127 with this module.
2128 .SH "SEE ALSO"
2129 .IX Header "SEE ALSO"
2130 datetime@perl.org mailing list
2131 .PP
2132 http://datetime.perl.org/