-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.Rmd
137 lines (100 loc) · 4.12 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
---
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%"
)
```
# dttr2 <img src="man/figures/logo.png" style="float: right;" />
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://github.com/poissonconsulting/dttr2/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/poissonconsulting/dttr2)
[](https://opensource.org/license/MIT)
[](https://cran.r-project.org/package=dttr2)
<!-- badges: end -->
## Introduction
`dttr2` (Dates, Times and dateTimes in R) is an R package to perform simple manipulations on date (Date), datetime (POSIXct) and time (hms) vectors (collectively referred to as date/times).
Key design principles include
1. use existing classes (Date, POSIXct, hms)
2. date/times are discrete (floor when encountered)
3. times are times (wrap when encountered)
4. maintain the current timezone (principle of least astonishment)
5. the origin is always assumed to be 1970-01-01 UTC (keep it simple)
## Installation
To install the latest release version from [CRAN](https://cran.r-project.org/package=dttr2)
```
install.packages("dttr2")
```
To install the latest development version from [GitHub](https://github.com/poissonconsulting/dttr2)
```
# install.packages("pak")
pak::pak("poissonconsulting/dttr2")
```
## Introduction
### Time Units
`dttr2` floors any date/time objects it encounters to the nearest time unit (by default days for Date and seconds for POSIXct and hms).
```{r}
library(dttr2)
date <- as.Date(1.75, origin = "1970-01-01")
date
as.numeric(date)
date <- dtt_date(date)
date
as.numeric(date)
```
Similarly, the time unit accessor (`dtt_second()`, `dtt_minute()` etc) and settor functions as well as the functions to add (ie `dtt_add_seconds()`) and subtract time units return or require integers.
```{r}
dtt_day(date)
dtt_add_days(date, 2L)
dtt_add_months(date, 24L)
```
### Times
`dttr2` wraps negative times or times greater than 23:59:59 to the actual clock time.
```{r}
time <- hms::as_hms(-3)
time
dtt_time(time)
dtt_time(hms::as_hms("24:00:00"))
```
### Time Zones
The user can override the default time zone (UTC) when handling POSIXct vectors using `dtt_set_default_tz()`.
```{r}
dtt_default_tz()
date_time <- dtt_date_time("1970-01-01 03:00:00")
dtt_set_default_tz("Etc/GMT+10")
dtt_default_tz()
date_time
```
They can assign a new time zone to a POSIXct object whilst leaving the clock time unchanged using `dtt_set_tz()` or adjust the time zone so that clock (but not the actual) time is altered using `dtt_adjust_tz()`
```{r}
date_time
dtt_set_tz(date_time)
dtt_adjust_tz(date_time)
```
### Combining Dates and Times
`dttr2` makes it easy to decompose POSIXct vectors into Date and hms vectors and then recombine them again.
As neither dates nor times have associated time zones unless the user passes a value they are assigned the default time zone.
```{r}
date_time
date <- dtt_date(date_time)
date
time <- dtt_time(date_time)
time
dtt_date_time(date, time)
```
## Inspiration
dttr2 was influenced by [lubridate](https://lubridate.tidyverse.org).
It aims to provide an alternative for simple manipulations.
## Contribution
Please report any [issues](https://github.com/poissonconsulting/dttr2/issues).
[Pull requests](https://github.com/poissonconsulting/dttr2/pulls) are always welcome.
## Code of Conduct
Please note that the dttr2 project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.