ymd: Parse dates with *y*ear, *m*onth, and *d*ay components

In lubridate: Make Dealing with Dates a Little Easier

Parse dates with year, month, and day components

Description

Transforms dates stored in character and numeric vectors to Date or POSIXct objects (see tz argument). 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.

Usage

ymd(
  ...,
  quiet = FALSE,
  tz = NULL,
  locale = Sys.getlocale("LC_TIME"),
  truncated = 0
)

ydm(
  ...,
  quiet = FALSE,
  tz = NULL,
  locale = Sys.getlocale("LC_TIME"),
  truncated = 0
)

mdy(
  ...,
  quiet = FALSE,
  tz = NULL,
  locale = Sys.getlocale("LC_TIME"),
  truncated = 0
)

myd(
  ...,
  quiet = FALSE,
  tz = NULL,
  locale = Sys.getlocale("LC_TIME"),
  truncated = 0
)

dmy(
  ...,
  quiet = FALSE,
  tz = NULL,
  locale = Sys.getlocale("LC_TIME"),
  truncated = 0
)

dym(
  ...,
  quiet = FALSE,
  tz = NULL,
  locale = Sys.getlocale("LC_TIME"),
  truncated = 0
)

yq(..., quiet = FALSE, tz = NULL, locale = Sys.getlocale("LC_TIME"))

ym(..., quiet = FALSE, tz = NULL, locale = Sys.getlocale("LC_TIME"))

my(..., quiet = FALSE, tz = NULL, locale = Sys.getlocale("LC_TIME"))

Arguments

...	a character or numeric vector of suspected dates
quiet	logical. If TRUE, function evaluates without displaying customary messages.
tz	Time zone indicator. If NULL (default), a Date object is returned. Otherwise a POSIXct with time zone attribute set to tz.
locale	locale to be used, see locales. On Linux systems you can use system("locale -a") to list all the installed locales.
truncated	integer. Number of formats that can be truncated.

Details

In case of heterogeneous date formats, the ymd() family guesses formats based on a subset of the input vector. If the input vector contains many missing values or non-date strings, the subset might not contain meaningful dates and the date-time format won't be guessed resulting in ⁠All formats failed to parse⁠ error. In such cases please see parse_date_time() for a more flexible parsing interface.

If the truncated parameter is non-zero, the ymd() functions also check for truncated formats. For example, ymd() with truncated = 2 will also parse incomplete dates like 2012-06 and 2012.

NOTE: The ymd() family of functions is based on parse_date_time() and thus directly drop to the internal C parser for numeric months, but uses base::strptime() for alphabetic months. This implies that some of base::strptime()'s limitations are inherited by lubridate's parser. For example, truncated formats (like ⁠%Y-%b⁠) will not be parsed. Numeric truncated formats (like ⁠%Y-%m⁠) are handled correctly by lubridate's C parser.

As of version 1.3.0, lubridate's parse functions no longer return a message that displays which format they used to parse their input. You can change this by setting the lubridate.verbose option to TRUE with options(lubridate.verbose = TRUE).

Value

a vector of class POSIXct if tz argument is non-NULL or Date if tz is NULL (default)

See Also

parse_date_time() for an even more flexible low level mechanism.

Examples

x <- c("09-01-01", "09-01-02", "09-01-03")
ymd(x)
x <- c("2009-01-01", "2009-01-02", "2009-01-03")
ymd(x)
ymd(090101, 90102)
now() > ymd(20090101)
## TRUE
dmy(010210)
mdy(010210)

yq('2014.2')

## heterogeneous formats in a single vector:
x <- c(20090101, "2009-01-02", "2009 01 03", "2009-1-4",
       "2009-1, 5", "Created on 2009 1 6", "200901 !!! 07")
ymd(x)

## What lubridate might not handle:

## Extremely weird cases when one of the separators is "" and some of the
## formats are not in double digits might not be parsed correctly:
## Not run: ymd("201002-01", "201002-1", "20102-1")
dmy("0312-2010", "312-2010")
## End(Not run)

lubridate documentation built on Sept. 27, 2023, 5:07 p.m.