R lubridate parse_date_time 用户友好的日期时间解析函数

parse_date_time() 将输入向量解析为 POSIXct 日期时间对象。它与 base::strptime() 有两个不同之处。首先，它允许指定格式出现的顺序，而无需包含分隔符和 % 前缀。这样的格式化参数被称为"order"。其次，它允许用户指定多个format-orders来处理异构日期时间字符表示。

parse_date_time2() 是一个快速的 C 数字顺序解析器。

fast_strptime() 是仅数字格式的快速 C 解析器，它接受显式格式参数，就像 base::strptime() 一样。

用法

parse_date_time(
  x,
  orders,
  tz = "UTC",
  truncated = 0,
  quiet = FALSE,
  locale = Sys.getlocale("LC_TIME"),
  select_formats = .select_formats,
  exact = FALSE,
  train = TRUE,
  drop = FALSE
)

parse_date_time2(
  x,
  orders,
  tz = "UTC",
  exact = FALSE,
  lt = FALSE,
  cutoff_2000 = 68L
)

fast_strptime(x, format, tz = "UTC", lt = TRUE, cutoff_2000 = 68L)

参数

x

日期的字符或数值向量

orders

日期时间格式的字符向量。每个订单字符串都是 base::strptime() 中列出的一系列格式字符，但可能不包含 "%" 前缀。例如，"ymd" 将按年、月、日顺序匹配所有可能的日期。格式化命令可能包含任意分隔符。这些被丢弃。请参阅实施格式的详细信息。如果提供多个订单字符串，它们将依次应用于 parse_date_time2() 和 fast_strptime() 。对于parse_date_time()，应用格式的顺序由select_formats 参数确定。

tz

指定用于解析日期的时区的字符串

truncated

整数，可能缺少的格式数量。日期时间数据中最常见的不规则类型是由于四舍五入或时间戳不可用而导致的截断。如果 truncated 参数非零，parse_date_time() 还会检查截断的格式。例如，如果格式顺序为 "ymdHMS" 和 truncated = 3 ，则 parse_date_time() 将正确解析不完整的日期时间，例如 2012-06-01 12:23 、 2012-06-01 12 和 2012-06-01 。注意：ymd() 系列函数基于 base::strptime()，目前无法解析 %Y-%m 格式。

quiet

合乎逻辑的。如果 TRUE ，则不打印进度消息，并且抑制 No formats found 错误，并且该函数仅返回 NA 向量。这反映了基本 R 函数 base::strptime() 和 base::as.POSIXct() 的行为。

locale

要使用的区域设置，请参阅locales。在 Linux 系统上，您可以使用 system("locale -a") 列出所有已安装的区域设置。

select_formats

用于从与 x 的训练子集匹配的一组格式中选择实际格式进行解析的函数。它接收一个命名的整数向量并返回选定格式的字符向量。输入向量的名称是与训练集匹配的格式(不是顺序)。数值是与相应格式匹配的日期数(在训练集中)。如果默认选择方法无法按正确的顺序选择格式，则应使用此参数。默认情况下，选择具有最多格式标记 ( % ) 的格式，并且 %Y 计为 2.5 个标记(因此它的优先级高于 %y%m )。请参阅示例。

exact

合乎逻辑的。如果 TRUE ，则 orders 参数被解释为精确的 base::strptime() 格式，并且不执行任何训练或猜测(即 train 、 drop 参数被忽略)。

train

逻辑，默认 TRUE 。是否在输入向量的子集上训练格式。因此，提供的订单根据该训练集的性能进行排序，这通常会提高性能。请注意，即使 train = FALSE (和 exact = FALSE )，实际格式的猜测仍在训练集(原始输入向量的伪随机子集)上进行。这可能会导致 All formats failed to parse 错误。请参阅下面的注释。

drop

逻辑，默认 FALSE 。是否删除与训练集不匹配的格式。如果 FALSE ，则在解析队列末尾尝试作为最后的手段，在训练集格式上不匹配。仅适用于 train = TRUE 。在涉及多种格式的情况下，将此参数设置为 TRUE 可能会稍微加快解析速度。在 v1.7.0 之前，此参数隐式 TRUE ，当训练集中不存在罕见模式时，这会导致偶尔出现令人惊讶的行为。

lt

合乎逻辑的。如果 TRUE ，则返回的对象属于 POSIXlt 类，否则返回 POSIXct 类。为了与 base::strptime() 兼容，fast_strptime() 的默认值是 TRUE，parse_date_time2() 的默认值是 FALSE。

cutoff_2000

整数。对于 y 格式，小于或等于 cutoff_2000 的两位数被解析为以 20 开头，否则解析为以 19 开头。仅适用于依赖lubridate 内部解析器的函数。

