Operators for datey, durationy and datey_interval

The unary - operator can be applied to a durationy to change its sign.

The following are the available binary operations on datey,durationy and datey_interval only operands, and their meaning:

Left	Operators	Right	Result	Notes
datey	== != < <= > >=	datey	logical	Comparisons for dates
durationy	== != < <= > >=	durationy	logical	Comparisons for durations
datey_interval	== !=	datey_interval	logical	Equality for date intervals
datey	-	datey	durationy	Duration between two dates
datey	+ -	durationy	datey	A date offset by a duration
durationy	+	datey	datey	A date offset by a duration
durationy	+ -	durationy	durationy	Duration addition and subtraction
datey	%to%	datey	datey_interval	Create a date interval – syntactic sugar for datey_interval()
datey_interval	%includes%	datey	logical	Whether an interval includes a date – syntactic sugar for interval_includes()
datey_interval	&	datey_interval	datey_interval	Intersection of two date intervals – NA_datey_interval_ if the intervals are disjoint and non-adjacent

dateys and durationys can also be mixed with numeric operands, in which case the datey or durationy is first converted to years, The following operations are implemented

• Comparison, i.e. a datey or durationy == != < <= > >= numeric or vice versa. Result is logical.

• datey addition and subtraction, i.e. a datey + - a numeric or vice versa. Result is double.

• durationy arithmetic, i.e. a durationy + - * / a numeric or vice versa. Result is double.

• The %to% operator accepts numbers, which are treated as years and coerced to datey.

• The %includes% operator accepts a number as its right hand operand, which is treated as years and coerced to datey.

When applied to datey_intervals, & is the 'intersection' operator. For intervals that do not intersect the result of & depends on whether the intervals are adjacent. If they are adjacent then the result is an empty interval starting (and ending) at the point in time they touch. Otherwise it is NA_datey_interval_. You can test whether intervals a and b intersect using is_collapsed(a & b).

Throughout the datey package, NA will cause an error when used where a datey, durationy or datey_interval is expected. This is because its type is logical and potentially indicates user error. If you want an NA value with a datey system type, use one of NA_datey_, NA_durationy_ or NA_datey_interval_.

Usage

# S3 method for class 'datey_type'
Ops(e1, e2)

Arguments

e1

First parameter.

e2

Second parameter (missing if a unary operator).

Value

See above table. In essence

• subtracting two dateys results in a durationy,

• comparing two Ts results in a logical,

• adding or subtracting a durationy to or from a T results in a T, and

• mixing durationy and datey with numeric operands first converts the durationy and datey to years and then results in standard numeric evaluation,

where T is either datey or durationy in each of the above.

See also

datey, durationy, datey_interval, vignette("datey", package = "datey") for a worked introduction

Examples

t_2000 <- datey(2000)
t_2001 <- datey(2001)
d_0.5 <- durationy(0.5)

t_2000
#> [1] 2000-01-01.0
t_2001
#> [1] 2001-01-01.0
d_0.5
#> [1] 0.5 yr

t_2001 - t_2000 # `datey` - `datey` is a `durationy`
#> [1] 1 yr
t_2000 + d_0.5  # `datey` + `durationy` is a `datey`
#> [1] 2000-07-02.0
t_2001 - d_0.5  # `datey` - `durationy` is a `datey`
#> [1] 2000-07-02.0
t_2000 + 0.5    # Arithmetic with numerics results in a double
#> [1] 2000.5
d_0.5 + d_0.5   # `durationy` + `durationy` is a `durationy`
#> [1] 1 yr
d_0.5 + 0.5     # Arithmetic with numerics results in a double
#> [1] 1
d_0.5 * 2       # Arithmetic with numerics results in a double
#> [1] 1

interval <- t_2000 %to% t_2001
interval
#> [1] [2000-01-01.0, 2001-01-01.0)

# %to% also accepts numbers:
2000 %to% 2001
#> [1] [2000-01-01.0, 2001-01-01.0)

interval %includes% t_2000 # TRUE -- start *is* included in an interval
#> [1] TRUE
interval %includes% (t_2000 + d_0.5) # TRUE
#> [1] TRUE
interval %includes% t_2001 # FALSE -- end is *not* included in an interval
#> [1] FALSE

# %includes% also accepts a number as its right hand operand:
interval %includes% 2000.5
#> [1] TRUE

# %includes% handling of NAs:
interval %includes% NA_datey_         # FALSE (not NA)
#> [1] FALSE
NA_datey_interval_ %includes% t_2000  # FALSE (not NA)
#> [1] FALSE

(2000 %to% 2020) & (2010 %to% 2030) # [2010-01-01.0, 2020-01-01.0)
#> [1] [2010-01-01.0, 2020-01-01.0)

# Non-intersecting *adjacent* intervals:
(2000 %to% 2001) & (2001 %to% 2002) # [2001-01-01.0, 2001-01-01.0)
#> [1] [2001-01-01.0, 2001-01-01.0)
# Non-intersecting *non*-adjacent intervals:
(1900 %to% 1901) & (2001 %to% 2001) # <NA>
#> [1] <NA>