duration: Create a duration object.

Description

duration() creates a duration object with the specified values. Entries for different units are cumulative. durations display as the number of seconds in a time span. When this number is large, durations also display an estimate in larger units,; however, the underlying object is always recorded as a fixed number of seconds. For display and creation purposes, units are converted to seconds using their most common lengths in seconds. Minutes = 60 seconds, hours = 3600 seconds, days = 86400 seconds, weeks = 604800. Units larger than weeks are not used due to their variability.

Usage

duration(num = NULL, units = "seconds", ...)
dseconds(x = 1)
dminutes(x = 1)
dhours(x = 1)
ddays(x = 1)
dweeks(x = 1)
dyears(x = 1)
dmilliseconds(x = 1)
dmicroseconds(x = 1)
dnanoseconds(x = 1)
dpicoseconds(x = 1)
is.duration(x)

Arguments

num

the number or a character vector of time units. In string representation all unambiguous name units and abbreviations are supported; 'm' stands for month and 'M' for minutes, see examples. Fractional units are supported.

units

a character string that specifies the type of units that num refers to. When num is character, this argument is ignored.

...

a list of time units to be included in the duration and their amounts. Seconds, minutes, hours, days, and weeks are supported.

numeric value of the number of units to be contained in the duration.

Value

a duration object

Details

Durations record the exact number of seconds in a time span. They measure the exact passage of time but do not always align with measurements made in larger units of time such as hours, months and years. This is because the length of larger time units can be affected by conventions such as leap years and Daylight Savings Time. Base R provides a second class for measuring durations, the difftime class.

Duration objects can be easily created with the helper functions dweeks(), ddays(), dminutes(), dseconds(). These objects can be added to and subtracted to date- times to create a user interface similar to object oriented programming.

Examples

Run this code

# NOT RUN {
duration(day = -1)
# -86400s (~-1 days)
duration(90, "seconds")
duration(1.5, "minutes")
duration(-1, "days")
# -86400s (~-1 days)
duration(second = 90)
duration(minute = 1.5)
duration(mins = 1.5)
duration(second = 3, minute = 1.5, hour = 2, day = 6, week = 1)
duration(hour = 1, minute = -60)
duration("2M 1sec")
duration("2hours 2minutes 1second")
duration("2d 2H 2M 2S")
duration("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:

dseconds(1)
dminutes(3.5)

x <- as.POSIXct("2009-08-03")
x + ddays(1) + dhours(6) + dminutes(30)
x + ddays(100) - dhours(8)

class(as.Date("2009-08-09") + ddays(1)) # retains Date class
as.Date("2009-08-09") + dhours(12)
class(as.Date("2009-08-09") + dhours(12))
# converts to POSIXt class to accomodate time units

dweeks(1) - ddays(7)
c(1:3) * dhours(1)

# compare DST handling to durations
boundary <- as.POSIXct("2009-03-08 01:59:59")
boundary + days(1) # period
boundary + ddays(1) # duration
is.duration(as.Date("2009-08-03")) # FALSE
is.duration(duration(days = 12.4)) # TRUE
# }