period {lubridate} | R Documentation |
period()
creates a period object with the specified values.
period(num = NULL, units = "second", ...) is.period(x) seconds(x = 1) minutes(x = 1) hours(x = 1) days(x = 1) weeks(x = 1) years(x = 1) milliseconds(x = 1) microseconds(x = 1) nanoseconds(x = 1) picoseconds(x = 1) ## S3 method for class 'numeric' months(x, abbreviate)
num |
a numeric vector that lists the number of time units to be
included in the period. From v1.6.0 |
units |
a character vector that lists the type of units to be used. The
units in units are matched to the values in num according to their
order. When |
... |
a list of time units to be included in the period and their
amounts. Seconds, minutes, hours, days, weeks, months, and years are
supported. Normally only one of |
x |
Any R object for |
abbreviate |
Ignored. For consistency with S3 generic in base namespace. |
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 the length of a period is distributed among its 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()
, hours()
, minutes()
,
and seconds()
. These objects can be added to and subtracted
to date-times to create a user interface similar to object oriented programming.
Note: Arithmetic with periods can results in undefined behavior when
non-existent dates are involved (such as February 29th). Please see
Period for more details and %m+%
and
add_with_rollback()
for alternative operations. Note: Arithmetic with
periods can results in undefined behavior when non-existent dates are
involved (such as February 29th in non-leap years). Please see Period
for more details and %m+%
and add_with_rollback()
for
alternative operations.
a period object
Period, period()
, %m+%
,
add_with_rollback()
period(c(90, 5), c("second", "minute")) # "5M 90S" period(-1, "days") period(c(3, 1, 2, 13, 1), c("second", "minute", "hour", "day", "week")) period(c(1, -60), c("hour", "minute")) period(0, "second") period (second = 90, minute = 5) period(day = -1) period(second = 3, minute = 1, hour = 2, day = 13, week = 1) period(hour = 1, minute = -60) period(second = 0) period(c(1, -60), c("hour", "minute"), hour = c(1, 2), minute = c(3, 4)) period("2M 1sec") period("2hours 2minutes 1second") period("2d 2H 2M 2S") period("2days 2hours 2mins 2secs") # Missing numerals default to 1. Repeated units are added up. duration("day day") # Comparison with characters is supported from v1.6.0. duration("day 2 sec") > "day 1sec" ### ELEMENTARY CONSTRUCTORS x <- ymd("2009-08-03") x + days(1) + hours(6) + minutes(30) x + days(100) - hours(8) class(as.Date("2009-08-09") + days(1)) # retains Date class as.Date("2009-08-09") + hours(12) class(as.Date("2009-08-09") + hours(12)) # converts to POSIXt class to accomodate time units years(1) - months(7) c(1:3) * hours(1) hours(1:3) #sequencing y <- ymd(090101) # "2009-01-01 CST" y + months(0:11) # compare DST handling to durations boundary <- ymd_hms("2009-03-08 01:59:59", tz="America/Chicago") boundary + days(1) # period boundary + ddays(1) # duration is.period(as.Date("2009-08-03")) # FALSE is.period(period(months= 1, days = 15)) # TRUE