README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

<!-- badges: start -->
[![Lifecycle: deprecated](https://img.shields.io/badge/lifecycle-deprecated-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#deprecated)
[![License: GPL3](https://img.shields.io/badge/License-GPL3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0.en.html)

<!-- badges: end -->

# dttr

`dttr` (date times in R) is a light-weight package to manipulate date (Date), time (hms) and datetime (POSIXct) objects.
As well as functions to get, set, add and subtract years, months, days, hours etc it includes functions to floor objects, set or adjust time zones and create complete sequences.
The default time zone can be set for package function calls.
It also provides duration and timer objects.

## Demonstration

### Get and Set Component

The core functions allow the user to easily get and set the components of Date and POSIXct objects.

```{r}
library(dttr)
date_times <- dttr::date_times
date_times
dtt_year(date_times)
dtt_year(date_times) <- c(2000L, 2000L, 2002L)
date_times
dtt_add_years(date_times, 2L)
dtt_floor(date_times, units = "months")
seq <- dtt_seq(date_times[1], date_times[2], units = "months")
seq
```

### Complete

Completing a sequence is also straightforward
```{r}
seq <- seq[c(1,2,12)]
seq
dtt_completed(seq)
seq <- dtt_complete(seq)
dtt_completed(seq)
seq
```


### Time Zones

As well as setting the time zone which does not change the clock time the user can adjust the time zone which alters the clock time so that the old and new events are coincident.

```{r}
date_times
dtt_set_tz(date_times, tz = "Etc/GMT-1")
dtt_adjust_tz(date_times, tz = "Etc/GMT-1")
```

The user is also able to use `dtt_set_sys_tz()` to define the default time zone for all package function calls.

### Timer

A object of class `dtt_timer` tracks the clock time in seconds.
`dtt_elapsed()` returns the duration for which the timer has been running (see below).

```{r}
timer <- dtt_timer(start = TRUE)
timer
Sys.sleep(1)
timer
Sys.sleep(1)
timer
timer <- dtt_stop(timer)
timer
Sys.sleep(1)
timer
timer <- dtt_start(timer)
Sys.sleep(1)
timer
as.integer(dtt_elapsed(timer))
```

### Duration

An object of class `dtt_duration` is an integer vector that stores the time in seconds.

```{r}
duration <- dtt_elapsed(timer)
duration
class(duration)
dtt_minutes(duration)

```

## Installation

To install the latest development version from the Poisson drat [repository](https://github.com/poissonconsulting/drat)
```
if(!"drat" %in% installed.packages()[,1]) 
  install.packages("drat")
drat::addRepo("poissonconsulting")
install.packages("dttr")
```

To install the latest development version from [GitHub](https://github.com/poissonconsulting/checkr)
```
if(!"devtools" %in% installed.packages()[,1]) 
  install.packages("devtools")
devtools::install_github("poissonconsulting/err")
devtools::install_github("poissonconsulting/checkr")
devtools::install_github("poissonconsulting/dttr")
```

## Inspiration

[lubridate](https://lubridate.tidyverse.org)

## Contribution

Please report any [issues](https://github.com/poissonconsulting/dttr/issues).

[Pull requests](https://github.com/poissonconsulting/dttr/pulls) are always welcome.

Please note that the 'dttr' project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms