https://github.com/schochastics/timeless
A general purpose date(time) parser for R
https://github.com/schochastics/timeless
datetime rstats rstats-package
Last synced: 4 months ago
JSON representation
A general purpose date(time) parser for R
- Host: GitHub
- URL: https://github.com/schochastics/timeless
- Owner: schochastics
- License: other
- Created: 2024-02-24T05:42:04.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2024-09-17T08:39:21.000Z (5 months ago)
- Last Synced: 2024-10-12T22:14:19.181Z (4 months ago)
- Topics: datetime, rstats, rstats-package
- Language: R
- Homepage: https://schochastics.github.io/timeless/
- Size: 32.4 MB
- Stars: 21
- Watchers: 3
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - schochastics/timeless - A general purpose date(time) parser for R (R)
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# timeless 
[](https://github.com/schochastics/timeless/actions/workflows/R-CMD-check.yaml)
[](https://CRAN.R-project.org/package=timeless)
[](https://app.codecov.io/gh/schochastics/timeless?branch=main)
A fast general purpose date/time converter written in Rust with crates [dateparser](https://github.com/waltzofpearls/dateparser) and [chrono](https://github.com/chronotope/chrono).
## Installation
You can install the development version of timeless like so:
``` r
remotes::install_github("schochastics/timeless")
#or
pak::pak("schochastics/timeless")
```
~~the package is also available on CRAN~~
```r
#install.packages("timeless")
```
**The fix I submitted for [#22](https://github.com/schochastics/timeless/issues/22) was apparently not sufficient and the package was archived.**
```{r}
library(timeless)
```
## Formats
timeless understands many different date(time) formats out of the box. A subset is included as a small benchmark dataset.
```{r}
bench_date
```
`chronos()` is the powerhouse of the package and tries as hard as possible to parse every input into either
a date or a datetime, depending on `out_format`. The function can also return a raw character vector which can be fed into faster
converters, such as [fasttime](https://github.com/s-u/fasttime).
```{r}
chronos(bench_date, out_format = "datetime")
```
## Functions
Under the hood `chronos()` calls three functions which can also be used in isolation:
- `parse_datetime()`: a fast datetime parser that tries several different formats until it can parse the input
- `parse_date()`: a fast date parser that tries several different formats until it can parse the input
- `parse_epoch()`: a fast-ish epoch timestamp parser
## other packages
[anytime](https://github.com/eddelbuettel/anytime) is the most accepted general purpose date(time) converter.
It does not recognize all accepted formats of `timeless` out of the box. (Note that the unrecognized formats can be added via `anytime::addFormats()`)
```{r}
sum_na <- function(x) sum(is.na(x))
sum_na(dplyr::coalesce(
anytime::anytime(bench_date),
anytime::anydate(bench_date)
)) / length(bench_date)
```
The list of formats supported out-of-the-box can be retrieved with `anytime::getFormats()`.
`timeless` implements these formats natively too.
Concerning runtime, `timeless` seems to be quite a bit faster than `anytime`.
```{r}
microbenchmark::microbenchmark(
chronos(bench_date),
anytime::anytime(bench_date)
)
```
See [this benchmark](https://github.com/schochastics/timeless/blob/main/data-raw/benchmark.md) for more details.
**Disclaimer**:
While it might seem that `timeless` has an edge over `anytime`, it is far less battle tested and
mature. Date parsing can be very tricky. I am grateful for everyone who can take the package for a spin and report issues.