1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/durations.r
3\name{duration}
4\alias{duration}
5\alias{dseconds}
6\alias{dminutes}
7\alias{dhours}
8\alias{ddays}
9\alias{dweeks}
10\alias{dmonths}
11\alias{dyears}
12\alias{dmilliseconds}
13\alias{dmicroseconds}
14\alias{dnanoseconds}
15\alias{dpicoseconds}
16\alias{is.duration}
17\title{Create a duration object.}
18\usage{
19duration(num = NULL, units = "seconds", ...)
20
21dseconds(x = 1)
22
23dminutes(x = 1)
24
25dhours(x = 1)
26
27ddays(x = 1)
28
29dweeks(x = 1)
30
31dmonths(x = 1)
32
33dyears(x = 1)
34
35dmilliseconds(x = 1)
36
37dmicroseconds(x = 1)
38
39dnanoseconds(x = 1)
40
41dpicoseconds(x = 1)
42
43is.duration(x)
44}
45\arguments{
46\item{num}{the number or a character vector of time units. In string
47representation all unambiguous name units and abbreviations and ISO 8601
48formats are supported; 'm' stands for month and 'M' for minutes unless ISO
498601 "P" modifier is present (see examples). Fractional units are
50supported.}
51
52\item{units}{a character string that specifies the type of units that \code{num}
53refers to. When \code{num} is character, this argument is ignored.}
54
55\item{...}{a list of time units to be included in the duration and their
56amounts. Seconds, minutes, hours, days, weeks, months and years are
57supported. Durations of months and years assume that year consists of
58365.25 days.}
59
60\item{x}{numeric value of the number of units to be contained in the
61duration.}
62}
63\value{
64a duration object
65}
66\description{
67\code{duration()} creates a duration object with the specified values. Entries
68for different units are cumulative. durations display as the number of
69seconds in a time span. When this number is large, durations also display an
70estimate in larger units, however, the underlying object is always recorded
71as a fixed number of seconds. For display and creation purposes, units are
72converted to seconds using their most common lengths in seconds. Minutes = 60
73seconds, hours = 3600 seconds, days = 86400 seconds, weeks = 604800. Units
74larger than weeks are not used due to their variability.
75}
76\details{
77Durations record the exact number of seconds in a time span. They measure the
78exact passage of time but do not always align with measurements
79made in larger units of time such as hours, months and years.
80This is because the length of larger time units can be affected
81by conventions such as leap years
82and Daylight Savings Time. Base R provides a second class for measuring
83durations, the difftime class.
84
85Duration objects can be easily created with the helper functions \code{\link[=dweeks]{dweeks()}},
86\code{\link[=ddays]{ddays()}}, \code{\link[=dminutes]{dminutes()}}, \code{\link[=dseconds]{dseconds()}}. These objects can be added to and
87subtracted to date- times to create a user interface similar to object
88oriented programming.
89}
90\examples{
91
92### Separate period and units vectors
93
94duration(90, "seconds")
95duration(1.5, "minutes")
96duration(-1, "days")
97
98### Units as arguments
99
100duration(day = -1)
101duration(second = 90)
102duration(minute = 1.5)
103duration(mins = 1.5)
104duration(second = 3, minute = 1.5, hour = 2, day = 6, week = 1)
105duration(hour = 1, minute = -60)
106
107### Parsing
108
109duration("2M 1sec")
110duration("2hours 2minutes 1second")
111duration("2d 2H 2M 2S")
112duration("2days 2hours 2mins 2secs")
113# Missing numerals default to 1. Repeated units are added up.
114duration("day day")
115
116### ISO 8601 parsing
117
118duration("P3Y6M4DT12H30M5S")
119duration("P23DT23H") # M stands for months
120duration("10DT10M") # M stands for minutes
121duration("P23DT60H 20min 100 sec") # mixing ISO and lubridate style parsing
122
123# Comparison with characters (from v1.6.0)
124
125duration("day 2 sec") > "day 1sec"
126
127
128## ELEMENTARY CONSTRUCTORS:
129
130dseconds(1)
131dminutes(3.5)
132
133x <- ymd("2009-08-03", tz = "America/Chicago")
134x + ddays(1) + dhours(6) + dminutes(30)
135x + ddays(100) - dhours(8)
136
137class(as.Date("2009-08-09") + ddays(1)) # retains Date class
138as.Date("2009-08-09") + dhours(12)
139class(as.Date("2009-08-09") + dhours(12))
140# converts to POSIXt class to accomodate time units
141
142dweeks(1) - ddays(7)
143c(1:3) * dhours(1)
144
145# compare DST handling to durations
146boundary <- ymd_hms("2009-03-08 01:59:59", tz = "America/Chicago")
147boundary + days(1) # period
148boundary + ddays(1) # duration
149is.duration(as.Date("2009-08-03")) # FALSE
150is.duration(duration(days = 12.4)) # TRUE
151}
152\seealso{
153\code{\link[=as.duration]{as.duration()}} \linkS4class{Duration}
154}
155\keyword{chron}
156\keyword{classes}
157