Help for package dttr2

Title:

Manipulate Date, POSIXct and hms Vectors

Version:

0.5.2

Description:

Manipulates date ('Date'), date time ('POSIXct') and time ('hms') vectors. Date/times are considered discrete and are floored whenever encountered. Times are wrapped and time zones are maintained unless explicitly altered by the user.

License:

MIT + file LICENSE

URL:

https://github.com/poissonconsulting/dttr2, https://poissonconsulting.github.io/dttr2/

BugReports:

https://github.com/poissonconsulting/dttr2/issues

Depends:

R (≥ 4.0)

Imports:

chk (≥ 0.9.1), hms, lifecycle

Suggests:

rlang, spelling, testthat (≥ 3.0.0)

RdMacros:

lifecycle

Config/testthat/edition:

Encoding:

UTF-8

Language:

en-US

RoxygenNote:

7.3.2

NeedsCompilation:

Packaged:

2024-09-25 23:40:09 UTC; aylapearson

Author:

Joe Thorley

[aut], Ayla Pearson

[aut, cre], Poisson Consulting [cph, fnd]

Maintainer:

Ayla Pearson <ayla@poissonconsulting.ca>

Repository:

CRAN

Date/Publication:

2024-09-26 00:00:02 UTC

dttr2: Manipulate Date, POSIXct and hms Vectors

Description

Author(s)

Maintainer: Ayla Pearson ayla@poissonconsulting.ca (ORCID)

Authors:

Joe Thorley joe@poissonconsulting.ca (ORCID)

Other contributors:

Poisson Consulting [copyright holder, funder]

Missing Date

Description

A missing Date object

Usage

NA_Date_

Format

An object of class Date of length 1.

Missing POSIXct

Description

A missing POSIXct object

Usage

NA_POSIXct_

Format

An object of class POSIXct (inherits from POSIXt) of length 1.

Missing hms

Description

A missing hms object

Usage

NA_hms_

Format

An object of class hms (inherits from difftime) of length 1.

Check Time Zone

Description

Checks an object's time zone as returned by dtt_tz().

Usage

check_tz(x, tz = dtt_tz(x), x_name = substitute(x), error = TRUE)

Arguments

x

The object to check.

tz

A string of the time zone to check that x's matches.

x_name

A string of the name of the object.

error

A flag indicating whether to throw an informative error or immediately generate an informative message if the check fails.

Value

