new_period creates a period object with the specified
values. Within a period object, time units do not have a
fixed length (except for seconds) until they are added to
a date-time. The length of each time unit will depend on
the date-time to which it is added. For example, a year
that begins on 2009-01-01 will be 365 days long. A year
that begins on 2012-01-01 will be 366 days long. When
math is performed with a period object, each unit is
applied separately. How a period is distributed among the
time units is non-trivial. For example, when leap seconds
occur 1 minute is longer than 60 seconds. Periods track the change in the "clock time" between two
date-times. They are measured in common time related
units: years, months, days, hours, minutes, and seconds.
Each unit except for seconds must be expressed in integer
values.
Period objects can be easily created with the helper
functions years
, months
,
weeks
, days
,
minutes
, seconds
. These
objects can be added to and subtracted to date-times to
create a user interface similar to object oriented
programming.