fastymd

Overview

fastymd is a package for working with Year-Month-Day (YMD) style date objects. It provides extremely fast passing of character strings and numeric values to date objects as well as fast decomposition of these in to their year, month and day components. The underlying algorithms follow the approach of Howard Hinnant for calculating days from the UNIX Epoch of Gregorian Calendar dates and vice versa.

The API won’t give any surprises:

library(fastymd)
cdate <- c("2025-04-16", "2025-04-17")
(res <- fymd(cdate))

#> [1] "2025-04-16" "2025-04-17"

res == as.Date(cdate)

#> [1] TRUE TRUE

get_ymd(res)

#>   year month day
#> 1 2025     4  16
#> 2 2025     4  17

fymd(2025, 4, 16) == res[1L]

#> [1] TRUE

Invalid dates will return NA and a warning:

fymd(2021, 02, 29) # not a leap year

#> NAs introduced due to invalid month and/or day combinations.

#> [1] NA

More interesting is the handling of output after a valid date. Consider the following timestamp:

timelt <- as.POSIXlt(Sys.time(), tz = "UTC")
(timestamp <- strftime(timelt, "%Y-%m-%dT%H:%M:%S%z"))

#> [1] "2026-11-10T10:12:29+0000"

By default the time element is ignored:

(res <- fymd(timestamp))

#> [1] "2026-11-10"

res == as.Date(timestamp, tz = "UTC")

#> [1] TRUE

This ignoring of the timestamp is both good and bad. For timestamps it makes perfect sense, but perhaps you have simple dates and a concern that some are corrupted. For these we can use the strict argument:

cdate <- "2025-04-16nonsense "
fymd(cdate)

#> [1] "2025-04-16"

fymd(cdate, strict = TRUE)

#> NAs introduced due to invalid date strings.

#> [1] NA

Benchmarks

The character method of fymd() parses input strings in a fixed, year, month and day order. These values must be digits but can be separated by any non-digit character. This is similar in spirit to the fastDate() function in Simon Urbanek’s fasttime package, using pure text parsing and no system calls for maximum speed.

For extremely fast passing of POSIX style timestamps you will struggle to beat the performance of fasttime. This works fantastically for timestamps that do not need validation and are within the date range supported by the package (currently 1970-01-01 through to the year 2199).

fymd() fills the, admittedly small, niche where you want fast parsing of YMD strings along with date validation and support for a wider range of dates from the Proleptic Gregorian calendar (currently we support years in the range [-9999, 9999]). This additional capability does come with a small performance penalty but, hopefully, this has been kept to a minimum and the implementation remains competitive.

library(microbenchmark)

# 1970-01-01 (UNIX epoch) to "2199-01-01"
dates <- seq.Date(from = .Date(0), to = fymd("2199-01-01"), by = "day")

# comparison timings for fymd (character method)
cdates  <- format(dates)
(res_c <- microbenchmark(
    fasttime  = fasttime::fastDate(cdates),
    fastymd   = fymd(cdates),
    ymd       = ymd::ymd(cdates),
    lubridate = lubridate::ymd(cdates),
    check     = "equal"
))

#> Unit: microseconds
#>       expr      min        lq      mean    median        uq       max neval
#>   fasttime  536.831  548.3915  623.5558  554.5135  565.8495  2453.953   100
#>    fastymd  881.537  891.2455  963.6858  899.6270  907.6975  2713.471   100
#>        ymd 3854.847 3922.9990 4053.0973 3964.9780 4019.2505  5869.573   100
#>  lubridate 5873.240 6013.5930 7278.2580 6241.6965 7865.8245 48278.639   100

# comparison timings for fymd (numeric method)
ymd  <- get_ymd(dates)
(res_n <- microbenchmark(
    fastymd   = fymd(ymd[[1]], ymd[[2]], ymd[[3]]),
    lubridate = lubridate::make_date(ymd[[1]], ymd[[2]], ymd[[3]]),
    check     = "equal"
))

#> Unit: microseconds
#>       expr     min      lq     mean   median       uq      max neval
#>    fastymd 309.854 313.485 336.7980 317.9285 320.1180 2149.501   100
#>  lubridate 673.226 720.986 798.4095 726.3970 729.5575 2643.039   100

# comparison timings for year getter
(res_get_year <- microbenchmark(
    fastymd   = get_year(dates),
    ymd       = ymd::year(dates),
    lubridate = lubridate::year(dates),
    check     = "equal"
))

#> Unit: microseconds
#>       expr      min       lq      mean    median        uq       max neval
#>    fastymd  324.470  326.505  355.9721  331.3585  333.5125  2161.093   100
#>        ymd  381.968  394.973  466.7480  403.4245  420.1605  2382.389   100
#>  lubridate 7765.646 7789.771 8216.7219 7803.3770 7972.0535 11526.454   100

# comparison timings for month getter
(res_get_month <- microbenchmark(
    fastymd   = get_month(dates),
    ymd       = ymd::month(dates),
    lubridate = lubridate::month(dates),
    check     = "equal"
))

#> Unit: microseconds
#>       expr      min        lq      mean   median         uq       max neval
#>    fastymd  324.301  327.7770  353.2091  332.055   335.2065  1972.238   100
#>        ymd  413.889  429.4735  474.6712  435.564   446.5405  2745.691   100
#>  lubridate 8460.322 8511.8740 9534.5861 8539.891 10163.1075 41510.378   100

# comparison timings for mday getter
(res_get_mday <- microbenchmark(
    fastymd   = get_mday(dates),
    ymd       = ymd::mday(dates),
    lubridate = lubridate::day(dates),
    check     = "equal"
))

#> Unit: microseconds
#>       expr      min        lq      mean    median        uq       max neval
#>    fastymd  326.985  331.1685  385.5498  334.0890  336.0825  3290.335   100
#>        ymd  415.842  429.4135  451.2208  437.5935  446.9305   748.758   100
#>  lubridate 7717.936 7737.3075 8195.3483 7757.0955 8039.3355 11124.228   100