Permalink
Browse files

Added timezone examples for common Olson timezones. Fixes #79.

  • Loading branch information...
1 parent 453d056 commit 924cc0978a5d764e5c6280e21039ada5688142ad @garrettgman garrettgman committed Oct 2, 2012
Showing with 59 additions and 8 deletions.
  1. +28 −4 R/accessors-tz.r
  2. +31 −4 man/tz.Rd
View
@@ -1,7 +1,14 @@
#' Get/set time zone component of a date-time.
#'
-#' Date-time must be a POSIXct, POSIXlt, Date, chron, yearmon, yearqtr, zoo,
-#' zooreg, timeDate, xts, its, ti, jul, timeSeries, and fts objects.
+#' Time zones are stored as character strings in an
+#' attribute of date-time objects. tz returns a date's time zone attribute.
+#' When used as a settor, it changes the time zone attribute. R does not come with
+#' a predefined list zone names, but relies on the user's OS to interpret time zone
+#' names. As a result, some names will be recognized on some computers but not others.
+#' Most computers, however, will recognize names in the timezone data base originally
+#' compiled by Arthur Olson. These names normally take the form "Country/City." A
+#' convenient listing of these timezones can be found at
+#' \url{http://en.wikipedia.org/wiki/List_of_tz_database_time_zones}.
#'
#' Setting tz does not update a date-time to display the same moment as measured
#' at a different time zone. See \code{\link{with_tz}}. Setting a new time zone
@@ -13,15 +20,18 @@
#' chron, then R will update the number in the hours element to display the new
#' date-time in the GMT timezone.
#'
-#' For a description of the time zone attribute, see \code{\link[base]{DateTimeClasses}}.
+#' For a description of the time zone attribute, see \code{\link[base]{timezones}}
+#' or \code{\link[base]{DateTimeClasses}}.
#'
#' @export tz "tz<-"
#' @aliases tz tz<-
#' @S3method tz default
#' @S3method tz zoo
#' @S3method tz timeSeries
#' @S3method tz irts
-#' @param x a date-time object
+#' @param x a date-time object of class a POSIXct, POSIXlt, Date, chron, yearmon,
+#' yearqtr, zoo, zooreg, timeDate, xts, its, ti, jul, timeSeries, fts or anything else that can
+#' be coerced to POSIXlt with as.POSIXlt
#' @return the first element of x's tzone attribute vector as a character string. If no tzone
#' attribute exists, tz returns "GMT".
#' @keywords utilities manip chron methods
@@ -30,8 +40,22 @@
#' tz(x)
#' tz(x) <- "GMT"
#' x
+#' \dontrun{
#' tz(x) <- "America/New_York"
#' x
+#' tz(x) <- "America/Chicago"
+#' x
+#' tz(x) <- "America/Los_Angeles"
+#' x
+#' tz(x) <- "Pacific/Honolulu"
+#' x
+#' tz(x) <- "Pacific/Auckland"
+#' x
+#' tz(x) <- "Europe/London"
+#' x
+#' tz(x) <- "Europe/Berlin"
+#' x
+#' }
#' Sys.setenv(TZ = "GMT")
#' now()
#' tz(now())
View
@@ -6,17 +6,29 @@
tz(x)
}
\arguments{
- \item{x}{a date-time object}
+ \item{x}{a date-time object of class a POSIXct, POSIXlt,
+ Date, chron, yearmon, yearqtr, zoo, zooreg, timeDate,
+ xts, its, ti, jul, timeSeries, fts or anything else that
+ can be coerced to POSIXlt with as.POSIXlt}
}
\value{
the first element of x's tzone attribute vector as a
character string. If no tzone attribute exists, tz
returns "GMT".
}
\description{
- Date-time must be a POSIXct, POSIXlt, Date, chron,
- yearmon, yearqtr, zoo, zooreg, timeDate, xts, its, ti,
- jul, timeSeries, and fts objects.
+ Time zones are stored as character strings in an
+ attribute of date-time objects. tz returns a date's time
+ zone attribute. When used as a settor, it changes the
+ time zone attribute. R does not come with a predefined
+ list zone names, but relies on the user's OS to interpret
+ time zone names. As a result, some names will be
+ recognized on some computers but not others. Most
+ computers, however, will recognize names in the timezone
+ data base originally compiled by Arthur Olson. These
+ names normally take the form "Country/City." A convenient
+ listing of these timezones can be found at
+ \url{http://en.wikipedia.org/wiki/List_of_tz_database_time_zones}.
}
\details{
Setting tz does not update a date-time to display the
@@ -33,15 +45,30 @@
in the GMT timezone.
For a description of the time zone attribute, see
+ \code{\link[base]{timezones}} or
\code{\link[base]{DateTimeClasses}}.
}
\examples{
x <- ymd("2012-03-26")
tz(x)
tz(x) <- "GMT"
x
+\dontrun{
tz(x) <- "America/New_York"
x
+tz(x) <- "America/Chicago"
+x
+tz(x) <- "America/Los_Angeles"
+x
+tz(x) <- "Pacific/Honolulu"
+x
+tz(x) <- "Pacific/Auckland"
+x
+tz(x) <- "Europe/London"
+x
+tz(x) <- "Europe/Berlin"
+x
+}
Sys.setenv(TZ = "GMT")
now()
tz(now())

0 comments on commit 924cc09

Please sign in to comment.