Browse files

redocumented package after vitoshka's pull request

  • Loading branch information...
1 parent e535001 commit 6807a20127d77b7bb1751978cc51697e8bd591a4 @garrettgman garrettgman committed Sep 14, 2012
View
52 man/Duration-class.Rd
@@ -1,39 +1,39 @@
\name{Duration-class}
-\alias{-,ANY,Duration-method}
+\alias{$,Duration-method}
+\alias{$<-,Duration-method}
\alias{*,ANY,Duration-method}
-\alias{as.difftime,Duration-method}
-\alias{as.numeric,Duration-method}
-\alias{c,Duration-method}
-\alias{+,Date,Duration-method}
-\alias{/,difftime,Duration-method}
-\alias{+,difftime,Duration-method}
-\alias{[<-,Duration,ANY-method}
\alias{*,Duration,ANY-method}
-\alias{Duration-class}
+\alias{+,Date,Duration-method}
\alias{+,Duration,Date-method}
-\alias{/,Duration,difftime-method}
-\alias{+,Duration,difftime-method}
-\alias{/,Duration,Duration-method}
-\alias{\%\%,Duration,Duration-method}
\alias{+,Duration,Duration-method}
-\alias{/,Duration,Interval-method}
-\alias{\%\%,Duration,Interval-method}
\alias{+,Duration,Interval-method}
-\alias{[,Duration-method}
-\alias{$<-,Duration-method}
-\alias{$,Duration-method}
-\alias{-,Duration,missing-method}
-\alias{/,Duration,numeric-method}
-\alias{+,Duration,numeric-method}
-\alias{/,Duration,Period-method}
-\alias{\%\%,Duration,Period-method}
-\alias{+,Duration,Period-method}
\alias{+,Duration,POSIXct-method}
\alias{+,Duration,POSIXlt-method}
-\alias{/,numeric,Duration-method}
-\alias{+,numeric,Duration-method}
+\alias{+,Duration,Period-method}
+\alias{+,Duration,difftime-method}
+\alias{+,Duration,numeric-method}
\alias{+,POSIXct,Duration-method}
\alias{+,POSIXlt,Duration-method}
+\alias{+,difftime,Duration-method}
+\alias{+,numeric,Duration-method}
+\alias{-,ANY,Duration-method}
+\alias{-,Duration,missing-method}
+\alias{/,Duration,Duration-method}
+\alias{/,Duration,Interval-method}
+\alias{/,Duration,Period-method}
+\alias{/,Duration,difftime-method}
+\alias{/,Duration,numeric-method}
+\alias{/,difftime,Duration-method}
+\alias{/,numeric,Duration-method}
+\alias{Duration-class}
+\alias{[,Duration-method}
+\alias{[<-,Duration,ANY-method}
+\alias{\%\%,Duration,Duration-method}
+\alias{\%\%,Duration,Interval-method}
+\alias{\%\%,Duration,Period-method}
+\alias{as.difftime,Duration-method}
+\alias{as.numeric,Duration-method}
+\alias{c,Duration-method}
\alias{rep,Duration-method}
\alias{show,Duration-method}
\title{Duration class}
View
72 man/Interval-class.Rd
@@ -1,50 +1,50 @@
\name{Interval-class}
+\alias{$,Interval-method}
+\alias{$<-,Interval-method}
\alias{*,ANY,Interval-method}
-\alias{as.difftime,Interval-method}
-\alias{as.numeric,Interval-method}
-\alias{c,Interval-method}
-\alias{-,Date,Interval-method}
-\alias{+,Date,Interval-method}
-\alias{/,difftime,Interval-method}
-\alias{+,difftime,Interval-method}
-\alias{-,Duration,Interval-method}
-\alias{intersect,Interval,Interval-method}
-\alias{[<-,Interval,ANY-method}
\alias{*,Interval,ANY-method}
-\alias{Interval-class}
-\alias{-,Interval,Date-method}
+\alias{+,Date,Interval-method}
\alias{+,Interval,Date-method}
-\alias{/,Interval,difftime-method}
-\alias{+,Interval,difftime-method}
-\alias{/,Interval,Duration-method}
-\alias{\%\%,Interval,Duration-method}
\alias{+,Interval,Duration-method}
-\alias{-,Interval,Interval-method}
-\alias{/,Interval,Interval-method}
-\alias{\%\%,Interval,Interval-method}
\alias{+,Interval,Interval-method}
-\alias{[,Interval-method}
-\alias{$<-,Interval-method}
-\alias{$,Interval-method}
-\alias{-,Interval,missing-method}
-\alias{-,Interval,numeric-method}
-\alias{/,Interval,numeric-method}
-\alias{+,Interval,numeric-method}
-\alias{/,Interval,Period-method}
-\alias{\%\%,Interval,Period-method}
-\alias{+,Interval,Period-method}
-\alias{-,Interval,POSIXct-method}
\alias{+,Interval,POSIXct-method}
-\alias{-,Interval,POSIXlt-method}
\alias{+,Interval,POSIXlt-method}
-\alias{-,numeric,Interval-method}
-\alias{/,numeric,Interval-method}
+\alias{+,Interval,Period-method}
+\alias{+,Interval,difftime-method}
+\alias{+,Interval,numeric-method}
+\alias{+,POSIXct,Interval-method}
+\alias{+,POSIXlt,Interval-method}
+\alias{+,difftime,Interval-method}
\alias{+,numeric,Interval-method}
-\alias{-,Period,Interval-method}
+\alias{-,Date,Interval-method}
+\alias{-,Duration,Interval-method}
+\alias{-,Interval,Date-method}
+\alias{-,Interval,Interval-method}
+\alias{-,Interval,POSIXct-method}
+\alias{-,Interval,POSIXlt-method}
+\alias{-,Interval,missing-method}
+\alias{-,Interval,numeric-method}
\alias{-,POSIXct,Interval-method}
-\alias{+,POSIXct,Interval-method}
\alias{-,POSIXlt,Interval-method}
-\alias{+,POSIXlt,Interval-method}
+\alias{-,Period,Interval-method}
+\alias{-,numeric,Interval-method}
+\alias{/,Interval,Duration-method}
+\alias{/,Interval,Interval-method}
+\alias{/,Interval,Period-method}
+\alias{/,Interval,difftime-method}
+\alias{/,Interval,numeric-method}
+\alias{/,difftime,Interval-method}
+\alias{/,numeric,Interval-method}
+\alias{Interval-class}
+\alias{[,Interval-method}
+\alias{[<-,Interval,ANY-method}
+\alias{\%\%,Interval,Duration-method}
+\alias{\%\%,Interval,Interval-method}
+\alias{\%\%,Interval,Period-method}
+\alias{as.difftime,Interval-method}
+\alias{as.numeric,Interval-method}
+\alias{c,Interval-method}
+\alias{intersect,Interval,Interval-method}
\alias{rep,Interval-method}
\alias{setdiff,Interval,Interval-method}
\alias{show,Interval-method}
View
82 man/Period-class.Rd
@@ -1,57 +1,57 @@
\name{Period-class}
-\alias{-,ANY,Period-method}
-\alias{*,ANY,Period-method}
-\alias{as.difftime,Period-method}
-\alias{as.numeric,Period-method}
-\alias{c,Period-method}
-\alias{+,Date,Period-method}
-\alias{/,difftime,Period-method}
-\alias{+,difftime,Period-method}
-\alias{<=,Duration,Period-method}
-\alias{<,Duration,Period-method}
-\alias{==,Duration,Period-method}
-\alias{>=,Duration,Period-method}
-\alias{>,Duration,Period-method}
\alias{!=,Duration,Period-method}
-\alias{/,numeric,Period-method}
-\alias{+,numeric,Period-method}
+\alias{!=,Period,Duration-method}
+\alias{!=,Period,Period-method}
+\alias{$,Period-method}
+\alias{$<-,Period-method}
+\alias{*,ANY,Period-method}
\alias{*,Period,ANY-method}
-\alias{Period-class}
+\alias{+,Date,Period-method}
+\alias{+,POSIXct,Period-method}
+\alias{+,POSIXlt,Period-method}
\alias{+,Period,Date-method}
-\alias{/,Period,difftime-method}
-\alias{+,Period,difftime-method}
-\alias{<=,Period,Duration-method}
-\alias{<,Period,Duration-method}
-\alias{==,Period,Duration-method}
-\alias{>=,Period,Duration-method}
-\alias{>,Period,Duration-method}
-\alias{!=,Period,Duration-method}
-\alias{/,Period,Duration-method}
-\alias{\%\%,Period,Duration-method}
\alias{+,Period,Duration-method}
-\alias{/,Period,Interval-method}
-\alias{\%\%,Period,Interval-method}
\alias{+,Period,Interval-method}
-\alias{[,Period-method}
-\alias{$<-,Period-method}
-\alias{$,Period-method}
+\alias{+,Period,POSIXct-method}
+\alias{+,Period,POSIXlt-method}
+\alias{+,Period,Period-method}
+\alias{+,Period,difftime-method}
+\alias{+,Period,numeric-method}
+\alias{+,difftime,Period-method}
+\alias{+,numeric,Period-method}
+\alias{-,ANY,Period-method}
\alias{-,Period,missing-method}
+\alias{/,Period,Duration-method}
+\alias{/,Period,Interval-method}
+\alias{/,Period,Period-method}
+\alias{/,Period,difftime-method}
\alias{/,Period,numeric-method}
-\alias{+,Period,numeric-method}
-\alias{<=,Period,Period-method}
+\alias{/,difftime,Period-method}
+\alias{/,numeric,Period-method}
+\alias{<,Duration,Period-method}
+\alias{<,Period,Duration-method}
\alias{<,Period,Period-method}
+\alias{<=,Duration,Period-method}
+\alias{<=,Period,Duration-method}
+\alias{<=,Period,Period-method}
+\alias{==,Duration,Period-method}
+\alias{==,Period,Duration-method}
\alias{==,Period,Period-method}
-\alias{>=,Period,Period-method}
+\alias{>,Duration,Period-method}
+\alias{>,Period,Duration-method}
\alias{>,Period,Period-method}
-\alias{!=,Period,Period-method}
-\alias{/,Period,Period-method}
+\alias{>=,Duration,Period-method}
+\alias{>=,Period,Duration-method}
+\alias{>=,Period,Period-method}
+\alias{Period-class}
+\alias{[,Period-method}
\alias{[<-,Period,Period-method}
+\alias{\%\%,Period,Duration-method}
+\alias{\%\%,Period,Interval-method}
\alias{\%\%,Period,Period-method}
-\alias{+,Period,Period-method}
-\alias{+,Period,POSIXct-method}
-\alias{+,Period,POSIXlt-method}
-\alias{+,POSIXct,Period-method}
-\alias{+,POSIXlt,Period-method}
+\alias{as.difftime,Period-method}
+\alias{as.numeric,Period-method}
+\alias{c,Period-method}
\alias{rep,Period-method}
\alias{show,Period-method}
\title{Period class}
View
2 man/Timespan-class.Rd
@@ -1,6 +1,6 @@
\name{Timespan-class}
-\alias{Timespan-class}
\alias{*,Timespan,Timespan-method}
+\alias{Timespan-class}
\alias{\%/\%,Timespan,Timespan-method}
\title{Timespan class}
\description{
View
4 man/as.duration.Rd
@@ -1,10 +1,10 @@
\name{as.duration}
\alias{as.duration}
-\alias{as.duration,difftime-method}
\alias{as.duration,Duration-method}
\alias{as.duration,Interval-method}
-\alias{as.duration,numeric-method}
\alias{as.duration,Period-method}
+\alias{as.duration,difftime-method}
+\alias{as.duration,numeric-method}
\title{Change an object to a duration.}
\usage{
as.duration(x)
View
4 man/as.period.Rd
@@ -1,10 +1,10 @@
\name{as.period}
\alias{as.period}
-\alias{as.period,difftime-method}
\alias{as.period,Duration-method}
\alias{as.period,Interval-method}
-\alias{as.period,numeric-method}
\alias{as.period,Period-method}
+\alias{as.period,difftime-method}
+\alias{as.period,numeric-method}
\title{Change an object to a period.}
\usage{
as.period(x, unit, ...)
View
87 man/guess_formats.Rd
@@ -0,0 +1,87 @@
+\name{guess_formats}
+\alias{guess_formats}
+\title{Guess formats from the supplied date-time character vector.}
+\usage{
+ guess_formats(x, orders,
+ locale = Sys.getlocale("LC_TIME"), preproc_wday = TRUE,
+ print_matches = FALSE)
+}
+\arguments{
+ \item{x}{input vector of date-times}
+
+ \item{orders}{format orders to look for. See details.}
+
+ \item{locale}{locale to use, default to the current
+ locale (also checks en_US)}
+
+ \item{preproc_wday}{whether to preprocess weak days
+ names. Internal optimization used by ymd_hms family of
+ functions. If true weak days are substituted with %a or
+ %A accordingly, so that there is no need to supply this
+ format explicitely.}
+
+ \item{print_matches}{for development purpose mainly. If
+ TRUE prints a matrix of matched templates.}
+}
+\value{
+ a vector of matched formats
+}
+\description{
+ Guess formats from the supplied date-time character
+ vector.
+}
+\examples{
+x <- c('February 20th 1973',
+ "february 14, 2004",
+ "Sunday, May 1, 2000",
+ "Sunday, May 1, 2000",
+ "february 14, 04",
+ 'Feb 20th 73',
+ "January 5 1999 at 7pm",
+ "jan 3 2010",
+ "Jan 1, 1999",
+ "jan 3 10",
+ "01 3 2010",
+ "1 3 10",
+ '1 13 89',
+ "5/27/1979",
+ "12/31/99",
+ "DOB:12/11/00",
+ "-----------",
+ 'Thu, 1 July 2004 22:30:00',
+ 'Thu, 1st of July 2004 at 22:30:00',
+ 'Thu, 1July 2004 at 22:30:00',
+ 'Thu, 1July2004 22:30:00',
+ 'Thu, 1July04 22:30:00',
+ "21 Aug 2011, 11:15:34 pm",
+ "-----------",
+ "1979-05-27 05:00:59",
+ "1979-05-27",
+ "-----------",
+ "3 jan 2000",
+ "17 april 85",
+ "27/5/1979",
+ '20 01 89',
+ '00/13/10',
+ "-------",
+ "14 12 00",
+ "03:23:22 pm")
+
+guess_formats(x, "BdY")
+guess_formats(x, "Bdy")
+## m also matches b and B; y also matches Y
+guess_formats(x, "mdy", print_matches = TRUE)
+
+## T also matches IMSp order
+guess_formats(x, "T", print_matches = TRUE)
+
+## b and B are equivalent and match, both, abreviated and full names
+guess_formats(x, c("mdY", "BdY", "Bdy", "bdY", "bdy"), print_matches = TRUE)
+guess_formats(x, c("dmy", "dbY", "dBy", "dBY"), print_matches = TRUE)
+
+
+guess_formats(x, c("dBY HMS", "dbY HMS", "dmyHMS", "BdY H"), print_matches = TRUE)
+
+guess_formats(x, c("ymd HMS"), print_matches = TRUE)
+}
+
View
3 man/hm.Rd
@@ -14,8 +14,7 @@
\description{
Transforms a character or numeric vectors into a period
object with the specified number of hours and minutes.
- hm() recognizes all non-alphanumeric separators, and no
- separator.
+ Arbitrary text can separate hours and minutes.
}
\examples{
x <- c("09:10", "09:02", "1:10")
View
8 man/hms.Rd
@@ -2,14 +2,14 @@
\alias{hms}
\title{Create a period with the specified hours, minutes, and seconds}
\usage{
- hms(..., missing = 0, frac = FALSE)
+ hms(..., truncated = 0)
}
\arguments{
\item{...}{a character vector of hour minute second
triples}
- \item{missing}{integer, number of formats that can be
- missing. See \code{\link{parseDateTime}}.}
+ \item{truncated}{integer, number of formats that can be
+ missing. See \code{\link{parse_date_time}}.}
\item{frac}{If \code{TRUE}, fractional seconds are
allowed. It is assumed that fractional seconds are
@@ -26,7 +26,7 @@
separators, as well as no separator.
}
\examples{
-x <- c("09:10:01", "09:10:02", "09:10:03")
+x <- c("09:10:01", "09:10:02", "09:10:03", "Collided at 9:20:04 pm")
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", "3-23---2", "2 : 23 : 33")
View
7 man/lubridate_formats.Rd
@@ -1,20 +1,21 @@
\docType{data}
\name{lubridate_formats}
\alias{lubridate_formats}
-\title{Lubridate formats used in \code{ymd}, \code{hms} and \code{ymd_hms} family of functions.}
+\title{Lubridate format orders used in \code{ymd}, \code{hms} and \code{ymd_hms}
+family of functions.}
\format{Named list with formats.}
\usage{
lubridate_formats
}
\description{
- These formats are passed to \code{parseDateTime} low
+ These orders are passed to \code{parse_date_time} low
level parsing function.
}
\examples{
str(lubridate_formats)
}
\seealso{
- \code{\link{parseDateTime}}, \code{\link{ymd}},
+ \code{\link{parse_date_time}}, \code{\link{ymd}},
\code{\link{ymd_hms}}
}
\keyword{chron}
View
11 man/ms.Rd
@@ -2,25 +2,20 @@
\alias{ms}
\title{Create a period with the specified number of minutes and seconds}
\usage{
- ms(..., frac = FALSE)
+ ms(...)
}
\arguments{
\item{...}{character or numeric vectors of minute second
pairs}
-
- \item{frac}{If \code{TRUE}, fractional seconds are
- allowed. It is assumed that fractional seconds are
- separated by ".". If \code{TRUE}, "." cannot be used as a
- separator between minutes and seconds.}
}
\value{
a vector of class \code{Period}
}
\description{
Transforms character or numeric vectors into a period
object with the specified number of minutes and seconds.
- ms() recognizes all non-alphanumeric separators as well
- as no separator.
+ ms() Arbitrary text can separate minutes and seconds.
+ Fractional separator is assumed to be ".".
}
\examples{
x <- c("09:10", "09:02", "1:10")
View
8 man/new_interval.Rd
@@ -33,10 +33,10 @@
time units that occurred during the interval can be
calculated.
- \%--\% Creates an interval that covers the range spanned
- by two dates. It replaces the original behavior of
- lubridate, which created an interval by default whenever
- two date-times were subtracted.
+ \code{\%--\%} Creates an interval that covers the range
+ spanned by two dates. It replaces the original behavior
+ of lubridate, which created an interval by default
+ whenever two date-times were subtracted.
}
\examples{
new_interval(ymd(20090201), ymd(20090101))
View
4 man/parse_date.Rd
@@ -1,6 +1,6 @@
\name{parse_date}
\alias{parse_date}
-\title{Deprecated internal function, use \code{\link{parseDateTime}} instead.}
+\title{Deprecated internal function, use \code{\link{parse_date_time}} instead.}
\usage{
parse_date(x, formats, quiet = FALSE, seps = NULL,
tz = "UTC")
@@ -18,6 +18,6 @@
}
\description{
Deprecated internal function, use
- \code{\link{parseDateTime}} instead.
+ \code{\link{parse_date_time}} instead.
}
View
168 man/parse_date_time.Rd
@@ -0,0 +1,168 @@
+\name{parse_date_time}
+\alias{parse_date_time}
+\title{Function to parse character and numeric date-time vectors with user friendly
+order formats.}
+\usage{
+ parse_date_time(x, orders, tz = "UTC", truncated = 0,
+ quiet = FALSE, locale = Sys.getlocale("LC_TIME"),
+ select_formats = .select_formats)
+}
+\arguments{
+ \item{x}{a character or numeric vector of dates}
+
+ \item{orders}{a character vector of date-time formats.
+ Each order string is series of formatting characters as
+ listed \code{\link[base]{strptime}} but might not include
+ the "\%" prefix, for example "ymd" will match all the
+ possible dates in year, month, day order. Formatting
+ orders might include arbitrary separators. These are
+ discarded. See details for implemented formats.}
+
+ \item{tz}{a character string that specifies the time zone
+ with which to parse the dates}
+
+ \item{truncated}{integer, number of formats that can be
+ missing. The most common type of irregularity in
+ date-time data is the truncation due to rounding or
+ unavailability of the time stamp. If \code{truncated}
+ parameter is non-zero \code{parse_date_time} also checks
+ for truncated formats. For example, if the format order
+ is "ymdhms" and \code{truncated = 3},
+ \code{parse_date_time} will correctly parse incomplete
+ dates like \code{2012-06-01 12:23}, \code{2012-06-01 12}
+ and \code{2012-06-01}. \bold{NOTE:} \code{ymd} family of
+ functions are based on \code{strptime} which currently
+ fails to parse \code{\%y-\%m} formats.}
+
+ \item{quiet}{logical. When TRUE function evaluates
+ without displaying customary messages.}
+
+ \item{locale}{locale to be used, see \link{locales}. On
+ linux systems you can use \code{system("locale -a")} to
+ list all the installed locales.}
+
+ \item{select_formats}{A function to select actual formats
+ for parsing from a set of formats which matched a
+ training subset of \code{x}. This should be function
+ receiving a named integer vector and returning a
+ character vector of selected formats. Names of the input
+ vector are explicit formats (not orders) which matched
+ the training set and numeric values are the number of
+ dates which matched the corresponding format. You should
+ use this argument if the default selection method fails
+ to select the formats in the right order. By default the
+ formats with most formating tockens (\%) are selected and
+ \%Y counts as 2.5 tockens (so that it can have priority
+ over \%y\%m).}
+}
+\value{
+ a vector of POSIXct date-time objects
+}
+\description{
+ As compared to \code{strptime} parser,
+ \code{parse_date_time} allows to specify only the order
+ in which the formats occur instead of the full format.
+ As it was specifically designed to handle heterogeneous
+ date-time formats at once, you can specify several
+ alternative orders. \code{parse_date_time} sorts the
+ supplied formats based on a training set and then applies
+ them recursively on the input vector.
+}
+\details{
+ Below are all the implemented formats recognized by
+ lubridate. For all numeric formats leading 0s are
+ optional. All formats are case insensitive. As compared
+ to \code{strptime}, some of the formats have been
+ extended for efficiency reasons. They are marked with "*"
+
+ \describe{ \item{\code{a}}{Abbreviated weekday name in
+ the current locale. (Also matches full name)}
+
+ \item{\code{A}}{Full weekday name in the current locale.
+ (Also matches abbreviated name).
+
+ You need not specify \code{a} and \code{A} formats
+ explicitly. Wday is automatically handled if
+ \code{preproc_wday = TRUE}}
+
+ \item{\code{b}}{Abbreviated month name in the current
+ locale. (Also matches full name.)} \item{\code{B}}{Full
+ month name in the current locale. (Also matches
+ abbreviated name.)}
+
+ \item{\code{d}}{Day of the month as decimal number
+ (01--31 or 0--31)} \item{\code{H}}{Hours as decimal
+ number (00--24 or 0--24).} \item{\code{I}}{Hours as
+ decimal number (01--12 or 0--12).} \item{\code{j}}{Day of
+ year as decimal number (001--366 or 1--366).}
+ \item{\code{m}*}{Month as decimal number (01--12 or
+ 1--12). Also matches abbreviated and full months names as
+ \code{b} and \code{B} formats} \item{\code{M}}{Minute as
+ decimal number (00--59 or 0--59).} \item{\code{p}}{AM/PM
+ indicator in the locale. Used in conjunction with
+ \code{I} and \bold{not} with \code{H}. An empty string
+ in some locales.} \item{\code{S}}{Second as decimal
+ number (00--61 or 0--61), allowing for up to two
+ leap-seconds (but POSIX-compliant implementations will
+ ignore leap seconds).} \item{\code{OS}}{Fractional
+ second.}
+
+ \item{\code{U}}{Week of the year as decimal number
+ (00--53 or 0-53) using Sunday as the first day 1 of the
+ week (and typically with the first Sunday of the year as
+ day 1 of week 1). The US convention.}
+ \item{\code{w}}{Weekday as decimal number (0--6, Sunday
+ is 0).} \item{\code{W}}{Week of the year as decimal
+ number (00--53 or 0-53) using Monday as the first day of
+ week (and typically with the first Monday of the year as
+ day 1 of week 1). The UK convention.}
+ \item{\code{y}*}{Year without century (00--99 or 0--99).
+ Also matches year with century (Y format).}
+ \item{\code{Y}}{Year with century.}
+ \item{\code{z}}{Signed offset in hours and minutes from
+ UTC, so \code{-0800} is 8 hours behind UTC.}
+
+ \item{\code{r}*}{Matches \code{Ip} and \code{H} orders.}
+ \item{\code{R}*}{Matches \code{HM} and\code{IMp} orders.}
+ \item{\code{T}*}{Matches \code{IMSp}, \code{HMS}, and
+ \code{HMOS} orders.}
+
+ }
+}
+\examples{
+x <- c("09-01-01", "09-01-02", "09-01-03")
+parse_date_time(x, "\%y\%m\%d")
+parse_date_time(x, "\%y \%m \%d")
+# "2009-01-01 UTC" "2009-01-02 UTC" "2009-01-03 UTC"
+
+## ** heterogenuous formats **
+x <- c("09-01-01", "090102", "09-01 03", "09-01-03 12:02")
+parse_date_time(x, c("\%y\%m\%d", "\%y\%m\%d \%H\%M"))
+## Avoid training for small vectors (all the formats are just tried in turn):
+parse_date_time(x, c("\%y\%m\%d", "\%y\%m\%d \%H\%M"), train = NULL)
+
+## different ymd orders:
+x <- c("2009-01-01", "02022010", "02-02-2010")
+parse_date_time(x, c("\%d\%m\%Y", "\%Y\%m\%d"), train = NULL)
+## "2009-01-01 UTC" "2010-02-02 UTC" "2010-02-02 UTC"
+
+## ** truncated time-dates **
+x <- c("2011-12-31 12:59:59", "2010-01-01 12:11", "2010-01-01 12", "2010-01-01")
+parse_date_time(x, "\%Y\%m\%d \%H\%M\%S", truncated = 3)
+## "2011-12-31 12:59:59 UTC" "2010-01-01 12:11:00 UTC" "2010-01-01 12:00:00 UTC" "2010-01-01 00:00:00 UTC"
+
+## ** custom formats **
+x <- c("July 8th, 2004, 10:30")
+strptime(x, "\%b \%dth, \%Y, \%H:\%M")
+parse_date_time(x, "\%b \%dth, \%Y, \%H:\%M", sep_regexp=NULL)
+## or just
+parse_date_time(x, "\%b\%dth\%Y \%H\%M")
+
+x <- c("Thu, 1 July 2004 22:30:00", "July 8th, 2004, 10:30")
+parse_date_time(x, c("\%a\%d\%b\%Y \%H\%M\%\%S", "\%b \%dth \%Y \%H\%M"))
+}
+\seealso{
+ \code{strptime}, \code{\link{ymd}}, \code{\link{ymd_hms}}
+}
+\keyword{chron}
+
View
2 man/pretty_dates.Rd
@@ -1,5 +1,4 @@
\name{pretty_dates}
-\alias{pretty_dates}
\alias{pretty.dates}
\alias{pretty.day}
\alias{pretty.hour}
@@ -9,6 +8,7 @@
\alias{pretty.sec}
\alias{pretty.unit}
\alias{pretty.year}
+\alias{pretty_dates}
\title{Computes attractive axis breaks for date-time data}
\usage{
pretty_dates(x, n, ...)
View
2 man/reclass_timespan.Rd
@@ -1,9 +1,9 @@
\name{reclass_timespan}
\alias{reclass_timespan}
-\alias{reclass_timespan,ANY,difftime-method}
\alias{reclass_timespan,ANY,Duration-method}
\alias{reclass_timespan,ANY,Interval-method}
\alias{reclass_timespan,ANY,Period-method}
+\alias{reclass_timespan,ANY,difftime-method}
\title{Convenience method to reclass timespans post-modification.}
\usage{
reclass_timespan(new, orig)
View
88 man/stamp.Rd
@@ -0,0 +1,88 @@
+\name{stamp}
+\alias{stamp}
+\alias{stamp_date}
+\alias{stamp_time}
+\title{Format dates and times based on human-friendly templates.}
+\usage{
+ stamp(x, orders = unlist(lubridate_formats),
+ locale = Sys.getlocale("LC_TIME"), quiet = FALSE)
+
+ stamp_date(x, locale = Sys.getlocale("LC_TIME"))
+
+ stamp_time(x, locale = Sys.getlocale("LC_TIME"))
+}
+\arguments{
+ \item{x}{a character vector of templates.}
+
+ \item{orders}{orders are sequences of formatting
+ characters which might be used for disambiguation. For
+ example "ymd hms", "aym" etc. See
+ \code{\link{guess_formats}} for a list of available
+ formats.}
+
+ \item{locale}{locale in which \code{x} is encoded. On
+ linux like systems use \code{locale -a} in terminal to
+ list available locales.}
+
+ \item{quiet}{whether to output informative messages.}
+
+ \item{x}{}
+
+ \item{locale}{}
+
+ \item{x}{}
+
+ \item{locale}{}
+}
+\value{
+ a function to be applied on a vector of dates
+}
+\description{
+ Stamps are just like \code{\link{format}}, but based on
+ human-frendly templates like "Recorded at 10 am,
+ September 2002" or "Meeting, Sunday May 1, 2000, at 10:20
+ pm".
+}
+\details{
+ \code{stamp} is a stamping function date-time templates
+ mainly, though it correctly handles all date and time
+ formats as long as they are unambiguous.
+ \code{stamp_date}, and \code{stamp_time} are the
+ specialized stamps for dates and times (MHS). These
+ function might be useful when the input template is
+ unambiguous and matches both a time and a date format.
+
+ Lubridate tries it's best to figure our the formats, but
+ often a given format can be interpreted in several ways.
+ One way to deal with the situation is to provide
+ unambiguous formats like 22/05/81 instead of 10/05/81 if
+ you want d/m/y format. Another option is to use a more
+ specialized stamp_date and stamp_time. The core function
+ \code{stamp} give priority to longer date-time formats.
+
+ Another option is to proved a vector of several values as
+ \code{x} parameter. Then lubridate will choose the format
+ which fits \code{x} the best. Note that longer formats
+ are preferred. If you have "22:23:00 PM" then "HMSp"
+ format will be given priority to shorter "HMS" order
+ which also fits the supplied string.
+
+ Finally, you can give desired format order directly as
+ \code{orders} argument.
+}
+\examples{
+D <- ymd("2010-04-05") - days(1:5)
+stamp("March 1, 1999")(D)
+sf <- stamp("Created on Sunday, Jan 1, 1999 3:34 pm")
+sf(D)
+stamp("Jan 01")(D)
+stamp("Sunday, May 1, 2000")(D)
+stamp("Sun Aug 5")(D) #=> "Sun Aug 04" "Sat Aug 04" "Fri Aug 04" "Thu Aug 04" "Wed Aug 03"
+stamp("12/31/99")(D) #=> "06/09/11"
+stamp("Sunday, May 1, 2000 22:10")(D)
+}
+\seealso{
+ \link{guess_formats}, \link{parseDateTime},
+ \link{strptime}
+}
+
View
42 man/ymd.Rd
@@ -9,7 +9,8 @@
\title{Parse dates according to the order that year, month, and day elements appear
in the input vector.}
\usage{
- ymd(..., quiet = FALSE, tz = "UTC", missing = 0)
+ ymd(..., quiet = FALSE, tz = "UTC",
+ locale = Sys.getlocale("LC_TIME"), truncated = 0)
}
\arguments{
\item{...}{a character or numeric vector of suspected
@@ -22,36 +23,36 @@ in the input vector.}
zone to parse the date with. The string must be a time
zone that is recognized by the user's OS.}
- \item{missing}{integer. Number of formats that can be
- missing.}
+ \item{truncated}{integer. Number of formats that can be
+ truncated.}
}
\value{
a vector of class POSIXct
}
\description{
Transforms dates stored in character and numeric vectors
- to POSIXct objects. These functions automatically
- recognize all non-alphanumeric separators as well as no
- separator. As long as the order of formats is correct,
- these functions will parse dates correctly even when
- dates have different formats or use different separators.
- For even more flexibility in treatment of heterogeneous
- formats see low level parser \code{\link{parseDateTime}}.
+ to POSIXct objects. These functions recognize arbitrary
+ non-digit separators as well as no separator. As long as
+ the order of formats is correct, these functions will
+ parse dates correctly even when the input vectors contain
+ differently formatted dates. See examples. For even more
+ flexibility in treatment of heterogeneous formats see low
+ level parser \code{\link{parse_date_time}}.
}
\details{
\code{ymd} family of functions automatically assign the
Universal Coordinated Time Zone (UTC) to the parsed
dates. This time zone can be changed with
\code{\link{force_tz}}.
- If \code{missing} parameter is non-zero \code{ymd}
+ If \code{truncated} parameter is non-zero \code{ymd}
functions also check for truncated formats. For example
- \code{ymd} with \code{missing = 2} will also parse
+ \code{ymd} with \code{truncated = 2} will also parse
incomplete dates like \code{2012-06} and \code{2012}.
NOTE: \code{ymd} family of functions are based on
\code{\link{strptime}} which currently correctly parses
- "\%y" format, but fails to parse "\%y-\%m" format.
+ "\%y" format, but fails to parse "\%y-\%m" formats.
}
\examples{
x <- c("09-01-01", "09-01-02", "09-01-03")
@@ -69,27 +70,18 @@ mdy(010210)
## heterogenuous formats in a single vector:
x <- c(20090101, "2009-01-02", "2009 01 03", "2009-1-4",
- "2009-1, 5", "2009....1--6", "200901-07", "200901-8")
+ "2009-1, 5", "Created on 2009 1 6", "200901 !!! 07", "200901-8")
ymd(x)
-## "2009-01-01 UTC" "2009-01-02 UTC" "2009-01-03 UTC" "2009-01-04 UTC" "2009-01-05 UTC" "2009-01-06 UTC"
## What lubridate might not handle:
-## 1) Extremely weird cases when one of the separators is "" and some of the
+## Extremely weird cases when one of the separators is "" and some of the
## formats are not in double digits might not be parsed correctly:
ymd("201002-01", "201002-1", "20102-1")
dmy("0312-2010", "312-2010")
-
-## 2) \%y formats have precedence over \%Y:
-ymd("10-02-01", "2010-02-02")
-## gives "2010-02-01 UTC" "2010-02-02 UTC" and not "10-02-01 UTC" "2010-02-02 UTC"
-
-## This is usually what is desired, as it's very unlikely that "10-02-01" means
-## year 10. If not, then you should use parseDateTime or strptime and pass
-## formats explicitly.
}
\seealso{
- \code{\link{parseDateTime}} for underlying mechanism.
+ \code{\link{parse_date_time}} for underlying mechanism.
}
\keyword{chron}
View
56 man/ymd_hms.Rd
@@ -8,14 +8,14 @@
\alias{ydm_h}
\alias{ydm_hm}
\alias{ydm_hms}
+\alias{ymdThms}
\alias{ymd_h}
\alias{ymd_hm}
\alias{ymd_hms}
-\alias{ymdThms}
\title{Parse dates that have hours, minutes, or seconds elements.}
\usage{
- ymd_hms(..., quiet = FALSE, tz = "UTC", missing = 0,
- frac = FALSE)
+ ymd_hms(..., quiet = FALSE, tz = "UTC",
+ locale = Sys.getlocale("LC_TIME"), truncated = 0)
}
\arguments{
\item{...}{a character vector of dates in year, month,
@@ -28,7 +28,7 @@
zone to parse the date with. The string must be a time
zone that is recognized by the user's OS.}
- \item{missing}{integer, indicating how many formats can
+ \item{truncated}{integer, indicating how many formats can
be missing. See details.}
\item{frac}{If \code{TRUE}, fractional seconds are
@@ -46,7 +46,7 @@
"." if \code{frac = TRUE}) and correctly handle
heterogeneous date-time representations. For more
flexibility in treatment of heterogeneous formats, see
- low level parser \code{\link{parseDateTime}}.
+ low level parser \code{\link{parse_date_time}}.
}
\details{
ymd_hms() functions automatically assigns the Universal
@@ -55,14 +55,14 @@
The most common type of irregularity in date-time data is
the truncation due to rounding or unavailability of the
- time stamp. If \code{missing} parameter is non-zero
+ time stamp. If \code{truncated} parameter is non-zero
\code{ymd_hms} functions also check for truncated
- formats. For example \code{ymd_hms} with \code{missing =
- 3} will also parse incomplete dates like \code{2012-06-01
- 12:23}, \code{2012-06-01 12} and \code{2012-06-01}. NOTE:
- \code{ymd} family of functions are based on
- \code{strptime} which currently fails to parse
- \code{\%y-\%m} formats.
+ formats. For example \code{ymd_hms} with \code{truncated
+ = 3} will also parse incomplete dates like
+ \code{2012-06-01 12:23}, \code{2012-06-01 12} and
+ \code{2012-06-01}. NOTE: \code{ymd} family of functions
+ are based on \code{strptime} which currently fails to
+ parse \code{\%y-\%m} formats.
ymdThms() specifically handles combined dates and times
written in the ISO 8601 format.
@@ -75,19 +75,24 @@ x <- c("2011-12-31 12:59:59", "2010-01-01 12:00:00")
ymd_hms(x)
# [1] "2011-12-31 12:59:59 UTC" "2010-01-01 12:00:00 UTC"
+
## ** heterogenuous formats **
-x <- c(20100101120101, "2009-01-02 12-01-02", "2009.01.03 12:01:03", "2009-1-4 12-1-4",
- "2009-1, 5 12:1, 5", "2009....1--6 - 12::1:6", "20090107 120107", "200901-08 1201-8",
- "10-01-09 12:01:09", "10-01-10 10:01:10 AM", "10-01-11 10:01:11 PM")
+x <- c(20100101120101, "2009-01-02 12-01-02", "2009.01.03 12:01:03",
+ "2009-1-4 12-1-4",
+ "2009-1, 5 12:1, 5",
+ "200901-08 1201-08",
+ "2009 arbitrary 1 non-decimal 6 chars 12 in between 1 !!! 6",
+ "OR collapsed formats: 20090107 120107 (as long as prefixed with zeros)",
+ "Automatic wday, Thu, detection, 10-01-10 10:01:10 and p format: AM",
+ "Created on 10-01-11 at 10:01:11 PM")
ymd_hms(x)
-## "2009-01-01 UTC" "2009-01-02 UTC" "2009-01-03 UTC" "2009-01-04 UTC" "2009-01-05 UTC" "2009-01-06 UTC"
## ** truncated time-dates **
x <- c("2011-12-31 12:59:59", "2010-01-01 12:11", "2010-01-01 12", "2010-01-01")
-ymd_hms(x, missing = 3)
+ymd_hms(x, truncated = 3)
## "2011-12-31 12:59:59 UTC" "2010-01-01 12:11:00 UTC" "2010-01-01 12:00:00 UTC" "2010-01-01 00:00:00 UTC"
x <- c("2011-12-31 12:59", "2010-01-01 12", "2010-01-01")
-ymd_hm(x, missing = 2)
+ymd_hm(x, truncated = 2)
## "2011-12-31 12:59:00 UTC" "2010-01-01 12:00:00 UTC" "2010-01-01 00:00:00 UTC"
## ** fractional seconds **
@@ -97,24 +102,15 @@ ymd_hms(x, frac = TRUE)
## "2011-12-31 12:59:59.23 UTC" "2010-01-01 12:11:10.00 UTC"
## ** What lubridate might not handle **
-## 1) Extremely weird cases when one of the separators is "" and some of the
+## Extremely weird cases when one of the separators is "" and some of the
## formats are not in double digits might not be parsed correctly:
ymd_hm("20100201 07-01", "20100201 07-1", "20100201 7-01")
## "2010-02-01 07:01:00 UTC" "2010-02-01 07:01:00 UTC" NA
-
-## 2) \%y formats have precedence over \%Y:
-ymd_h("10-02-01 02", "2010-02-02 02")
-## gives "2010-02-01 02:00:00 UTC" "2010-02-02 02:00:00 UTC"
-## and not "10-02-01 UTC" "2010-02-02 UTC"
-
-## This is usually what is desired, as it's very unlikely that "10-02-01" means
-## year 10. If not, then you should use parseDateTime or strptime and pass
-## formats explicitly.
}
\seealso{
\code{\link{ymd}}, \code{\link{hms}}.
- \code{\link{parseDateTime}} for underlying mechanism.
+ \code{\link{parse_date_time}} for underlying mechanism.
}
-\keyword{parse}
\keyword{POSIXt}
+\keyword{parse}

0 comments on commit 6807a20

Please sign in to comment.