# 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-02-27T14:15:17+0000"

By default the time element is ignored:

    (res <- fymd(timestamp))

    #> [1] "2026-02-27"

    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  527.791  533.8475  625.5244  539.0075  551.4360  4175.602   100
    #>    fastymd  834.637  839.0155  863.3579  842.8025  849.2545  1612.167   100
    #>        ymd 4138.121 4191.6765 4247.0964 4220.1800 4254.2895  5398.368   100
    #>  lubridate 5559.390 5692.0295 7658.6938 5821.1215 7288.9885 42395.606   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 326.012 327.8455 388.9347 331.0065  335.8755 3210.910   100
    #>  lubridate 662.203 673.4600 858.1228 681.4450 1069.0375 2371.504   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  358.813  360.0465  385.3047  361.9095  366.1925  1942.277   100
    #>        ymd  381.777  389.9425  407.0797  400.9275  409.1435   670.219   100
    #>  lubridate 7691.444 7707.3685 8002.6305 7727.9025 7848.6895 10352.812   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  325.191  327.079  352.8862  330.7610  334.8685  2049.539   100
    #>        ymd  416.542  422.779  458.8966  431.6105  441.8050   802.297   100
    #>  lubridate 8213.795 8271.889 9256.4655 8341.7555 9752.4595 41471.291   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  361.539  362.716  401.9738  365.241  368.377  3303.413   100
    #>        ymd  420.951  426.351  455.8044  433.799  442.571   801.064   100
    #>  lubridate 7635.339 7657.145 8119.6285 7703.982 8728.492 10747.924   100