reading DateTime on CPAN

* 0-based versus 1-based
** Month, day-of-month, day-of-week, day-of-year are all 1-based.
** All time-based ones are 0-based.
** Year is neither.

* Errors can occur when calling constructor methods, methods that change
  the object, or methods that take parameters. Methods that retrieve
  information will never die.

* There are locales.

* 'naive' DateTimes are those with a 'floating' time zone. You can compare
  DateTime objects where one is of a real time zone and one of a floating one,
  but the result doesn't really make much sense. Try not to mix real time
  zones with floating ones.

* Determining the local time zone is hard. Please determine the time zone
  manually in your program. We'd do it automatically, but there's no good
  way to actually do that.

* Constructor:

my $dt = DateTime->new( year   => 1066,
                        month  => 10,
                        day    => 25,
                        hour   => 7,
                        minute => 15,
                        second => 47,
                        nanosecond => 500000000,
                        time_zone  => 'America/Chicago',
                      );

** also accepts "locale", "time_zone", and "formatter" parameters
** month ~~ 1..12, day ~~ 1..31 (and valid in month), hour ~~ 0..23,
   minute ~~ 0..59, second ~~ 0..61, nanosecond > 0 (wraps into seconds)
** if second > 59, DateTime actually checks if it's a valid leap second
** all params optional except year
** params default to 1 or 0 as above
** locale parameter ~~ DateTime::Locale
** time_zone parameter can be a DateTime::TimeZone, or a string, the latter
   being passed into DateTime::TimeZone->new as the 'name' paramter.
** the time_zone string may be an Olson DB time zone name ("America/Chicago"),
   an offset string ("+0630"), or the words "floating" or "local"
** the formatter paramter is something that accepts a format_datetime() method

* This module does not parse dates. Other modules on CPAN do that

* Because of Daylight Saving Time, it is possible to specify a local time
  that is ambiguous. The same time specification may have occurred twice in
  a time zone. DateTime always chooses the latter of those.

* Conversely, some local times don't exist. Attempting to create an invalid
  time causes a fatal error.

* DateTime->epoch() creates a DateTime object from an epoch scalar value
* DateTime->now() does DateTime->epoch( time() )
* DateTime->today() does DateTime->now->truncate( to => 'day' )

* There are also constructors called ->last_day_of_month and
  ->from_day_of_year

* There's a clone method

* There are a lot of getter methods, including synonyms and 0- and 1-based
  variants and iso8601 formatters

* There are setter methods for each of the constructors in ->new

* The ->truncate method sets all lower values to 'zero', where 'zero' might
  mean 1 for some values; see above

* If the time zone is set to one with a different offset, the local time
  is adjusted accordingly

* You can add a DateTime and a Duration, you can subtract a Duration from
  a DateTime, and you can subtract two DateTimes.

* A 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

* ->delta_md and ->delta_days and ->delta_ms also do DateTime subtractions,
  but return the result in months/days, days, and minutes/seconds,
  respectively. they always return absolute (non-negative) values

* DateTime->compare($dt1, $dt2). -1, 0, 1 like with <=>. if one datetime
  has a floating time zone, its time zone is converted to that of the other
  object to make them comparable

* there's also DateTime->compare_ignore_floating which doesn't convert
  floating DateTimes. Objects with a floating time zone will be sorted as if
  they were UTC times

* The parts of a duration can be broken down into five parts. These are
  months, days, minutes, seconds, and nanoseconds

* DateTime.pm 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 UTC) values
  are used. For minutes and seconds, the local values are used. This generally
  just works.
** This means that adding one month and one day to February 28, 2003 will
   produce the date April 1, 2003, not March 29, 2003.

* Note that if you converted the datetime object to UTC first you would get
  predictable results.

* DateTime overloads $dt + $dur, $dt - $dur, $dt1 - $dt2, and sort.

* It doesn't override things involving numification or numeric comparison.

* It overloads stringification.

* You can set a formatter on your DateTime object. If unspecified, the
  ->iso8601 method is used.

* ->strftime

* ->format_cldr

* DateTime objects are serializable/persistable