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"