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