Documented S4version of lubridate with roxygen2

1 parent f98d52d commit 949c648cb995ff2b9f74c184a377e67f830d3036 garrettgman committed Feb 13, 2012
 @@ -1,8 +1,8 @@ \name{DateCoercion} \alias{DateCoercion} -\title{Convert every date method we know about to POSIXlt and POSIXct} +\title{Convert a variety of date-time classes to POSIXlt and POSIXct} \description{ - Convert every date method we know about to POSIXlt and + Convert a variety of date-time classes to POSIXlt and POSIXct } \keyword{internal}
 @@ -43,9 +43,9 @@ 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. + months and years. This is because the exact length of + larger time units can be affected by conventions such as + leap years and Daylight Savings Time. } \details{ Durations provide a method for measuring generalized
 @@ -49,9 +49,10 @@ The exact length of a period is not defined until the period is placed at a specific moment of time. This is because the precise length of one year, month, day, etc. - can change depending on when it occurs. A period can be - associated with a specific moment in time by coercing it - to an \code{\link{Interval-class}} object with + can change depending on when it occurs due to daylight + savings, leap years, and other conventions. A period can + be associated with a specific moment in time by coercing + it to an \code{\link{Interval-class}} object with \code{\link{as.interval}} or by adding it to a date-time with "+".
 @@ -16,9 +16,9 @@ A duration object } \description{ - as.duration changes interval, period and numeric objects - to duration objects. Numeric objects are changed to - duration objects with the seconds unit equal to the + as.duration changes Interval, Period and numeric class + objects to Duration objects. Numeric objects are changed + to Duration objects with the seconds unit equal to the numeric value. } \details{ @@ -29,17 +29,18 @@ does not exist between durations and periods. When used with a period object, as.duration provides an inexact estimate of the length of the period; each time unit is - assigned its most common number of seconds. Periods with - a months unit cannot be coerced to durations because of - the variability of month lengths. For an exact - transformation, first transform the period to an interval - with \code{\link{as.interval}}. + assigned its most common number of seconds. A period of + one month is converted to 2628000 seconds (approximately + 30.42 days). This ensures that 12 months will sum to 365 + days, or one normal year. For an exact transformation, + first transform the period to an interval with + \code{\link{as.interval}}. } \examples{ -span <- new_interval(ymd("2009-01-01"), ymd("2009-08-01")) #interval -# 2009-01-01 -- 2009-08-01 +span <- interval(ymd("2009-01-01"), ymd("2009-08-01")) #interval +# "2009-01-01 UTC--2009-08-01 UTC" as.duration(span) -# 18316800s (212d) +# 18316800s (~212 days) as.duration(10) # numeric # 10s }
 @@ -5,8 +5,8 @@ as.interval(x, start) } \arguments{ - \item{x}{a duration (i.e. difftime), period, or numeric - object that describes the length of the interval} + \item{x}{a duration, difftime, period, or numeric object + that describes the length of the interval} \item{start}{a POSIXt or Date object that describes when the interval begins} @@ -15,15 +15,15 @@ an interval object } \description{ - as.interval changes difftime, duration, period and - numeric objects to intervals that begin at the specified - date-time. Numeric objects are first coerced to time - spans equal to the numeric value in seconds. + as.interval changes difftime, Duration, Period and + numeric class objects to intervals that begin at the + specified date-time. Numeric objects are first coerced to + timespans equal to the numeric value in seconds. } \details{ as.interval can be used to create accurate - transformations between period objects, which measure - time spans in variable length units, and difftime + transformations between Period objects, which measure + time spans in variable length units, and Duration objects, which measure timespans as an exact number of seconds. A start date- time must be supplied to make the conversion. Lubridate uses this start date to look up how @@ -34,24 +34,24 @@ \examples{ diff <- new_difftime(days = 31) #difftime as.interval(diff, ymd("2009-01-01")) -# 2009-01-01 -- 2009-02-01 +# 2009-01-01 UTC--2009-02-01 UTC as.interval(diff, ymd("2009-02-01")) -# 2009-02-01 -- 2009-03-04 +# 2009-02-01 UTC--2009-03-04 UTC dur <- new_duration(days = 31) #duration as.interval(dur, ymd("2009-01-01")) -# 2009-01-01 -- 2009-02-01 +# 2009-01-01 UTC--2009-02-01 UTC as.interval(dur, ymd("2009-02-01")) -# 2009-02-01 -- 2009-03-04 +# 2009-02-01 UTC--2009-03-04 UTC per <- new_period(months = 1) #period as.interval(per, ymd("2009-01-01")) -# 2009-01-01 -- 2009-02-01 +# 2009-01-01 UTC--2009-02-01 UTC as.interval(per, ymd("2009-02-01")) -# 2009-02-01 -- 2009-03-01 +# 2009-02-01 UTC--2009-03-01 UTC as.interval(3600, ymd("2009-01-01")) #numeric -# 2009-01-01 -- 2009-01-01 01:00:00 +# 2009-01-01 UTC--2009-01-01 01:00:00 UTC } \seealso{ \code{\link{interval}}, \code{\link{new_interval}}
 @@ -18,26 +18,26 @@ a period object } \description{ - as.period changes interval, duration (i.e., difftime) and - numeric objects to period objects with the specified - units. + as.period changes Interval, Duration, difftime and + numeric class objects to Period class objects with the + specified units. } \details{ Users must specify which time units to measure the period - in. The length of each time unit in a period depends on - when it occurs. See \code{\link{Period-class}} and - \code{\link{new_period}}. The choice of units is not + in. The exact length of each time unit in a period will + depend on when it occurs. See \code{\link{Period-class}} + and \code{\link{new_period}}. The choice of units is not trivial; units that are normally equal may differ in length depending on when the time period occurs. For example, when a leap second occurs one minute is longer than 60 seconds. Because periods do not have a fixed length, they can not - be accurately converted to and from duration objects. + be accurately converted to and from Duration objects. Duration objects measure time spans in exact numbers of seconds, see \code{\link{Duration-class}}. Hence, a one to one mapping does not exist between durations and - periods. When used with a duration object, as.period + periods. When used with a Duration object, as.period provides an inexact estimate; the duration is broken into time units based on the most common lengths of time units, in seconds. Because the length of months are @@ -48,7 +48,7 @@ } \examples{ span <- new_interval(as.POSIXct("2009-01-01"), as.POSIXct("2010-02-02 01:01:01")) #interval -# [1] 2009-01-01 -- 2010-02-02 01:01:01 +# 2009-01-01 CST--2010-02-02 01:01:01 CST as.period(span) # 1 year, 1 month, 1 day, 1 hour, 1 minute and 1 second }
 @@ -31,9 +31,9 @@ a duration object } \description{ - Quickly create duration objects for easy date-time + Quickly create Duration objects for easy date-time manipulation. The units of the duration created depend on - the name of the function called. For duration objects, + the name of the function called. For Duration objects, units are equal to their most common lengths in seconds (i.e. minutes = 60 seconds, hours = 3600 seconds, days = 86400 seconds, weeks = 604800, years = 31536000). @@ -48,7 +48,7 @@ dseconds(1) # 1s dminutes(3.5) -# 210s +# 210s (~3.5 minutes) x <- as.POSIXct("2009-08-03") # "2009-08-03 CDT" @@ -62,13 +62,13 @@ class(as.Date("2009-08-09") + ddays(1)) # retains Date class as.Date("2009-08-09") + dhours(12) # "2009-08-09 12:00:00 UTC" class(as.Date("2009-08-09") + dhours(12)) -# "POSIXt" "POSIXct" +# "POSIXct" "POSIXt" # converts to POSIXt class to accomodate time units dweeks(1) - ddays(7) # 0s c(1:3) * dhours(1) -# 3600s 7200s 10800s +# 3600s (~1 hours) 7200s (~2 hours) 10800s (~3 hours) # # compare DST handling to durations boundary <- as.POSIXct("2009-03-08 01:59:59")
 @@ -23,8 +23,6 @@ hms(x) # [1] 9 hours, 10 minutes and 1 second 9 hours, 10 minutes and 2 seconds 9 hours, 10 minutes and 3 seconds hms("7 6 5") # [1] 7 hours, 6 minutes and 5 seconds -hms("7,6,5") -# [1] 7 hours, 6 minutes and 5 seconds } \seealso{ \code{\link{hm}, \link{ms}}
 @@ -10,10 +10,25 @@ \item{int2}{an Interval object} } \value{ - Logical. TRUE if int1 and int2 at least one endpoint in - any combination. FALSE otherwise. + Logical. TRUE if int1 and int2 begin or end on the same + moment. FALSE otherwise. } \description{ - Test if two intervals share an endpoint + int_aligns tests for the case where two intervals begin + or end at the same moment when arranged chronologically. + The direction of each interval is ignored. int_align + tests whether the earliest or latest moments of each + interval occur at the same time. +} +\examples{ +int1 <- new_interval(ymd("2001-01-01"), ymd("2002-01-01")) +# 2001-01-01 UTC--2002-01-01 UTC +int2 <- new_interval(ymd("2001-06-01"), ymd("2002-01-01")) +# 2001-06-01 UTC--2002-01-01 UTC +int3 <- new_interval(ymd("2003-01-01"), ymd("2004-01-01")) +# 2003-01-01 UTC--2004-01-01 UTC + +int_aligns(int1, int2) # TRUE +int_aligns(int1, int3) # FALSE }
 @@ -19,12 +19,12 @@ } \examples{ int <- new_interval(ymd("2001-01-01"), ymd("2002-01-01")) -# 2001-01-01 -- 2002-01-01 +# 2001-01-01 UTC--2002-01-01 UTC int_end(int) # "2002-01-01 UTC" int_end(int) <- ymd("2002-06-01") int -# 2001-06-01 -- 2002-06-01 +# 2001-01-01 UTC--2002-06-01 UTC } \seealso{ \code{\link{int_start}}, \code{\link{int_shift}},
 @@ -16,6 +16,12 @@ timespan as the original interval, but has the opposite direction. } +\examples{ +int <- new_interval(ymd("2001-01-01"), ymd("2002-01-01")) +# 2001-01-01 UTC--2002-01-01 UTC +int_flip(int) +# 2002-01-01 UTC--2001-01-01 UTC +} \seealso{ \code{\link{int_shift}}, \code{\link{int_start}}, \code{\link{int_end}}
 @@ -16,4 +16,15 @@ \description{ Test if two intervals overlap } +\examples{ +int1 <- new_interval(ymd("2001-01-01"), ymd("2002-01-01")) +# 2001-01-01 UTC--2002-01-01 UTC +int2 <- new_interval(ymd("2001-06-01"), ymd("2002-06-01")) +# 2001-06-01 UTC--2002-06-01 UTC +int3 <- new_interval(ymd("2003-01-01"), ymd("2004-01-01")) +# 2003-01-01 UTC--2004-01-01 UTC + +int_overlaps(int1, int2) # TRUE +int_overlaps(int1, int3) # FALSE +}
 @@ -15,7 +15,18 @@ \description{ Shifts the start and end dates of an interval up or down the timeline by a specified amount. Note that this may - change the exact length of the interval. + change the exact length of the interval if the interval + is shifted by a Period object. Intervals shifted by a + Duration or difftime object will retain their exact + length in seconds. +} +\examples{ +int <- new_interval(ymd("2001-01-01"), ymd("2002-01-01")) +# 2001-01-01 UTC--2002-01-01 UTC +int_shift(int, duration(days = 11)) +# 2001-01-12 UTC--2002-01-12 UTC +int_shift(int, duration(hours = -1)) +# 2000-12-31 23:00:00 UTC--2001-12-31 23:00:00 UTC } \seealso{ \code{\link{int_flip}}, \code{\link{int_start}},
 @@ -11,4 +11,10 @@ If an interval is not positive, int_standardize flips it so that it retains its endpoints but becomes positive. } +\examples{ +int <- new_interval(ymd("2002-01-01"), ymd("2001-01-01")) +# 2002-01-01 UTC--2001-01-01 UTC +int_standardize(int) +# 2001-01-01 UTC--2002-01-01 UTC +}
 @@ -19,12 +19,12 @@ } \examples{ int <- new_interval(ymd("2001-01-01"), ymd("2002-01-01")) -# 2001-01-01 -- 2002-01-01 +# 2001-01-01 UTC--2002-01-01 UTC int_start(int) # "2001-01-01 UTC" int_start(int) <- ymd("2001-06-01") int -# 2001-06-01 -- 2002-06-01 +# 2001-06-01 UTC--2002-01-01 UTC } \seealso{ \code{\link{int_end}}, \code{\link{int_shift}},