An invisible copy of x (if it doesn't throw an error).

Examples

check_tz(Sys.time(), "UTC", error = FALSE)

Check Time

Description

Checks if scalar hms object using vld_time().

Usage

chk_time(x, x_name = NULL)

Arguments

x

The object to check.

x_name

A string of the name of object x or NULL.

Value

NULL, invisibly. Called for the side effect of throwing an error if the condition is not met.

Examples

chk_time(hms::as_hms("10:00:10"))
try(chk_time(1))

dtt Object

Description

A dtt (short for date time) object is an object of class Date (date), POSIXct (datetime) or hms (time).

Add Time Units

Description

Add time units to a date time vector.

Usage

dtt_add_units(x, units, n = 1L)

dtt_add_years(x, n = 1L, ...)

dtt_add_months(x, n = 1L, ...)

dtt_add_days(x, n = 1L, ...)

dtt_add_hours(x, n = 1L, ...)

dtt_add_minutes(x, n = 1L, ...)

dtt_add_seconds(x, n = 1L, ...)

Arguments

x

A date/time vector.

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

n

An integer of the number of units.

...

Unused.

Value

The modified date time vector.

Examples

dtt_add_units(as.Date("1999-12-31"), "days")

Adjust Time Zone

Description

Adjusts the time zone so that clock (but not the actual) time is altered for a date time vector. Equivalent to lubridate::with_tz().

Usage

dtt_adjust_tz(x, tz = dtt_default_tz(), ...)

## S3 method for class 'POSIXct'
dtt_adjust_tz(x, tz = dtt_default_tz(), ...)

Arguments

x

A POSIXct vector.

tz

A string of the time zone.

...

Unused.

Value

The date time vector with the new time zone and time.

Methods (by class)

dtt_adjust_tz(POSIXct): Adjust the time zone for a POSIXct vector

Examples

dtt_adjust_tz(as.POSIXct("1970-01-01", tz = "Etc/GMT+8"), tz = "UTC")

Adjust Units

Description

Adjust Units

Usage

dtt_adjust_units(x, from = "seconds", to = "seconds")

Arguments

x

An integer or numeric vector

from

A string of the original units.

to

A string of the new units.

Value

A numeric vector.

Examples

dtt_adjust_units(60, to = "minutes")

Aggregate Date/Time

Description

Aggregates a date/time vector

Usage

dtt_aggregate(x, units, ...)

## S3 method for class 'Date'
dtt_aggregate(x, units = "days", ...)

## S3 method for class 'POSIXct'
dtt_aggregate(x, units = "seconds", ...)

## S3 method for class 'hms'
dtt_aggregate(x, units = "seconds", ...)

Arguments

x

A date/time vector.

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

...

Unused.

Details

The possible units values are 'seconds', 'minutes', 'hours', 'days', 'months' or 'years'.

Value

The floored date/time vector.

Methods (by class)

dtt_aggregate(Date): Aggregate a Date vector
dtt_aggregate(POSIXct): Aggregate a POSIXct vector
dtt_aggregate(hms): Aggregate a hms vector

Examples

dtt_aggregate(as.Date(c("1992-01-01", "1991-02-02", "1991-03-03")), "years")

Complete

Description

Completes date/time vector.

Usage

dtt_complete(x, ...)

## S3 method for class 'Date'
dtt_complete(
  x,
  from = min(x),
  to = max(x),
  units = "days",
  unique = TRUE,
  sort = TRUE,
  ...
)

## S3 method for class 'POSIXct'
dtt_complete(
  x,
  from = min(x),
  to = max(x),
  units = "seconds",
  unique = TRUE,
  sort = TRUE,
  ...
)

## S3 method for class 'hms'
dtt_complete(
  x,
  from = min(x),
  to = max(x),
  units = "seconds",
  unique = TRUE,
  sort = TRUE,
  ...
)

Arguments

x

A date/time vector.

...

Unused.

from

A date/time scalar of the start.

to

A date/time scalar of the end.

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

unique

A flag specifying whether to only return unique values.

sort

A flag specifying whether to sort the vector.

Value

The completed date/time vector.

Methods (by class)

dtt_complete(Date): Complete a Date sequence vector
dtt_complete(POSIXct): Complete a POSIXct sequence vector
dtt_complete(hms): Complete a hms sequence vector

Examples

dtt_complete(as.Date(c("2001-01-01", "2001-01-03", "2001-01-01")))

Completed

Description

Tests whether a date time is complete.

Usage

dtt_completed(x, ...)

## S3 method for class 'Date'
dtt_completed(x, units = "days", unique = TRUE, sorted = TRUE, ...)

## S3 method for class 'POSIXct'
dtt_completed(x, units = "seconds", unique = TRUE, sorted = TRUE, ...)

## S3 method for class 'hms'
dtt_completed(x, units = "seconds", unique = TRUE, sorted = TRUE, ...)

Arguments

x

A date/time vector.

...

Unused.

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

unique

A flag indicating whether the values must be unique.

sorted

A flag indicating whether the values must be sorted.

Value

A flag indicating whether complete.

Methods (by class)

dtt_completed(Date): Test if Date vector is complete
dtt_completed(POSIXct): Test if POSIXct vector is complete
dtt_completed(hms): Test if POSIXct vector is complete

Floor Date

Description

Coerces vectors to floored Date vectors.

Usage

dtt_date(x, ...)

dtt_date(x) <- value

## S3 method for class 'integer'
dtt_date(x, origin = as.Date("1970-01-01"), ...)

## S3 method for class 'double'
dtt_date(x, origin = as.Date("1970-01-01"), ...)

## S3 method for class 'character'
dtt_date(x, ...)

## S3 method for class 'Date'
dtt_date(x, ...)

## S3 method for class 'POSIXct'
dtt_date(x, ...)

## S3 method for class 'hms'
dtt_date(x, ...)

## S3 replacement method for class 'Date'
dtt_date(x) <- value

## S3 replacement method for class 'POSIXct'
dtt_date(x) <- value

dtt_set_date(x, value)

Arguments

x

A vector.

...

Unused.

value

A date vector.

origin

Origin date.

Value

A floored Date vector.

Methods (by class)

dtt_date(integer): Coerce integer vector to a floored Date vector
dtt_date(double): Coerce double vector to a floored Date vector
dtt_date(character): Coerce character vector to a floored Date vector
dtt_date(Date): Coerce Date vector to a floored Date vector
dtt_date(POSIXct): Coerce POSIXct vector to a floored Date vector
dtt_date(hms): Coerce hms vector to a floored Date vector

Functions

dtt_date(Date) <- value: Set date values for a Date vector
dtt_date(POSIXct) <- value: Set date values for a POSIXct vector

Examples

dtt_date(1L)
dtt_date(-1)
dtt_date("2000-01-01")
as.Date(as.POSIXct("2019-05-01", tz = "Etc/GMT-8"))
dtt_date(as.POSIXct("2019-05-01", tz = "Etc/GMT-8"))
dtt_date(hms::as_hms("23:59:59"))
dtt_date(hms::as_hms("24:00:00"))

Add Time to Date

Description

Adds times to Dates vector and sets timezone in a single function.

Usage

dtt_date_add_time(x, time, tz = dtt_default_tz())

Arguments

x

A Date vector.

time

A hms vector of the time.

tz

A string of the time zone.

Value

A POSIXct vector.

Examples

dtt_date_add_time(
  as.Date("2001-03-05"),
  hms::as_hms("06:07:08"),
  tz = "Etc/GMT+9"
)

Create Dates from Integers

Description

Create date object from vectors of year, month and day values.

Usage

dtt_date_from_ints(year = 1972L, month = 1L, day = 1L)

Arguments

year

An integer of the year. The default value is 1972.

month

An integer of the month between 1 and 12. The default value is the 1st month.

day

An integer of the day between 1 and 31. The default value is the 1st day.

Details

This can be very helpful when needing to create a date column in a data frame from year, month and days columns. Vectors must all be the same length or be of length one.

Value

A floored Date vector.

Examples

dtt_date_from_ints(
  year = 1991,
  month = 07,
  day = 23
)

dtt_date_from_ints(
  year = c(1991, 1992, 1993),
  month = c(07, 07, 07),
  day = c(23, 24, 21)
)

year_vals <- c(1991, 1992, 1993)
month_vals <- c(07, 07, 07)
day_vals <- c(23, 24, 21)
dtt_date_from_ints(year_vals, month_vals, day_vals)

year_vals <- 2022
month_vals <- 1:12
day_vals <- 15
dtt_date_from_ints(year_vals, month_vals, day_vals)

dtt_date_from_ints(year_vals, month_vals)

Floor Date/Time

Description

Coerces vectors to floored POSIXct vectors.

Usage

dtt_date_time(x, ...)

## S3 method for class 'integer'
dtt_date_time(x, tz = dtt_default_tz(), ...)

## S3 method for class 'double'
dtt_date_time(x, tz = dtt_default_tz(), ...)

## S3 method for class 'character'
dtt_date_time(x, tz = dtt_default_tz(), ...)

## S3 method for class 'Date'
dtt_date_time(x, time = hms::as_hms("00:00:00"), tz = dtt_default_tz(), ...)

## S3 method for class 'POSIXct'
dtt_date_time(x, tz = dtt_tz(x), ...)

## S3 method for class 'hms'
dtt_date_time(x, date = dtt_date("1970-01-01"), tz = dtt_default_tz(), ...)

Arguments

x

A vector.

...

Unused.

tz

A string of the time zone.

time

A hms vector of the time.

date

A Date vector of the date.

Value

A floored POSIXct vector.

Methods (by class)

dtt_date_time(integer): Coerce integer vector to a floored POSIXct vector
dtt_date_time(double): Coerce double vector to a floored POSIXct vector
dtt_date_time(character): Coerce character vector to a floored POSIXct vector
dtt_date_time(Date): Coerce Date vector to a floored POSIXct vector
dtt_date_time(POSIXct): Coerce POSIXct vector to a floored POSIXct vector
dtt_date_time(hms): Coerce hms vector to a floored POSIXct vector

Examples

dtt_date_time(1L)
dtt_date_time(-1)
dtt_date_time(1, tz = "Etc/GMT+8")
dtt_date_time(as.Date("2000-01-02"))
dtt_date_time(as.Date("2000-01-02"), time = hms::as_hms("04:05:06"))

Create Date Times from Integers

Description

Create date object from vectors of year, month and day values.

Usage

dtt_date_time_from_ints(
  year = 1972L,
  month = 1L,
  day = 1L,
  hour = 0L,
  minute = 0L,
  second = 0L,
  tz = dtt_default_tz()
)

Arguments

year

An integer of the year. The default value is 1972.

month

An integer of the month between 1 and 12. The default value is the 1st month.

day

An integer of the day between 1 and 31. The default value is the 1st day.

hour

An integer of the hour between 0 and 23.The default value is hour zero.

minute

An integer of the minute between 0 to 59. The default value is minute zero.

second

An integer of the second between 0 to 59. The default value is second zero.

tz

A string of the time zone.

Details

This can be very helpful when needing to create a date time column in a data frame from year, month, day, hour, minute, and second columns. Vectors must all be the same length or be of length one.

Value

A POSIXct vector

Examples

dtt_date_time_from_ints(
  year = 1991,
  month = 07,
  day = 23,
  hour = 06,
  minute = 25,
  second = 0,
  tz = "Etc/GMT+8"
)

dtt_date_time_from_ints(
  year = c(1991, 1992, 1993),
  month = c(07, 07, 07),
  day = c(23, 24, 21),
  hour = c(06, 05, 07),
  minute = c(25, 24, 15),
  second = c(0, 0, 0),
  tz = "Etc/GMT+8"
)

year <- c(1991, 1992, 1993)
month <- c(07, 08, 09)
day <- c(23, 24, 21)
hour <- c(06, 05, 07)
minute <- c(25, 24, 15)
second <- 30
dtt_date_time_from_ints(year, month, day, hour, minute, second)

dtt_date_time_from_ints(year, month, day)

Get and Set Day Values

Description

Gets and sets day values for date/time vectors.

Usage

dtt_day(x, ...)

dtt_day(x) <- value

## S3 method for class 'Date'
dtt_day(x, ...)

## S3 method for class 'POSIXct'
dtt_day(x, ...)

## S3 replacement method for class 'Date'
dtt_day(x) <- value

## S3 replacement method for class 'POSIXct'
dtt_day(x) <- value

dtt_days(x, ...)

dtt_days(x) <- value

dtt_set_day(x, value)

Arguments

x

A date/time vector.

...

Unused.

value

A integer vector of the day value(s).

Value

An integer vector (or the modified date/time vector).

Methods (by class)

dtt_day(Date): Get integer vector of day values for a Date vector
dtt_day(POSIXct): Get integer vector of day values for a POSIXct vector

Functions

dtt_day(Date) <- value: Set day values for a Date vector
dtt_day(POSIXct) <- value: Set day values for a POSIXct vector

Examples

x <- as.Date("1990-01-02")
dtt_day(x)
dtt_day(x) <- 27L
x

x <- as.POSIXct("1990-01-02 23:40:51")
dtt_day(x)
dtt_day(x) <- 27L
x

Get Decimal Day Values

Description

Gets decimal day values for date/time vectors.

Usage

dtt_day_decimal(x, ...)

## S3 method for class 'Date'
dtt_day_decimal(x, ...)

## S3 method for class 'POSIXct'
dtt_day_decimal(x, ...)

Arguments

x

A date/time vector.

...

Unused.

Value

A numeric vector.

Methods (by class)

dtt_day_decimal(Date): Get numeric vector of decimal year values for a Date vector
dtt_day_decimal(POSIXct): Get numeric vector of decimal year values for a POSIXct vector

Examples

x <- as.POSIXct("1990-01-03 10:00:01")
dtt_day_decimal(x)

Days in the Month

Description

Days in the Month

Usage

dtt_days_in_month(x)

Arguments

x

A Date or POSIXct vector.

Value

A integer vector of 28 to 31 indicating the days in the month.

Examples

dtt_days_in_month(as.Date(c("2000-02-11", "2001-02-01")))

Days in the Year

Description

Days in the Year

Usage

dtt_days_in_year(x)

Arguments

x

A Date or POSIXct vector.

Value

A integer vector of 365 and 366 indicates the days of the year.

Examples

dtt_days_in_year(as.Date(c("2000-10-11", "2001-01-01")))

Dayte

Description

Dayte

Usage

dtt_dayte(x, ...)

## S3 method for class 'Date'
dtt_dayte(x, start = 1L, ...)

## S3 method for class 'POSIXct'
dtt_dayte(x, start = 1L, ...)

Arguments

x

A date/time vector.

...

Unused.

start

An integer scalar of the starting month or a Date scalar of the starting date.

Value

A Date vector with the year set to year.

A Date vector of the daytes.

Methods (by class)

dtt_dayte(Date): Dayte a Date vector
dtt_dayte(POSIXct): Dayte a POSIXct vector

Examples

dtt_dayte(as.Date(c("2001-01-01", "2015-12-13")))

Dayte Time

Description

Dayte Time

Usage

dtt_dayte_time(x, ...)

## S3 method for class 'Date'
dtt_dayte_time(x, start = 1L, tz = dtt_default_tz(), ...)

## S3 method for class 'POSIXct'
dtt_dayte_time(x, start = 1L, ...)

Arguments

x

A date/time vector.

...

Unused.

start

An integer scalar of the starting month or a Date scalar of the starting date.

tz

A string of the time zone.

Value

A Date vector with the year set to year.

A POSIXct vector of the dayte times.

Methods (by class)

dtt_dayte_time(Date): Dayte Time a Date vector
dtt_dayte_time(POSIXct): Dayte Time a POSIXct vector

Examples

dtt_dayte_time(
  as.POSIXct(
    c("2001-01-01 12:13:14", "2015-12-13"),
    tz = "Etc/GMT+10"
  )
)

Dayte Time

Description

Dayte Time

Usage

dtt_daytt(x, start = 1L)

Arguments

x

A Date or POSIXct vector.

start

An integer vector of the starting month or a Date vector of the starting date.

Value

A Date or POSIXct vector with the year for February 29th as 1972.

Decade

Description

Decade

Usage

dtt_decade(x, ...)

## S3 method for class 'Date'
dtt_decade(x, ...)

Arguments

x

A date/time vector.

...

Unused.

Value

A integer vector of the decade.

Methods (by class)

dtt_decade(Date): Decade a Date vector

Examples

dtt_decade(as.Date(c("2001-01-01", "2015-12-13")))

Time Difference

Description

Gets the time difference in secs, minutes, hours, days or weeks. Uses difftime() but floors x and y first after coercing to POSIXct and adjusts the timezone of y to match that of x.

Usage

dtt_diff(x, y, units = "secs", as_difftime = FALSE)

Arguments

x

An object that can be coerced to a POSIXct using dtt_date_time().

y

An object that can be coerced to a POSIXct using dtt_date_time().

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

as_difftime

A flag specifying whether to return a difftime vector.

Value

A numeric vector of the time difference.

Examples

dtt_diff(
  as.Date(c("2001-01-02", "2000-12-31")),
  as.Date("2001-01-01"),
  "hours"
)
dtt_diff(as.Date("2001-01-02"), as.Date("2001-01-01"), "weeks")

Day of the Year

Description

Day of the Year

Usage

dtt_doy(x, ...)

Arguments

x

A Date or POSIXct vector.

...

Unused.

Value

A integer vector between 1 and 366 of the day of the year.

Examples

dtt_doy(Sys.Date())

Day of the Year Decimal

Description

Day of the Year Decimal

Usage

dtt_doy_decimal(x, ...)

Arguments

x

A Date or POSIXct vector.

...

Unused.

Value

A numeric vector between 0 and 366 of the day of the year.

Examples

dtt_doy_decimal(Sys.Date())

Day of the Year to Date

Description

Day of the Year to Date

Usage

dtt_doy_to_date(x, year = 1972L)

Arguments

x

An integer vector of the Day of the Year.

year

An integer scalar or vector of the year.

Value

A Date vector.

Examples

dtt_doy_to_date(3)

Convert Excel dates to dates.

Description

Converts Excel dates encoded as serial numbers to date class.

Usage

dtt_excel_to_date(x, modern = TRUE, ...)

Arguments

x

A vector of numbers to convert.

modern

A flag specifying whether to use the modern or old Excel date system.

...

Unused.

Details

Defaults to the modern Excel date encoding system. Excel for Mac 2008 and earlier Mac versions of Excel use a different date system. If the date 2016-01-01 is represented by 42370, it's the modern system. If it's 40908, it's the old system.

Value

A floored Date vector.

Examples

dtt_excel_to_date(42370)
dtt_excel_to_date(40908, modern = FALSE)

Convert Excel date times to date times.

Description

Converts Excel serial date times to date time class.

Usage

dtt_excel_to_date_time(x, tz = dtt_default_tz(), modern = TRUE, ...)

Arguments

x

A vector of numbers to convert.

tz

A string of the time zone.

modern

A flag specifying whether to use the modern or old Excel date system.

...

Unused.

Details

Value

A floored POSIXct vector.

Examples

dtt_excel_to_date_time(42370.1234)
dtt_excel_to_date_time(c(1000.1145, 43397.84578))
dtt_excel_to_date_time(45324.1234, tz = "UTC")
dtt_excel_to_date_time(42370.1234, modern = FALSE)

Convert Feb 29 to Feb 28

Description

Converts Feb 29 to Feb 28th

Usage

dtt_feb29_to_28(x)

Arguments

x

A Date or POSIXct vector.

Value

The modified Date or POSIXct vector.

Examples

dtt_feb29_to_28(as.Date("2004-02-29"))

Floor Date/Time

Description

Floors a date/time vector

Usage

dtt_floor(x, units, ...)

## S3 method for class 'Date'
dtt_floor(x, units = "days", ...)

## S3 method for class 'POSIXct'
dtt_floor(x, units = "seconds", ...)

## S3 method for class 'hms'
dtt_floor(x, units = "seconds", ...)

Arguments

x

A date/time vector.

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

...

Unused.

Value

The floored date/time vector.

Methods (by class)

dtt_floor(Date): Floor a Date vector
dtt_floor(POSIXct): Floor a POSIXct vector
dtt_floor(hms): Floor a hms vector

Examples

dtt_floor(hms::as_hms("23:59:59"), "hours")

Test Floored

Description

Test whether a date time vector is floored.

Usage

dtt_floored(x, ...)

## S3 method for class 'Date'
dtt_floored(x, units = "days", ...)

## S3 method for class 'POSIXct'
dtt_floored(x, units = "seconds", ...)

## S3 method for class 'hms'
dtt_floored(x, units = "seconds", ...)

Arguments

x

A Date, POSIXct or hms vector.

...

Unused.

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

Value

A flag indicating whether floored.

Methods (by class)

dtt_floored(Date): Test if Date vector is floored
dtt_floored(POSIXct): Test if POSIXct vector is floored
dtt_floored(hms): Test if hms vector is floored

Examples

dtt_floored(as.Date("2002-02-01"))

Get Decimal Hour Values

Description

Gets decimal hour values for date/time vectors.

Usage

dtt_hour_decimal(x, ...)

## S3 method for class 'Date'
dtt_hour_decimal(x, ...)

## S3 method for class 'POSIXct'
dtt_hour_decimal(x, ...)

## S3 method for class 'hms'
dtt_hour_decimal(x, ...)

Arguments

x

A date/time vector.

...

Unused.

Value

A numeric vector.

Methods (by class)

dtt_hour_decimal(Date): Get numeric vector of decimal hour values for a Date vector
dtt_hour_decimal(POSIXct): Get numeric vector of decimal hour values for a POSIXct vector
dtt_hour_decimal(hms): Get numeric vector of decimal hour values for a hms vector

Examples

x <- as.POSIXct("1990-01-02 23:40:51")
dtt_hour_decimal(x)
x <- hms::as_hms("23:40:51")
dtt_hour_decimal(x)

Get and Set Hour Values

Description

Gets and sets hour values for date/time vectors.

Usage

dtt_hours(x, ...)

dtt_hours(x) <- value

dtt_hour(x, ...)

dtt_hour(x) <- value

## S3 method for class 'Date'
dtt_hour(x, ...)

## S3 method for class 'POSIXct'
dtt_hour(x, ...)

## S3 method for class 'hms'
dtt_hour(x, ...)

## S3 replacement method for class 'POSIXct'
dtt_hour(x) <- value

## S3 replacement method for class 'hms'
dtt_hour(x) <- value

dtt_set_hour(x, value)

Arguments

x

A date/time vector.

...

Unused.

value

A integer vector of the hour value(s).

Value

An integer vector (or the modified date/time vector).

Methods (by class)

dtt_hour(Date): Get integer vector of hour values for a Date vector
dtt_hour(POSIXct): Get integer vector of hour values for a POSIXct vector
dtt_hour(hms): Get integer vector of hour values for a hms vector

Functions

dtt_hour(POSIXct) <- value: Set hour values for a POSIXct vector
dtt_hour(hms) <- value: Set hour values for a hms vector

Examples

x <- as.POSIXct("1990-01-02 23:40:51")
dtt_hour(x)
dtt_hour(x) <- 01L
x

x <- hms::as_hms("23:40:51")
dtt_hour(x)
dtt_hour(x) <- 01L
x

Is Date

Description

Is Date

Usage

dtt_is_date(x)

Arguments

x

An R object.

Value

A flag indicating whether R is a Date vector.

Is Date Time

Description

Is Date Time

Usage

dtt_is_date_time(x)

Arguments

x

An R object.

Value

A flag indicating whether R is a POSIXct vector.

Is Date or DateTime Object

Description

Is Date or DateTime Object

Usage

dtt_is_dtt(x)

Arguments

x

An R object.

Value

A flag indicating whether R is a Date or POSIXct vector.

Test for Leap Year

Description

Tests whether each year is a leap year.

Usage

dtt_leap_year(x)

Arguments

x

A date/time vector.

Value

A logical vector indicating whether each year is a leap year.

Examples

dtt_leap_year(as.Date("1999-03-04", "2000-02-01"))

Get Decimal Minute Values

Description

Gets decimal minute values for date/time vectors.

Usage

dtt_minute_decimal(x, ...)

## S3 method for class 'Date'
dtt_minute_decimal(x, ...)

## S3 method for class 'POSIXct'
dtt_minute_decimal(x, ...)

## S3 method for class 'hms'
dtt_minute_decimal(x, ...)

Arguments

x

A date/time vector.

...

Unused.

Value

A numeric vector.

Methods (by class)

dtt_minute_decimal(Date): Get numeric vector of decimal minute values for a Date vector
dtt_minute_decimal(POSIXct): Get numeric vector of decimal minute values for a POSIXct vector
dtt_minute_decimal(hms): Get numeric vector of decimal minute values for a hms vector

Examples

x <- as.POSIXct("1990-01-02 23:40:51")
dtt_minute_decimal(x)
x <- hms::as_hms("23:40:51")
dtt_minute_decimal(x)

Get and Set Minute Values

Description

Gets and sets minute values for date/time vectors.

Usage

dtt_minutes(x, ...)

dtt_minutes(x) <- value

dtt_minute(x, ...)

dtt_minute(x) <- value

## S3 method for class 'Date'
dtt_minute(x, ...)

## S3 method for class 'POSIXct'
dtt_minute(x, ...)

## S3 method for class 'hms'
dtt_minute(x, ...)

## S3 replacement method for class 'POSIXct'
dtt_minute(x) <- value

## S3 replacement method for class 'hms'
dtt_minute(x) <- value

dtt_set_minute(x, value)

Arguments

x

A date/time vector.

...

Unused.

value

A integer vector of the minute value(s).

Value

An integer vector (or the modified date/time vector).

Methods (by class)

dtt_minute(Date): Get integer vector of minute values for a Date vector
dtt_minute(POSIXct): Get integer vector of minute values for a POSIXct vector
dtt_minute(hms): Get integer vector of minute values for a hms vector

Functions

dtt_minute(POSIXct) <- value: Set minute values for a POSIXct vector
dtt_minute(hms) <- value: Set minute values for a hms vector

Examples

x <- as.POSIXct("1990-01-02 23:40:51")
dtt_minute(x)
dtt_minute(x) <- 27L
x

x <- hms::as_hms("23:40:51")
dtt_minute(x)
dtt_minute(x) <- 27L
x

Get Decimal Month Values

Description

Gets decimal month values for date/time vectors.

Usage

dtt_month_decimal(x, ...)

## S3 method for class 'Date'
dtt_month_decimal(x, ...)

## S3 method for class 'POSIXct'
dtt_month_decimal(x, ...)

Arguments

x

A date/time vector.

...

Unused.

Value

A numeric vector.

Methods (by class)

dtt_month_decimal(Date): Get numeric vector of decimal year values for a Date vector
dtt_month_decimal(POSIXct): Get numeric vector of decimal year values for a POSIXct vector

Examples

x <- as.POSIXct("1990-01-03 10:00:01")
dtt_month_decimal(x)

Get and Set Month Values

Description

Gets and sets month values for date/time vectors.

Usage

dtt_months(x, ...)

dtt_months(x) <- value

dtt_month(x, ...)

dtt_month(x) <- value

## S3 method for class 'Date'
dtt_month(x, ...)

## S3 method for class 'POSIXct'
dtt_month(x, ...)

## S3 replacement method for class 'Date'
dtt_month(x) <- value

## S3 replacement method for class 'POSIXct'
dtt_month(x) <- value

dtt_set_month(x, value)

Arguments

x

A date/time vector.

...

Unused.

value

A integer vector of the month value(s).

Value

An integer vector (or the modified date/time vector).

Methods (by class)

dtt_month(Date): Get integer vector of month values for a Date vector
dtt_month(POSIXct): Get integer vector of month values for a POSIXct vector

Functions

dtt_month(Date) <- value: Set month values for a Date vector
dtt_month(POSIXct) <- value: Set month values for a POSIXct vector

Examples

x <- as.Date("1990-01-02")
dtt_month(x)
dtt_month(x) <- 11L
x

x <- as.POSIXct("1990-01-02 23:40:51")
dtt_month(x)
dtt_month(x) <- 11L
x

Season

Description

Returns a factor of the user specified seasons.

Usage

dtt_season(
  x,
  start = c(Spring = 3L, Summer = 6L, Autumn = 9L, Winter = 12L),
  first = NULL
)

Arguments

x

A Date or POSIXct vector

start

A uniquely named integer vector of the first month of each season or a uniquely named Date vector of the first date of each season.

first

A string of the name of first season or NULL in which case the first season is that which includes Jan 1st.

Details

If the first month of the first season isn't January (1L), then the last season is considered to wrap into the following year.

Value

A factor of the seasons.

Examples

dates <- as.Date(c("2001-01-01", "2001-02-28", "2012-09-01", "2012-12-01"))
dtt_season(dates)
dtt_season(dates, start = c(Monsoon = 2L, `Dry Period` = 6L))
dtt_season(
  dates,
  start = c(First = dtt_date("2000-01-01"), Second = dtt_date("2000-06-01"))
)

Get and Set Second Values

Description

Gets and sets second values for date/time vectors.

Usage

dtt_seconds(x, ...)

dtt_seconds(x) <- value

dtt_second(x, ...)

dtt_second(x) <- value

## S3 method for class 'Date'
dtt_second(x, ...)

## S3 method for class 'POSIXct'
dtt_second(x, ...)

## S3 method for class 'hms'
dtt_second(x, ...)

## S3 replacement method for class 'POSIXct'
dtt_second(x) <- value

## S3 replacement method for class 'hms'
dtt_second(x) <- value

dtt_set_second(x, value)

Arguments

x

A date/time vector.

...

Unused.

value

A integer vector of the second value(s).

Value

An integer vector (or the modified date/time vector).

Methods (by class)

dtt_second(Date): Get integer vector of second values for a Date vector
dtt_second(POSIXct): Get integer vector of second values for a POSIXct vector
dtt_second(hms): Get integer vector of second values for a time vector

Functions

dtt_second(POSIXct) <- value: Set second values for a POSIXct vector
dtt_second(hms) <- value: Set second values for a hms vector

Examples

x <- as.POSIXct("1990-01-02 23:40:51")
dtt_second(x)
dtt_second(x) <- 27L
x

x <- hms::as_hms("23:40:51")
dtt_second(x)
dtt_second(x) <- 27L
x

Sequence

Description

Creates a date/time sequence vector. from and to are first floored and then a sequence is created by units. If length_out is defined then that number of units are added to from.

Usage

dtt_seq(from, to, units, length_out = NULL, ...)

## S3 method for class 'Date'
dtt_seq(from, to = from, units = "days", length_out = NULL, ...)

## S3 method for class 'POSIXct'
dtt_seq(from, to = from, units = "seconds", length_out = NULL, ...)

## S3 method for class 'hms'
dtt_seq(
  from,
  to = from,
  units = "seconds",
  length_out = NULL,
  wrap = TRUE,
  ...
)

Arguments

from

A date/time scalar of the start.

to

A date/time scalar of the end.

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

length_out

An integer of the number of units from from.

...

Unused.

wrap

A flag specifying whether to wrap hms vectors from 23:59:59 to 00:00:00

Value

The date/time vector.

Methods (by class)

dtt_seq(Date): Create a Date sequence vector
dtt_seq(POSIXct): Create a POSIXct sequence vector
dtt_seq(hms): Create a hms sequence vector

Examples

dtt_seq(as.Date("2001-01-01"), as.Date("2001-01-05"))

Floor Time

Description

Coerces vectors to floored (and wrapped) hms vectors.

Usage

dtt_set_time(x, value)

dtt_time(x, ...)

dtt_time(x) <- value

## S3 method for class 'integer'
dtt_time(x, ...)

## S3 method for class 'double'
dtt_time(x, ...)

## S3 method for class 'character'
dtt_time(x, ...)

## S3 method for class 'Date'
dtt_time(x, ...)

## S3 method for class 'hms'
dtt_time(x, ...)

## S3 method for class 'POSIXct'
dtt_time(x, ...)

## S3 method for class 'POSIXlt'
dtt_time(x, ...)

## S3 replacement method for class 'Date'
dtt_time(x) <- value

## S3 replacement method for class 'POSIXct'
dtt_time(x) <- value

Arguments

x

A vector.

value

A time vector.

...

Unused.

Value

A floored hms vector.

Methods (by class)

dtt_time(integer): Coerce integer vector to a floored hms vector
dtt_time(double): Coerce double vector to a floored hms vector
dtt_time(character): Coerce character vector to a floored hms vector
dtt_time(Date): Coerce Date vector to a floored hms vector
dtt_time(hms): Coerce hms vector to a floored hms vector
dtt_time(POSIXct): Coerce POSIXct vector to a floored hms vector
dtt_time(POSIXlt): Coerce POSIXlt vector to a floored hms vector

Functions

dtt_time(Date) <- value: Set time values for a Date vector
dtt_time(POSIXct) <- value: Set time values for a POSIXct vector

Examples

dtt_time(1L)
dtt_time(1.999)
dtt_time(-0.001)
dtt_time(Sys.Date())
dtt_time(as.POSIXct("2001-01-01 02:30:40"))
dtt_time(as.POSIXct("2001-01-01 02:30:40", tz = "Etc/GMT-8"))

Set Time Zone

Description

Sets the time zone for a date time vector without adjusting the clock time. Equivalent to lubridate::force_tz().

Usage

dtt_set_tz(x, tz = dtt_default_tz(), ...)

## S3 method for class 'POSIXct'
dtt_set_tz(x, tz = dtt_default_tz(), ...)

Arguments

x

A date/time vector.

tz

A string of the new time zone.

...

Unused.

Value

The date time vector with the new time zone.

Methods (by class)

dtt_set_tz(POSIXct): Set the time zone for a POSIXct vector

Examples

dtt_set_tz(as.POSIXct("1970-01-01", tz = "Etc/GMT+8"), tz = "UTC")

Study Year

Description

Study Year

Usage

dtt_study_year(x, start = 1L, full = TRUE)

Arguments

x

A Date or POSIXct vector.

start

An integer vector of the starting month or a Date vector of the starting date.

full

A flag specifying whether to return a character vector of the study years (or an integer vector of the first year)

Value

A character vector of the study year or an integer vector of the first year.

Examples

dtt_study_year(
  as.Date(c("2000-03-31", "2000-04-01", "2001-04-01")),
  start = 4L
)
dtt_study_year(
  as.Date(c("2000-03-31", "2000-04-01", "2001-04-01")),
  start = 4L,
  full = FALSE
)

Subtract Time Units

Description

Subtract time units from a date time vector.

Usage

dtt_subtract_units(x, n = 1L, units = dtt_units(x))

dtt_subtract_years(x, n = 1L)

dtt_subtract_months(x, n = 1L)

dtt_subtract_days(x, n = 1L)

dtt_subtract_hours(x, n = 1L)

dtt_subtract_minutes(x, n = 1L)

dtt_subtract_seconds(x, n = 1L)

Arguments

x

A date/time vector.

n

An integer of the number of units.

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

Value

The modified date time vector.

Examples

dtt_subtract_units(as.Date("1999-12-31"), 2L, "days")

Get System Date

Description

Get System Date

Usage

dtt_sys_date(tz = dtt_default_tz())

Arguments

tz

A string of the time zone.

Value

A floored Date scalar.

Examples

## Not run: 
dtt_set_default_tz("Etc/GMT+12")
dtt_sys_date()
dtt_set_default_tz("Etc/GMT-12")
dtt_sys_date()
dtt_sys_date(tz = "Etc/GMT+12")

## End(Not run)

Get System Date Time

Description

Get System Date Time

Usage

dtt_sys_date_time(tz = dtt_default_tz())

Arguments

tz

A string of the time zone.

Value

A floored POSIXct scalar.

Examples

## Not run: 
dtt_set_default_tz("UTC")
dtt_sys_date_time()
dtt_set_default_tz("Etc/GMT+8")
dtt_sys_date_time()
dtt_sys_date_time(tz = "UTC")

## End(Not run)

Get System Time

Description

Get System Time

Usage

dtt_sys_time(tz = dtt_default_tz())

Arguments

tz

A string of the time zone.

Value

A floored hms scalar.

Examples

## Not run: 
dtt_sys_time()

## End(Not run)

Get, Set or Reset Default Time Zone

Description

Get, Set or Reset Default Time Zone

Usage

dtt_sys_tz()

dtt_set_sys_tz(tz = NULL)

dtt_reset_sys_tz()

dtt_default_tz()

dtt_set_default_tz(tz = NULL)

dtt_reset_default_tz()

Arguments

tz

A string of the time zone.

Value

A string of the current or old time zone.

Functions

dtt_set_default_tz(): Set Default Time Zone
dtt_reset_default_tz(): Reset Default Time Zone

Examples

## Not run: 
dtt_default_tz()
old <- dtt_set_default_tz("Etc/GMT+8")
dtt_default_tz()
dtt_reset_default_tz()
dtt_default_tz()
dtt_set_default_tz(old)
dtt_default_tz()

## End(Not run)

Create Time from Vectors

Description

Pass vectors of hour, minute and second values to create a time object.

Usage

dtt_time_from_ints(hour = 0L, minute = 0L, second = 0L)

Arguments

hour

An integer of the hour between 0 and 23.The default value is hour zero.

minute

An integer of the minute between 0 to 59. The default value is minute zero.

second

An integer of the second between 0 to 59. The default value is second zero.

Details

This can be very helpful when needing to create a time column in a data frame from hour, minute and second columns. Vectors must all be the same length or be of length one.

Value

A floored hms vector.

Examples

dtt_time_from_ints()

dtt_time_from_ints(
  hour = 10,
  minute = 15,
  second = 30
)

dtt_time_from_ints(
  hour = c(10, 11),
  minute = c(15, 15),
  second = c(30, 0)
)

hour <- c(9, 10, 11)
minute <- c(15, 30, 45)
second <- 0
dtt_time_from_ints(hour, minute, second)

Get, Set or Adjust Time Zone

Description

Gets, sets or the time zone for a date time vector.

Usage

dtt_tz(x, ...)

## S3 method for class 'POSIXct'
dtt_tz(x, ...)

Arguments

x

A date/time vector.

...

Unused.

Value

A string of the time zone.

Methods (by class)

dtt_tz(POSIXct): Get the time zone for a POSIXct vector.

Examples

dtt_tz(as.POSIXct("1970-01-01", tz = "Etc/GMT+8"))

Get Units

Description

Gets the smallest units for a date time vector. The possible values are 'seconds', 'minutes', 'hours', 'days', 'months' or 'years'.

Usage

dtt_units(x, ...)

## S3 method for class 'Date'
dtt_units(x, ...)

## S3 method for class 'POSIXct'
dtt_units(x, ...)

## S3 method for class 'hms'
dtt_units(x, ...)

Arguments

x

A Date, POSIXct or hms vector.

...

Unused.

Value

A string indicating the date time units.

Methods (by class)

dtt_units(Date): Get time units for a Date vector
dtt_units(POSIXct): Get time units for a POSIXct vector
dtt_units(hms): Get time units for a hms vector

Examples

dtt_units(as.Date("2000-01-01"))
dtt_units(as.Date("2000-02-01"))
dtt_units(as.Date("2000-01-02"))

Units per Unit

Description

Units per Unit

Usage

dtt_units_per_unit(units = "seconds", unit = "days")

Arguments

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

unit

A string of the time unit.

Value

A number of the units per unit

Examples

dtt_units_per_unit("hours")

Get Week Day

Description

Gets the week days for the locale.

Usage

dtt_wday(x, abbr = FALSE, ...)

## Default S3 method:
dtt_wday(x, abbr = FALSE, ...)

Arguments

x

A date/time vector.

abbr

A flag specifying whether to abbreviate the week days.

...

Unused.

Value

An character vector of the week days.

Methods (by class)

dtt_wday(default): Get character vector of week days for a Date vector

Examples

x <- as.Date("1990-01-02")
dtt_wday(x)

x <- as.POSIXct("1990-01-02 23:40:51")
dtt_wday(x, abbr = TRUE)

Wrap

Description

Wrap

Usage

dtt_wrap(x, ...)

Arguments

x

A date/time vector.

...

Unused.

Examples

dtt_wrap(hms::as_hms("24:00:00"))

Get Decimal Year Values

Description

Gets decimal year values for date/time vectors.

Usage

dtt_year_decimal(x, ...)

## S3 method for class 'Date'
dtt_year_decimal(x, ...)

## S3 method for class 'POSIXct'
dtt_year_decimal(x, ...)

Arguments

x

A date/time vector.

...

Unused.

Value

A numeric vector.

Methods (by class)

dtt_year_decimal(Date): Get numeric vector of decimal year values for a Date vector
dtt_year_decimal(POSIXct): Get numeric vector of decimal year values for a POSIXct vector

Examples

x <- as.Date("1990-01-02")
dtt_year_decimal(x)

Get and Set Year Values

Description

Gets and sets year values for date/time vectors.

Usage

dtt_years(x, ...)

dtt_years(x) <- value

dtt_set_year(x, value)

dtt_year(x, ...)

dtt_year(x) <- value

## S3 method for class 'Date'
dtt_year(x, ...)

## S3 method for class 'POSIXct'
dtt_year(x, ...)

## S3 replacement method for class 'Date'
dtt_year(x) <- value

## S3 replacement method for class 'POSIXct'
dtt_year(x) <- value

Arguments

x

A date/time vector.

...

Unused.

value

A integer vector of the year value(s).

Value

An integer vector (or the modified date/time vector).

Methods (by class)

dtt_year(Date): Get integer vector of year values for a Date vector
dtt_year(POSIXct): Get integer vector of year values for a POSIXct vector

Functions

dtt_year(Date) <- value: Set year values for a Date vector
dtt_year(POSIXct) <- value: Set year values for a POSIXct vector

Examples

x <- as.Date("1990-01-02")
dtt_year(x)
dtt_year(x) <- 11L
x

x <- as.POSIXct("1990-01-02 23:40:51")
dtt_year(x)
dtt_year(x) <- 2022L
x

Is Date/Time

Description

Tests whether an object is a Date, POSIXct, or hms vector.

Usage

is.POSIXct(x)

is_date_time(x)

is.Date(x)

is_date(x)

is.hms(x)

is_time(x)

Arguments

x

An object

Value

A flag indicating whether x inherits from Date, POSIXct or hms.

Parameters for dttr2 functions

Description

Descriptions of the parameters for the dttr2 functions.

Arguments

x

A date/time vector.

...

Unused.

units

A string of the time units. The possible values are "secs", "minutes", "hours", "days" or "weeks".

unit

A string of the time unit.

tz

A string of the time zone.

n

An integer of the number of units.

from

A date/time scalar of the start.

to

A date/time scalar of the end.

start

An integer scalar of the starting month or a Date scalar of the starting date.

time

A hms vector of the time.

date

A Date vector of the date.

length_out

An integer of the number of units from from.

wrap

A flag specifying whether to wrap hms vectors from 23:59:59 to 00:00:00

abbr

A flag specifying whether to abbreviate the week days.

as_difftime

A flag specifying whether to return a difftime vector.

first

A string of the name of first season or NULL in which case the first season is that which includes Jan 1st.

y

An object that can be coerced to a POSIXct using dtt_date_time().

full

A flag specifying whether to return a character vector of the study years (or an integer vector of the first year)

sort

A flag specifying whether to sort the vector.

sorted

A flag indicating whether the values must be sorted.

x_name

A string of the name of the object.

error

A flag indicating whether to throw an informative error or immediately generate an informative message if the check fails.

origin

Origin date.

modern

A flag specifying whether to use the modern or old Excel date system.

Validate Time

Description

Validates that an object is scalar hms::hms object using inherits(x, class) && length(x) == 1L && !anyNA(x).

Usage

vld_time(x)

Arguments

x

The object to check.

Value

A flag indicating whether the condition was met.

Examples

vld_time(1)
vld_time(hms::as_hms("10:12:59"))

dttr2: Manipulate Date, POSIXct and hms Vectors

Description

Author(s)

See Also

Missing Date

Description

Usage

Format

Missing POSIXct

Description

Usage

Format

Missing hms

Description

Usage

Format

Check Time Zone

Description

Usage

Arguments

Value

See Also

Examples

Check Time

Description

Usage

Arguments

Value

See Also

Examples

dtt Object

Description

Add Time Units

Description

Usage

Arguments

Value

See Also

Examples

Adjust Time Zone

Description

Usage

Arguments

Value

Methods (by class)

See Also

Examples

Adjust Units

Description

Usage

Arguments

Value

See Also

Examples

Aggregate Date/Time

Description

Usage

Arguments

Details

Value

Methods (by class)

Examples

Complete

Description

Usage

Arguments

Value

Methods (by class)

See Also

Examples

Completed

Description

Usage

Arguments

Value

Methods (by class)

See Also

Floor Date

Description

Usage