format

格式向量。如果提供了多种格式，则依次应用它们直到成功。格式应包含所有分隔符，并且每个格式字母必须以 % 为前缀，就像 base::strptime() 的格式参数中一样。

值

POSIXct 日期时间对象的向量

细节

当指定多个format-orders时，parse_date_time()根据输入字符串的训练子集选择(猜测)format-orders。猜测后，根据训练集的性能对格式进行排序，并递归地应用于整个输入向量。您可以使用 train = FALSE 禁用训练。

parse_date_time() 以及所有派生函数，例如 ymd_hms() 、 ymd() 等，只要从输入数据格式猜测的都是数字，就会落入 fast_strptime() 而不是 base::strptime() 。

下面的列表包含可识别的格式润滑。对于数字格式，前导 0 是可选的。相比于base::strptime()，一些格式是新的或出于效率原因已被扩展。这些格式在下面标有"(*)"。快速解析器parse_date_time2()和fast_strptime()仅接受标有 "(!)" 的格式。

a

当前区域设置中工作日的缩写名称。 (也匹配全名)

A

当前区域设置中的完整工作日名称。 (也匹配缩写名称)。

您不需要显式指定 a 和 A 格式。如果preproc_wday = TRUE，则自动处理工作日

b (!)

当前区域设置中月份的缩写或完整名称。 C 解析器当前仅理解英文月份名称。

B (!)

与b相同。

d (!)

十进制数形式的月份日期(01--31 或 0--31)

H (!)

十进制数形式的小时(00--24 或 0--24)。

I (!)

十进制数形式的小时(01--12 或 1--12)。

j

一年中的第几天，十进制数(001--366 或 1--366)。

q (!*)

四分之一 (1--4)。如果存在 m 元素，则将季月添加到解析的月份中。

m (!*)

十进制数形式的月份(01--12 或 1--12)。对于 parse_date_time 还匹配缩写和完整月份名称，如 b 和 B 格式。 C 解析器仅理解英文月份名称。

M (!)

分钟为十进制数(00--59 或 0--59)。

p (!)

区域设置中的 AM/PM 指示器。通常与I和不是和H。但润滑只要小时不大于 12，C 解析器就接受 H 格式。C 解析器仅理解英语语言环境 AM/PM 指示符。

S (!)

秒为十进制数(00--61 或 0--61)，最多允许两个 leap-seconds(但 POSIX-compliant 实现将忽略闰秒)。

OS

小数秒。

U

一年中的第几周，以十进制数表示(00--53 或 0--53)，使用星期日作为一周的第一天(通常将一年中的第一个星期日作为第一周的第一天)。美国大会。

w

工作日为十进制数(0--6，星期日为 0)。

W

一年中的第几周，采用十进制数(00--53 或 0--53)，使用星期一作为一周的第一天(通常将一年中的第一个星期一作为第一周的第一天)。英国大会。

y (!*)

不带世纪的年份(00--99 或 0--99)。在 parse_date_time() 中也将年份与世纪匹配(Y 格式)。

Y (!)

年与世纪。

z (!*)

ISO8601 与 UTC 的小时和分钟偏移量。例如 -0800 、 -08:00 或 -08 均表示比 UTC 晚 8 小时。此格式还与 Z (Zulu) UTC 指示器匹配。由于 base::strptime() 不完全支持 ISO8601，因此该格式作为 4 种格式的联合实现：Ou (Z)、Oz (-0800)、OO (-08:00) 和 Oo (-08)。您可以像使用其他格式一样使用这些格式，但很少有必要。 parse_date_time2() 和 fast_strptime() 支持所有这些格式。

Om (!*)

匹配数字月份和英文字母月份(长形式和缩写形式)。

Op (!*)

匹配 AM/PM 英文指示符。

r (*)

匹配 Ip 和 H 订单。

R (*)

匹配 HM 和 IMp 订单。

T (*)

匹配 IMSp 、 HMS 和 HMOS 订单。

注意

parse_date_time() (以及衍生产品 ymd() 、 ymd_hms() 等)依赖于稀疏猜测器，该猜测器从提供的字符向量中获取最多 501 个元素，以便从提供的订单中识别适当的格式。如果收到错误 All formats failed to parse 并且确信向量包含有效日期，则应该将 exact 参数设置为 TRUE 或使用不执行格式猜测的函数( fast_strptime() 、 parse_date_time2() 或base::strptime())。

