parse_datetime.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/collectors.R
\name{parse_datetime}
\alias{parse_datetime}
\alias{parse_date}
\alias{parse_time}
\alias{col_datetime}
\alias{col_date}
\alias{col_time}
\title{Parse date/times}
\usage{
parse_datetime(
  x,
  format = "",
  na = c("", "NA"),
  locale = default_locale(),
  trim_ws = TRUE
)

parse_date(
  x,
  format = "",
  na = c("", "NA"),
  locale = default_locale(),
  trim_ws = TRUE
)

parse_time(
  x,
  format = "",
  na = c("", "NA"),
  locale = default_locale(),
  trim_ws = TRUE
)

col_datetime(format = "")

col_date(format = "")

col_time(format = "")
}
\arguments{
\item{x}{A character vector of dates to parse.}

\item{format}{A format specification, as described below. If set to "",
date times are parsed as ISO8601, dates and times used the date and
time formats specified in the \code{\link[=locale]{locale()}}.

Unlike \code{\link[=strptime]{strptime()}}, the format specification must match
the complete string.}

\item{na}{Character vector of strings to interpret as missing values. Set this
option to \code{character()} to indicate no missing values.}

\item{locale}{The locale controls defaults that vary from place to place.
The default locale is US-centric (like R), but you can use
\code{\link[=locale]{locale()}} to create your own locale that controls things like
the default time zone, encoding, decimal mark, big mark, and day/month
names.}

\item{trim_ws}{Should leading and trailing whitespace (ASCII spaces and tabs) be trimmed from
each field before parsing it?}
}
\value{
A \code{\link[=POSIXct]{POSIXct()}} vector with \code{tzone} attribute set to
\code{tz}. Elements that could not be parsed (or did not generate valid
dates) will be set to \code{NA}, and a warning message will inform
you of the total number of failures.
}
\description{
Parse date/times
}
\section{Format specification}{

\code{readr} uses a format specification similar to \code{\link[=strptime]{strptime()}}.
There are three types of element:
\enumerate{
\item Date components are specified with "\%" followed by a letter. For example
"\%Y" matches a 4 digit year, "\%m", matches a 2 digit month and "\%d" matches
a 2 digit day. Month and day default to \code{1}, (i.e. Jan 1st) if not present,
for example if only a year is given.
\item Whitespace is any sequence of zero or more whitespace characters.
\item Any other character is matched exactly.
}

\code{parse_datetime()} recognises the following format specifications:
\itemize{
\item Year: "\%Y" (4 digits). "\%y" (2 digits); 00-69 -> 2000-2069, 70-99 ->
1970-1999.
\item Month: "\%m" (2 digits), "\%b" (abbreviated name in current locale), "\%B"
(full name in current locale).
\item Day: "\%d" (2 digits), "\%e" (optional leading space), "\%a" (abbreviated
name in current locale).
\item Hour: "\%H" or "\%I" or "\%h", use I (and not H) with AM/PM, use h (and not H)
if your times represent durations longer than one day.
\item Minutes: "\%M"
\item Seconds: "\%S" (integer seconds), "\%OS" (partial seconds)
\item Time zone: "\%Z" (as name, e.g. "America/Chicago"), "\%z" (as offset from
UTC, e.g. "+0800")
\item AM/PM indicator: "\%p".
\item Non-digits: "\%." skips one non-digit character, "\%+" skips one or more
non-digit characters, "\%*" skips any number of non-digits characters.
\item Automatic parsers: "\%AD" parses with a flexible YMD parser, "\%AT" parses
with a flexible HMS parser.
\item Time since the Unix epoch: "\%s" decimal seconds since the Unix epoch.
\item Shortcuts: "\%D" = "\%m/\%d/\%y", "\%F" = "\%Y-\%m-\%d", "\%R" = "\%H:\%M", "\%T" =
"\%H:\%M:\%S", "\%x" = "\%y/\%m/\%d".
}
}

\section{ISO8601 support}{


Currently, readr does not support all of ISO8601. Missing features:
\itemize{
\item Week & weekday specifications, e.g. "2013-W05", "2013-W05-10".
\item Ordinal dates, e.g. "2013-095".
\item Using commas instead of a period for decimal separator.
}

The parser is also a little laxer than ISO8601:
\itemize{
\item Dates and times can be separated with a space, not just T.
\item Mostly correct specifications like "2009-05-19 14:" and "200912-01" work.
}
}

\examples{
# Format strings --------------------------------------------------------
parse_datetime("01/02/2010", "\%d/\%m/\%Y")
parse_datetime("01/02/2010", "\%m/\%d/\%Y")
# Handle any separator
parse_datetime("01/02/2010", "\%m\%.\%d\%.\%Y")

# Dates look the same, but internally they use the number of days since
# 1970-01-01 instead of the number of seconds. This avoids a whole lot
# of troubles related to time zones, so use if you can.
parse_date("01/02/2010", "\%d/\%m/\%Y")
parse_date("01/02/2010", "\%m/\%d/\%Y")

# You can parse timezones from strings (as listed in OlsonNames())
parse_datetime("2010/01/01 12:00 US/Central", "\%Y/\%m/\%d \%H:\%M \%Z")
# Or from offsets
parse_datetime("2010/01/01 12:00 -0600", "\%Y/\%m/\%d \%H:\%M \%z")

# Use the locale parameter to control the default time zone
# (but note UTC is considerably faster than other options)
parse_datetime("2010/01/01 12:00", "\%Y/\%m/\%d \%H:\%M",
  locale = locale(tz = "US/Central")
)
parse_datetime("2010/01/01 12:00", "\%Y/\%m/\%d \%H:\%M",
  locale = locale(tz = "US/Eastern")
)

# Unlike strptime, the format specification must match the complete
# string (ignoring leading and trailing whitespace). This avoids common
# errors:
strptime("01/02/2010", "\%d/\%m/\%y")
parse_datetime("01/02/2010", "\%d/\%m/\%y")

# Failures -------------------------------------------------------------
parse_datetime("01/01/2010", "\%d/\%m/\%Y")
parse_datetime(c("01/ab/2010", "32/01/2010"), "\%d/\%m/\%Y")

# Locales --------------------------------------------------------------
# By default, readr expects English date/times, but that's easy to change'
parse_datetime("1 janvier 2015", "\%d \%B \%Y", locale = locale("fr"))
parse_datetime("1 enero 2015", "\%d \%B \%Y", locale = locale("es"))

# ISO8601 --------------------------------------------------------------
# With separators
parse_datetime("1979-10-14")
parse_datetime("1979-10-14T10")
parse_datetime("1979-10-14T10:11")
parse_datetime("1979-10-14T10:11:12")
parse_datetime("1979-10-14T10:11:12.12345")

# Without separators
parse_datetime("19791014")
parse_datetime("19791014T101112")

# Time zones
us_central <- locale(tz = "US/Central")
parse_datetime("1979-10-14T1010", locale = us_central)
parse_datetime("1979-10-14T1010-0500", locale = us_central)
parse_datetime("1979-10-14T1010Z", locale = us_central)
# Your current time zone
parse_datetime("1979-10-14T1010", locale = locale(tz = ""))
}
\seealso{
Other parsers: 
\code{\link{col_skip}()},
\code{\link{cols_condense}()},
\code{\link{cols}()},
\code{\link{parse_factor}()},
\code{\link{parse_guess}()},
\code{\link{parse_logical}()},
\code{\link{parse_number}()},
\code{\link{parse_vector}()}
}
\concept{parsers}