% 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 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 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}
