tind (version 0.2.4)

time-index-components: Time Index Components (Years, Months, Days, ...)

Description

The following functions can be used to retrieve components of time indices.

year, quarter, month, week, day return year (0--9999), quarter (1--4), month (1--12), week (1--53, ISO 8601), and day (1--31) indices as integers. When month is invoked with labels argument set to TRUE, an ordered factor is returned.

day_of_week returns index (1--7) of weekday with Monday as the first day (as in ISO 8601). When invoked with labels argument set to TRUE, an ordered factor is returned.

day_of_year returns index (1--366) of the day of year as integer.

hour, minute, second return hour (0--23), minute (0--59), and second (0--59,999999) indices as integers and reals (for seconds). am and pm functions determine whether time falls in the first or second half of the day.

Methods weekdays, months, and quarters from package base are implemented but users are encouraged to use functions from tind package.

Usage

year(x)
quarter(x)
# S3 method for tind
quarters(x, abbreviate)
month(x, labels = FALSE, abbreviate = TRUE, locale = NULL)
# S3 method for tind
months(x, abbreviate = FALSE)
week(x)
day(x)
day_of_year(x)
day_of_week(x, labels = FALSE, abbreviate = TRUE, locale = NULL)
# S3 method for tind
weekdays(x, abbreviate = FALSE)
hour(x)
am(x)
pm(x)
minute(x)
second(x)

Value

All functions return integer vectors, except for second, which returns numeric vectors. Additionally, month and day_of_week

return ordered factors if invoked with argument labels set to TRUE.

Arguments

x

an object of tind class or an R object coercible to it.

abbreviate

a logical value, if TRUE, abbreviated names are returned; if FALSE, full names are returned. TRUE by default.

labels

a logical value, if TRUE month and weekday names are returned (as ordered factors) instead of integer indices (FALSE by default).

locale

(optional) a character value determining locale or NULL (the default, interpreted as the current system locale), see calendar-names for information on locale settings.

Details

year for week arguments need not necessarily return the same value as for days within the week in question when the week is the first or the last in a year.

tind package does not provide replacement methods for time index components. In order to change, say, month one can use tind constructor or %+m% operator (and similar operators), see Examples.

See Also

tind class, Ops for index increments / decrements and index differences, and calendar-names for names of months and days of weeks in the current locale. Further examples of use of these functions can be found in calendar documentation.

Examples

# current date and time
(nw <- now())
# show current year, quarter, month, ...
year(nw)
quarter(nw)
month(nw)
month(nw, labels = TRUE)
month(nw, labels = TRUE, abbreviate = FALSE)
week(nw)
day(nw)
day_of_week(nw)
day_of_week(nw, labels = TRUE)
day_of_week(nw, labels = TRUE, abbreviate = FALSE)
day_of_year(nw)
hour(nw)
minute(nw)
second(nw)

# alternatives to replacement, change month to December
(x <- as.date("2023-09-11"))
(x <- tind(y = year(x), m = 12, d = day(x)))
(x <- as.date("2023-09-11"))
(x <- x %+m% (12 - month(x)))