R: Parsing: date

date_parse {clock}

R Documentation

Parsing: date

Description

date_parse() parses strings into a Date.

The default format used is "%Y-%m-%d".

Usage

date_parse(x, ..., format = NULL, locale = clock_locale())

Arguments

`x`	`[character]` A character vector to parse.
`...`	These dots are for future extensions and must be empty.
`format`	`[character / NULL]` A format string. A combination of the following commands, or `NULL`, in which case a default format string is used. A vector of multiple format strings can be supplied. They will be tried in the order they are provided. Year `%C`: The century as a decimal number. The modified command `%NC` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. `%y`: The last two decimal digits of the year. If the century is not otherwise specified (e.g. with `%C`), values in the range `[69 - 99]` are presumed to refer to the years `[1969 - 1999]`, and values in the range `[00 - 68]` are presumed to refer to the years `[2000 - 2068]`. The modified command `%Ny`, where `N` is a positive decimal integer, specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. `%Y`: The year as a decimal number. The modified command `%NY` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `4`. Leading zeroes are permitted but not required. Month `%b`, `%B`, `%h`: The `locale`'s full or abbreviated case-insensitive month name. `%m`: The month as a decimal number. January is `1`. The modified command `%Nm` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. Day `%d`, `%e`: The day of the month as a decimal number. The modified command `%Nd` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. Day of the week `%a`, `%A`: The `locale`'s full or abbreviated case-insensitive weekday name. `%w`: The weekday as a decimal number (`0-6`), where Sunday is `0`. The modified command `%Nw` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `1`. Leading zeroes are permitted but not required. ISO 8601 week-based year `%g`: The last two decimal digits of the ISO week-based year. The modified command `%Ng` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. `%G`: The ISO week-based year as a decimal number. The modified command `%NG` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `4`. Leading zeroes are permitted but not required. `%V`: The ISO week-based week number as a decimal number. The modified command `%NV` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. `%u`: The ISO weekday as a decimal number (`1-7`), where Monday is `1`. The modified command `%Nu` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `1`. Leading zeroes are permitted but not required. Week of the year `%U`: The week number of the year as a decimal number. The first Sunday of the year is the first day of week `01`. Days of the same year prior to that are in week `00`. The modified command `%NU` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. `%W`: The week number of the year as a decimal number. The first Monday of the year is the first day of week `01`. Days of the same year prior to that are in week `00`. The modified command `%NW` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. Day of the year `%j`: The day of the year as a decimal number. January 1 is `1`. The modified command `%Nj` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `3`. Leading zeroes are permitted but not required. Date `%D`, `%x`: Equivalent to `%m/%d/%y`. `%F`: Equivalent to `%Y-%m-%d`. If modified with a width (like `%NF`), the width is applied to only `%Y`. Time of day `%H`: The hour (24-hour clock) as a decimal number. The modified command `%NH` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. `%I`: The hour (12-hour clock) as a decimal number. The modified command `%NI` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. `%M`: The minutes as a decimal number. The modified command `%NM` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is `2`. Leading zeroes are permitted but not required. `%S`: The seconds as a decimal number. The modified command `%NS` where `N` is a positive decimal integer specifies the maximum number of characters to read. If not specified, the default is determined by the precision that you are parsing at. If encountered, the `locale` determines the decimal point character. Leading zeroes are permitted but not required. `%p`: The `locale`'s equivalent of the AM/PM designations associated with a 12-hour clock. The command `%I` must precede `%p` in the format string. `%R`: Equivalent to `%H:%M`. `%T`, `%X`: Equivalent to `%H:%M:%S`. `%r`: Equivalent to `%I:%M:%S %p`. Time zone `%z`: The offset from UTC in the format `[+\|-]hh[mm]`. For example `-0430` refers to 4 hours 30 minutes behind UTC. And `04` refers to 4 hours ahead of UTC. The modified command `%Ez` parses a `:` between the hours and minutes and leading zeroes on the hour field are optional: `[+\|-]h[h][:mm]`. For example `-04:30` refers to 4 hours 30 minutes behind UTC. And `4` refers to 4 hours ahead of UTC. `%Z`: The full time zone name or the time zone abbreviation, depending on the function being used. A single word is parsed. This word can only contain characters that are alphanumeric, or one of `'_'`, `'/'`, `'-'` or `'+'`. Miscellaneous `%c`: A date and time representation. Equivalent to `%a %b %d %H:%M:%S %Y`. `%%`: A `%` character. `%n`: Matches one white space character. `%n`, `%t`, and a space can be combined to match a wide range of white-space patterns. For example `"%n "` matches one or more white space characters, and `"%n%t%t"` matches one to three white space characters. `%t`: Matches zero or one white space characters.
`locale`	`[clock_locale]` A locale object created from `clock_locale()`.

Details

date_parse() ignores both the %z and %Z commands, as clock treats Date as a naive type, with a yet-to-be-specified time zone.

If parsing a string with sub-daily components, such as hours, minutes or seconds, note that the conversion to Date will round those components to the nearest day. See the examples for a way to control this.

Value

A Date.

Examples

date_parse("2020-01-01")

date_parse(
  "January 5, 2020",
  format = "%B %d, %Y"
)

# With a different locale
date_parse(
  "janvier 5, 2020",
  format = "%B %d, %Y",
  locale = clock_locale("fr")
)

# A neat feature of `date_parse()` is the ability to parse
# the ISO year-week-day format
date_parse("2020-W01-2", format = "%G-W%V-%u")

# ---------------------------------------------------------------------------
# Rounding of sub-daily components

# Note that rounding a string with time components will round them to the
# nearest day if you try and parse them
x <- c("2019-01-01 11", "2019-01-01 12")

# Hour 12 rounds up to the next day
date_parse(x, format = "%Y-%m-%d %H")

# If you don't like this, one option is to just not parse the time component
date_parse(x, format = "%Y-%m-%d")

# A more general option is to parse the full string as a naive-time,
# then round manually
nt <- naive_time_parse(x, format = "%Y-%m-%d %H", precision = "hour")
nt

nt <- time_point_floor(nt, "day")
nt

as.Date(nt)

[Package clock version 0.3.0 Index]