Permalink
Browse files

Documented S4version of lubridate with roxygen2

  • Loading branch information...
1 parent f98d52d commit 949c648cb995ff2b9f74c184a377e67f830d3036 @garrettgman garrettgman committed Feb 13, 2012
View
@@ -136,9 +136,9 @@
#' Functions for working with intervals include
#' \code{\link{is.interval}}, \code{\link{as.interval}},
#' \code{\link{new_interval}}, \code{\link{int_shift}},
-#' \code{\link{int_flip}}, \code{\link{int_align}},
-#' \code{\link{int_overlaps}}, \code{\link{%--%}}, and
-#' \code{\link{%within%}}. Intervals can also be manipulated with
+#' \code{\link{int_flip}}, \code{\link{int_aligns}},
+#' \code{\link{int_overlaps}}, and
+#' \code{\link{\%within\%}}. Intervals can also be manipulated with
#' intersect, union, and setdiff().
#'
#' Miscellaneous
View
@@ -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
View
@@ -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 "+".
View
@@ -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
}
View
@@ -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}}
View
@@ -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
}
View
@@ -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")
View
@@ -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}}
View
@@ -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
}
View
@@ -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}},
View
@@ -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}}
View
@@ -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
+}
View
@@ -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
+}
View
@@ -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}},
Oops, something went wrong.

0 comments on commit 949c648

Please sign in to comment.