出于性能原因，当时区不是 UTC 时，parse_date_time2() 和 fast_strptime() 不会执行夏令时的有效性检查。因此，如果您的输入字符串包含落入 DST 间隙和 lt = TRUE 的无效日期时间，您将获得时间不存在的 POSIXlt 对象。如果lt = FALSE，您的时刻将通过添加一个小时来调整为有效时间。请参阅示例。如果您想获取无效日期时间的 NA，请显式使用 fit_to_timeline()。

也可以看看

例子

## ** orders are much easier to write **
x <- c("09-01-01", "09-01-02", "09-01-03")
parse_date_time(x, "ymd")
#> [1] "2009-01-01 UTC" "2009-01-02 UTC" "2009-01-03 UTC"
parse_date_time(x, "y m d")
#> [1] "2009-01-01 UTC" "2009-01-02 UTC" "2009-01-03 UTC"
parse_date_time(x, "%y%m%d")
#> [1] "2009-01-01 UTC" "2009-01-02 UTC" "2009-01-03 UTC"
#  "2009-01-01 UTC" "2009-01-02 UTC" "2009-01-03 UTC"

## ** heterogeneous date-times **
x <- c("09-01-01", "090102", "09-01 03", "09-01-03 12:02")
parse_date_time(x, c("ymd", "ymd HM"))
#> [1] "2009-01-01 00:00:00 UTC" "2009-01-02 00:00:00 UTC"
#> [3] "2009-01-03 00:00:00 UTC" "2009-01-03 12:02:00 UTC"

## ** different ymd orders **
x <- c("2009-01-01", "02022010", "02-02-2010")
parse_date_time(x, c("dmY", "ymd"))
#> [1] "2009-01-01 UTC" "2010-02-02 UTC" "2010-02-02 UTC"
##  "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, "Ymd HMS", truncated = 3)
#> [1] "2011-12-31 12:59:59 UTC" "2010-01-01 12:11:00 UTC"
#> [3] "2010-01-01 12:00:00 UTC" "2010-01-01 00:00:00 UTC"

## ** specifying exact formats and avoiding training and guessing **
parse_date_time(x, c("%m-%d-%y", "%m%d%y", "%m-%d-%y %H:%M"), exact = TRUE)
#> Warning:  4 failed to parse.
#> [1] NA NA NA NA
parse_date_time(c('12/17/1996 04:00:00','4/18/1950 0130'),
                c('%m/%d/%Y %I:%M:%S','%m/%d/%Y %H%M'), exact = TRUE)
#> [1] "1996-12-17 04:00:00 UTC" "1950-04-18 01:30:00 UTC"

## ** quarters and partial dates **
parse_date_time(c("2016.2", "2016-04"), orders = "Yq")
#> [1] "2016-04-01 UTC" "2016-10-01 UTC"
parse_date_time(c("2016", "2016-04"), orders = c("Y", "Ym"))
#> [1] "2016-01-01 UTC" "2016-04-01 UTC"

## ** fast parsing **
if (FALSE) {
  options(digits.secs = 3)
  ## random times between 1400 and 3000
  tt <- as.character(.POSIXct(runif(1000, -17987443200, 32503680000)))
  tt <- rep.int(tt, 1000)

  system.time(out <- as.POSIXct(tt, tz = "UTC"))
  system.time(out1 <- ymd_hms(tt)) # constant overhead on long vectors
  system.time(out2 <- parse_date_time2(tt, "YmdHMOS"))
  system.time(out3 <- fast_strptime(tt, "%Y-%m-%d %H:%M:%OS"))

  all.equal(out, out1)
  all.equal(out, out2)
  all.equal(out, out3)
}

## ** how to use `select_formats` argument **
## By default %Y has precedence:
parse_date_time(c("27-09-13", "27-09-2013"), "dmy")
#> [1] "2013-09-27 UTC" "2013-09-27 UTC"

## to give priority to %y format, define your own select_format function:

my_select <-   function(trained, drop=FALSE, ...){
   n_fmts <- nchar(gsub("[^%]", "", names(trained))) + grepl("%y", names(trained))*1.5
   names(trained[ which.max(n_fmts) ])
}

parse_date_time(c("27-09-13", "27-09-2013"), "dmy", select_formats = my_select)
#> [1] "2013-09-27 UTC" "2013-09-27 UTC"

## ** invalid times with "fast" parsing **
parse_date_time("2010-03-14 02:05:06",  "YmdHMS", tz = "America/New_York")
#> Warning:  1 failed to parse.
#> [1] NA
parse_date_time2("2010-03-14 02:05:06",  "YmdHMS", tz = "America/New_York")
#> [1] "2010-03-14 03:05:06 EDT"
parse_date_time2("2010-03-14 02:05:06",  "YmdHMS", tz = "America/New_York", lt = TRUE)
#> [1] "2010-03-14 02:05:06 America/New_York"