time_add: Arithmetics with periods

Description Usage Arguments Examples

View source: R/addition.R

Description

Add periods to date-time objects. Periods track the change in the "clock time" between two civil times. They are measured in common civil time units: years, months, days, hours, minutes, and seconds.

Arithmetic operations with multiple period units (years, months etc) are applied in decreasing size order, from year to second. Thus time_add(x, months = 1, days = 3) first adds 1 to x and then 3 days.

Generally period arithmetic is undefined due to the irregular nature of civil time and complexities with DST transitions. 'timechange' allows for a refined control of what happens when an addition of irregular periods (years, months, days) results in "unclear" date.

Let's start with an example. What happens when you add "1 month 3 days" to "2000-01-31 01:02:03"? 'timechange' operates by applying larger periods first. First months are added1 + 1 = February which results in non-existent time of 2000-02-31 01:02:03. Here the roll_month adjustment kicks in:

Usage

1
2
3
4
5
6
7
time_add(time, periods = NULL, years = NULL, months = NULL,
  weeks = NULL, days = NULL, hours = NULL, minutes = NULL,
  seconds = NULL, roll_month = "last", roll_dst = "first")

time_subtract(time, periods = NULL, years = NULL, months = NULL,
  weeks = NULL, days = NULL, hours = NULL, minutes = NULL,
  seconds = NULL, roll_month = "last", roll_dst = "last")

Arguments

time

date-time object

periods

string of units to add/subtract (not yet implemented) or a named list of the form list(years = 1, months = 2, ...).

years, months, weeks, days, hours, minutes, seconds

Units to be added to time. Each unit except for seconds must be expressed as integer values.

roll_month

controls how addition of months and years behaves when standard arithmetic rules exceed limits of the resulting date's month. See "Details" for the description of possible values.

roll_dst

controls how to adjust the updated time if it falls within a DST transition intervals. See the "Details".

Examples

 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
# Addition

## Month gap
x <- as.POSIXct("2000-01-31 01:02:03", tz = "America/Chicago")
time_add(x, months = 1, roll_month = "first")
time_add(x, months = 1, roll_month = "last")
time_add(x, months = 1, roll_month = "boundary")
time_add(x, months = 1, roll_month = "skip")
time_add(x, months = 1, roll_month = "NA")
time_add(x, months = 1, days = 3,  roll_month = "first")
time_add(x, months = 1, days = 3,  roll_month = "last")
time_add(x, months = 1, days = 3,  roll_month = "boundary")
time_add(x, months = 1, days = 3,  roll_month = "skip")
time_add(x, months = 1, days = 3,  roll_month = "NA")

## DST gap
x <- as.POSIXlt("2010-03-14 01:02:03", tz = "America/Chicago")
time_add(x, hours = 1, minutes = 50, roll_dst = "first")
time_add(x, hours = 1, minutes = 50, roll_dst = "last")
time_add(x, hours = 1, minutes = 50, roll_dst = "boundary")
time_add(x, hours = 1, minutes = 50, roll_dst = "skip")
time_add(x, hours = 1, minutes = 50, roll_dst = "NA")

# SUBTRACTION

## Month gap
x <- as.POSIXct("2000-03-31 01:02:03", tz = "America/Chicago")
time_subtract(x, months = 1, roll_month = "first")
time_subtract(x, months = 1, roll_month = "last")
time_subtract(x, months = 1, roll_month = "boundary")
time_subtract(x, months = 1, roll_month = "skip")
time_subtract(x, months = 1, roll_month = "NA")
time_subtract(x, months = 1, days = 3,  roll_month = "first")
time_subtract(x, months = 1, days = 3,  roll_month = "last")
time_subtract(x, months = 1, days = 3,  roll_month = "boundary")
time_subtract(x, months = 1, days = 3,  roll_month = "skip")
time_subtract(x, months = 1, days = 3,  roll_month = "NA")

## DST gap
y <- as.POSIXlt("2010-03-15 01:02:03", tz = "America/Chicago")
time_subtract(y, hours = 22, minutes = 50, roll_dst = "first")
time_subtract(y, hours = 22, minutes = 50, roll_dst = "last")
time_subtract(y, hours = 22, minutes = 50, roll_dst = "boundary")
time_subtract(y, hours = 22, minutes = 50, roll_dst = "skip")
time_subtract(y, hours = 22, minutes = 50, roll_dst = "NA")

timechange documentation built on April 26, 2018, 5:04 p.m.