Package 'clock'

Description

as_date() is a generic function that converts its input to a date (Date).

There are methods for converting date-times (POSIXct), calendars, time points, and zoned-times to dates.

For converting to a date-time, see as_date_time().

Usage

as_date(x, ...)

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

## S3 method for class 'POSIXt'
as_date(x, ...)

## S3 method for class 'clock_calendar'
as_date(x, ...)

## S3 method for class 'clock_time_point'
as_date(x, ...)

## S3 method for class 'clock_zoned_time'
as_date(x, ...)

Arguments

Details

Note that clock always assumes that R's Date class is naive, so converting a POSIXct to a Date will always retain the printed year, month, and day value.

This is not a drop-in replacement for as.Date(), as it only converts a limited set of types to Date. For parsing characters as dates, see date_parse(). For converting numerics to dates, see vctrs::new_date() or continue to use as.Date().

Value

A date with the same length as x.

Examples

x <- date_time_parse("2019-01-01 23:02:03", "America/New_York")

# R's `as.Date.POSIXct()` method defaults to changing the printed time
# to UTC before converting, which can result in odd conversions like this:
as.Date(x)

# `as_date()` will never change the printed time before converting
as_date(x)

# Can also convert from other clock types
as_date(year_month_day(2019, 2, 5))

Description

as_date_time() is a generic function that converts its input to a date-time (POSIXct).

There are methods for converting dates (Date), calendars, time points, and zoned-times to date-times.

For converting to a date, see as_date().

Usage

as_date_time(x, ...)

## S3 method for class 'POSIXt'
as_date_time(x, ...)

## S3 method for class 'Date'
as_date_time(x, zone, ..., nonexistent = NULL, ambiguous = NULL)

## S3 method for class 'clock_calendar'
as_date_time(x, zone, ..., nonexistent = NULL, ambiguous = NULL)

## S3 method for class 'clock_sys_time'
as_date_time(x, zone, ...)

## S3 method for class 'clock_naive_time'
as_date_time(x, zone, ..., nonexistent = NULL, ambiguous = NULL)

## S3 method for class 'clock_zoned_time'
as_date_time(x, ...)

Arguments

Details

Note that clock always assumes that R's Date class is naive, so converting a Date to a POSIXct will always attempt to retain the printed year, month, and day. Where possible, the resulting time will be at midnight (00:00:00), but in some rare cases this is not possible due to daylight saving time. If that issue ever arises, an error will be thrown, which can be resolved by explicitly supplying nonexistent or ambiguous.

This is not a drop-in replacement for as.POSIXct(), as it only converts a limited set of types to POSIXct. For parsing characters as date-times, see date_time_parse(). For converting numerics to date-times, see vctrs::new_datetime() or continue to use as.POSIXct().

Value

A date-time with the same length as x.

Examples

x <- as.Date("2019-01-01")

# `as.POSIXct()` will always treat Date as UTC, but will show the result
# of the conversion in your system time zone, which can be somewhat confusing
if (rlang::is_installed("withr")) {
  withr::with_timezone("UTC", print(as.POSIXct(x)))
  withr::with_timezone("Europe/Paris", print(as.POSIXct(x)))
  withr::with_timezone("America/New_York", print(as.POSIXct(x)))
}

# `as_date_time()` will treat Date as naive, which means that the original
# printed date will attempt to be kept wherever possible, no matter the
# time zone. The time will be set to midnight.
as_date_time(x, "UTC")
as_date_time(x, "Europe/Paris")
as_date_time(x, "America/New_York")

# In some rare cases, this is not possible.
# For example, in Asia/Beirut, there was a DST gap from
# 2021-03-27 23:59:59 -> 2021-03-28 01:00:00,
# skipping the 0th hour entirely.
x <- as.Date("2021-03-28")
try(as_date_time(x, "Asia/Beirut"))

# To resolve this, set a `nonexistent` time resolution strategy
as_date_time(x, "Asia/Beirut", nonexistent = "roll-forward")


# You can also convert to date-time from other clock types
as_date_time(year_month_day(2019, 2, 3, 03), "America/New_York")

Description

You generally convert to a duration from either a sys-time or a naive-time. The precision of the input is retained in the returned duration.

To round an existing duration to another precision, see duration_floor().

Usage

as_duration(x, ...)

Arguments

Value

A duration with the same precision as x.

Examples

x <- as_sys_time(year_month_day(2019, 01, 01))

# The number of days since 1970-01-01 UTC
as_duration(x)

x <- x + duration_seconds(1)
x

# The number of seconds since 1970-01-01 00:00:00 UTC
as_duration(x)

Description

as_iso_year_week_day() converts a vector to the iso-year-week-day calendar. Time points, Dates, POSIXct, and other calendars can all be converted to iso-year-week-day.

Usage

as_iso_year_week_day(x, ...)

Arguments

Value

A iso-year-week-day vector.

Examples

# From Date
as_iso_year_week_day(as.Date("2019-01-01"))

# From POSIXct, which assumes that the naive time is what should be converted
as_iso_year_week_day(as.POSIXct("2019-01-01 02:30:30", "America/New_York"))

# From other calendars
as_iso_year_week_day(year_quarter_day(2019, quarter = 2, day = 50))

Description

as_naive_time() converts x to a naive-time.

You can convert to a naive-time from any calendar type, as long as it has at least day precision. There also must not be any invalid dates. If invalid dates exist, they must first be resolved with invalid_resolve().

Converting to a naive-time from a sys-time or zoned-time retains the printed time, but drops the assumption that the time should be interpreted with any specific time zone.

Converting to a naive-time from a duration just wraps the duration in a naive-time object, there is no assumption about the time zone. The duration must have at least day precision.

There are convenience methods for converting to a naive-time from R's native date and date-time types. Like converting from a zoned-time, these retain the printed time.

Usage

as_naive_time(x, ...)

Arguments

Value

A naive-time vector.

Examples

x <- as.Date("2019-01-01")
as_naive_time(x)

ym <- year_month_day(2019, 02)

# A minimum of day precision is required
try(as_naive_time(ym))

ymd <- set_day(ym, 10)
as_naive_time(ymd)

Description

as_sys_time() converts x to a sys-time.

You can convert to a sys-time from any calendar type, as long as it has at least day precision. There also must not be any invalid dates. If invalid dates exist, they must first be resolved with invalid_resolve().

Converting to a sys-time from a naive-time retains the printed time, but adds an assumption that the time should be interpreted in the UTC time zone.

Converting to a sys-time from a zoned-time retains the underlying duration, but the printed time is the equivalent UTC time to whatever the zoned-time's zone happened to be.

Converting to a sys-time from a duration just wraps the duration in a sys-time object, adding the assumption that the time should be interpreted in the UTC time zone. The duration must have at least day precision.

There are convenience methods for converting to a sys-time from R's native date and date-time types. Like converting from a zoned-time, these retain the underlying duration, but will change the printed time if the zone was not already UTC.

Usage

as_sys_time(x, ...)

Arguments

Value

A sys-time vector.

Examples

x <- as.Date("2019-01-01")

# Dates are assumed to be naive, so the printed time is the same whether
# we convert it to sys-time or naive-time
as_sys_time(x)
as_naive_time(x)

y <- as.POSIXct("2019-01-01 01:00:00", tz = "America/New_York")

# The sys time displays the equivalent time in UTC (5 hours ahead of
# America/New_York at this point in the year)
as_sys_time(y)

ym <- year_month_day(2019, 02)

# A minimum of day precision is required
try(as_sys_time(ym))

ymd <- set_day(ym, 10)
as_sys_time(ymd)

Description

as_weekday() converts to a weekday type. This is normally useful for converting to a weekday from a sys-time or naive-time. You can use this function along with the circular arithmetic that weekday implements to easily get to the "next Monday" or "previous Sunday".

Usage

as_weekday(x, ...)

Arguments

Value

A weekday.

Examples

x <- as_naive_time(year_month_day(2019, 01, 05))

# This is a Saturday!
as_weekday(x)

# See the examples in `?weekday` for more usage.

Description

as_year_day() converts a vector to the year-day calendar. Time points, Dates, POSIXct, and other calendars can all be converted to year-day.

Usage

as_year_day(x, ...)

Arguments

Value

A year-day vector.

Examples

# From Date
as_year_day(as.Date("2019-05-01"))

# From POSIXct, which assumes that the naive time is what should be converted
as_year_day(as.POSIXct("2019-05-01 02:30:30", "America/New_York"))

# From other calendars
as_year_day(year_quarter_day(2019, quarter = 2, day = 50))

Description

as_year_month_day() converts a vector to the year-month-day calendar. Time points, Dates, POSIXct, and other calendars can all be converted to year-month-day.

Usage

as_year_month_day(x, ...)

Arguments

Value

A year-month-day vector.

Examples

# From Date
as_year_month_day(as.Date("2019-01-01"))

# From POSIXct, which assumes that the naive time is what should be converted
as_year_month_day(as.POSIXct("2019-01-01 02:30:30", "America/New_York"))

# From other calendars
as_year_month_day(year_quarter_day(2019, quarter = 2, day = 50))

Description

as_year_month_weekday() converts a vector to the year-month-weekday calendar. Time points, Dates, POSIXct, and other calendars can all be converted to year-month-weekday.

Usage

as_year_month_weekday(x, ...)

Arguments

Value

A year-month-weekday vector.

Examples

# From Date
as_year_month_weekday(as.Date("2019-01-01"))

# From POSIXct, which assumes that the naive time is what should be converted
as_year_month_weekday(as.POSIXct("2019-01-01 02:30:30", "America/New_York"))

# From other calendars
as_year_month_weekday(year_quarter_day(2019, quarter = 2, day = 50))

Description

as_year_quarter_day() converts a vector to the year-quarter-day calendar. Time points, Dates, POSIXct, and other calendars can all be converted to year-quarter-day.

Usage

as_year_quarter_day(x, ..., start = NULL)

Arguments

Value

A year-quarter-day vector.

Examples

# From Date
as_year_quarter_day(as.Date("2019-01-01"))
as_year_quarter_day(as.Date("2019-01-01"), start = 3)

# From POSIXct, which assumes that the naive time is what should be converted
as_year_quarter_day(as.POSIXct("2019-01-01 02:30:30", "America/New_York"))

# From other calendars
tuesday <- 3
as_year_quarter_day(year_month_weekday(2019, 2, tuesday, 2))

# Converting between `start`s
x <- year_quarter_day(2019, 01, 01, start = 2)
x

# Default keeps the same start
as_year_quarter_day(x)

# But you can change it
as_year_quarter_day(x, start = 1)

Description

as_year_week_day() converts a vector to the year-week-day calendar. Time points, Dates, POSIXct, and other calendars can all be converted to year-week-day.

Usage

as_year_week_day(x, ..., start = NULL)

Arguments

Value

A year-week-day vector.

Examples

# From Date
as_year_week_day(as.Date("2019-01-01"))
as_year_week_day(as.Date("2019-01-01"), start = clock_weekdays$monday)

# From POSIXct, which assumes that the naive time is what should be converted
as_year_week_day(as.POSIXct("2019-01-01 02:30:30", "America/New_York"))

# From other calendars
as_year_week_day(year_quarter_day(2019, quarter = 2, day = 50))

Description

as_zoned_time() converts x to a zoned-time. You generally convert to a zoned time from either a sys-time or a naive time. Each are documented on their own page:

• sys-time

• naive-time

There are also convenience methods for converting to a zoned time from native R date and date-time types:

• dates (Date)

• date-times (POSIXct / POSIXlt)

Usage

as_zoned_time(x, ...)

Arguments

Value

A zoned-time vector.

Examples

x <- as.Date("2019-01-01")
as_zoned_time(x, "Europe/London")

y <- as_naive_time(year_month_day(2019, 2, 1))
as_zoned_time(y, zone = "America/New_York")

Description

This is a Date method for the as_zoned_time() generic.

clock assumes that Dates are naive date-time types. Like naive-times, they have a yet-to-be-specified time zone. This method allows you to specify that time zone, keeping the printed time. If possible, the time will be set to midnight (see Details for the rare case in which this is not possible).

Usage

## S3 method for class 'Date'
as_zoned_time(x, zone, ..., nonexistent = NULL, ambiguous = NULL)

Arguments

Details

In the rare instance that the specified time zone does not contain a date-time at midnight due to daylight saving time, nonexistent can be used to resolve the issue. Similarly, if there are two possible midnight times due to a daylight saving time fallback, ambiguous can be used.

Value

A zoned-time.

Examples

x <- as.Date("2019-01-01")

# The resulting zoned-times have the same printed time, but are in
# different time zones
as_zoned_time(x, "UTC")
as_zoned_time(x, "America/New_York")

# Converting Date -> zoned-time is the same as naive-time -> zoned-time
x <- as_naive_time(year_month_day(2019, 1, 1))
as_zoned_time(x, "America/New_York")

# In Asia/Beirut, there was a DST gap from
# 2021-03-27 23:59:59 -> 2021-03-28 01:00:00,
# skipping the 0th hour entirely. This means there is no midnight value.
x <- as.Date("2021-03-28")
try(as_zoned_time(x, "Asia/Beirut"))

# To resolve this, set a `nonexistent` time resolution strategy
as_zoned_time(x, "Asia/Beirut", nonexistent = "roll-forward")

Description

This is a naive-time method for the as_zoned_time() generic.

Converting to a zoned-time from a naive-time retains the printed time, but changes the underlying duration, depending on the zone that you choose.

Naive-times are time points with a yet-to-be-determined time zone. By converting them to a zoned-time, all you are doing is specifying that time zone while attempting to keep all other printed information the same (if possible).

If you want to retain the underlying duration, try converting to a zoned-time from a sys-time, which is a time point interpreted as having a UTC time zone.

Usage

## S3 method for class 'clock_naive_time'
as_zoned_time(x, zone, ..., nonexistent = NULL, ambiguous = NULL)

Arguments

Value

A zoned-time vector.

Daylight Saving Time

Converting from a naive-time to a zoned-time is not always possible due to daylight saving time issues. There are two types of these issues:

Nonexistent times are the result of daylight saving time "gaps". For example, in the America/New_York time zone, there was a daylight saving time gap 1 second after "2020-03-08 01:59:59", where the clocks changed from 01:59:59 -> 03:00:00, completely skipping the 2 o'clock hour. This means that if you had a naive time of "2020-03-08 02:30:00", you couldn't convert that straight into a zoned-time with this time zone. To resolve these issues, the nonexistent argument can be used to specify one of many nonexistent time resolution strategies.

Ambiguous times are the result of daylight saving time "fallbacks". For example, in the America/New_York time zone, there was a daylight saving time fallback 1 second after "2020-11-01 01:59:59 EDT", at which point the clocks "fell backwards" by 1 hour, resulting in a printed time of "2020-11-01 01:00:00 EST" (note the EDT->EST shift). This resulted in two 1 o'clock hours for this day, so if you had a naive time of "2020-11-01 01:30:00", you wouldn't be able to convert that directly into a zoned-time with this time zone, as there is no way for clock to know which of the two ambiguous times you wanted. To resolve these issues, the ambiguous argument can be used to specify one of many ambiguous time resolution strategies.

Examples

library(magrittr)

x <- as_naive_time(year_month_day(2019, 1, 1))

# Converting a naive-time to a zoned-time generally retains the
# printed time, while changing the underlying duration.
as_zoned_time(x, "America/New_York")
as_zoned_time(x, "America/Los_Angeles")

# ---------------------------------------------------------------------------
# Nonexistent time:

new_york <- "America/New_York"

# There was a daylight saving gap in the America/New_York time zone on
# 2020-03-08 01:59:59 -> 03:00:00, which means that one of these
# naive-times don't exist in that time zone. By default, attempting to
# convert it to a zoned time will result in an error.
nonexistent_time <- year_month_day(2020, 03, 08, c(02, 03), c(45, 30), 00)
nonexistent_time <- as_naive_time(nonexistent_time)
try(as_zoned_time(nonexistent_time, new_york))

# Resolve this by specifying a nonexistent time resolution strategy
as_zoned_time(nonexistent_time, new_york, nonexistent = "roll-forward")
as_zoned_time(nonexistent_time, new_york, nonexistent = "roll-backward")

# Note that rolling backwards will choose the last possible moment in
# time at the current precision of the input
nonexistent_nanotime <- time_point_cast(nonexistent_time, "nanosecond")
nonexistent_nanotime
as_zoned_time(nonexistent_nanotime, new_york, nonexistent = "roll-backward")

# A word of caution - Shifting does not guarantee that the relative ordering
# of the input is maintained
shifted <- as_zoned_time(
  nonexistent_time,
  new_york,
  nonexistent = "shift-forward"
)
shifted

# 02:45:00 < 03:30:00
nonexistent_time[1] < nonexistent_time[2]
# 03:45:00 > 03:30:00 (relative ordering is lost)
shifted[1] < shifted[2]

# ---------------------------------------------------------------------------
# Ambiguous time:

new_york <- "America/New_York"

# There was a daylight saving time fallback in the America/New_York time
# zone on 2020-11-01 01:59:59 EDT -> 2020-11-01 01:00:00 EST, resulting
# in two 1 o'clock hours. This means that the following naive time is
# ambiguous since we don't know which of the two 1 o'clocks it belongs to.
# By default, attempting to convert it to a zoned time will result in an
# error.
ambiguous_time <- year_month_day(2020, 11, 01, 01, 30, 00)
ambiguous_time <- as_naive_time(ambiguous_time)
try(as_zoned_time(ambiguous_time, new_york))

# Resolve this by specifying an ambiguous time resolution strategy
earliest <- as_zoned_time(ambiguous_time, new_york, ambiguous = "earliest")
latest <- as_zoned_time(ambiguous_time, new_york, ambiguous = "latest")
na <- as_zoned_time(ambiguous_time, new_york, ambiguous = "NA")
earliest
latest
na

# Now assume that you were given the following zoned-times, i.e.,
# you didn't build them from scratch so you already know their otherwise
# ambiguous offsets
x <- c(earliest, latest)
x

# To set the seconds to 5 in both, you might try:
x_naive <- x %>%
  as_naive_time() %>%
  as_year_month_day() %>%
  set_second(5) %>%
  as_naive_time()

x_naive

# But this fails because you've "lost" the information about which
# offsets these ambiguous times started in
try(as_zoned_time(x_naive, zoned_time_zone(x)))

# To get around this, you can use that information by specifying
# `ambiguous = x`, which will use the offset from `x` to resolve the
# ambiguity in `x_naive` as long as `x` is also an ambiguous time with the
# same daylight saving time transition point as `x_naive` (i.e. here
# everything has a transition point of `"2020-11-01 01:00:00 EST"`).
as_zoned_time(x_naive, zoned_time_zone(x), ambiguous = x)

# Say you added one more time to `x` that would not be considered ambiguous
# in naive-time
x <- c(x, as_zoned_time(as_sys_time(latest) + 3600, zoned_time_zone(latest)))
x

# Imagine you want to floor this vector to a multiple of 2 hours, with
# an origin of 1am that day. You can do this by subtracting the origin,
# flooring, then adding it back
origin <- year_month_day(2019, 11, 01, 01, 00, 00) %>%
  as_naive_time() %>%
  as_duration()

x_naive <- x %>%
  as_naive_time() %>%
  add_seconds(-origin) %>%
  time_point_floor("hour", n = 2) %>%
  add_seconds(origin)

x_naive

# You again have ambiguous naive-time points, so you might try using
# `ambiguous = x`. It looks like this took care of the first two problems,
# but we have an issue at location 3.
try(as_zoned_time(x_naive, zoned_time_zone(x), ambiguous = x))

# When we floored from 02:30:00 -> 01:00:00, we went from being
# unambiguous -> ambiguous. In clock, this is something you must handle
# explicitly, and cannot be handled by using information from `x`. You can
# handle this while still retaining the behavior for the other two
# time points that were ambiguous before and after the floor by passing a
# list containing `x` and an ambiguous time resolution strategy to use
# when information from `x` can't resolve ambiguities:
as_zoned_time(x_naive, zoned_time_zone(x), ambiguous = list(x, "latest"))

Description

This is a POSIXct/POSIXlt method for the as_zoned_time() generic.

Converting from one of R's native date-time classes (POSIXct or POSIXlt) will retain the time zone of that object. There is no zone argument.

Usage

## S3 method for class 'POSIXt'
as_zoned_time(x, ...)

Arguments

Value

A zoned-time.

Examples

x <- as.POSIXct("2019-01-01", tz = "America/New_York")
as_zoned_time(x)

Description

This is a sys-time method for the as_zoned_time() generic.

Converting to a zoned-time from a sys-time retains the underlying duration, but changes the printed time, depending on the zone that you choose. Remember that sys-times are interpreted as UTC.

If you want to retain the printed time, try converting to a zoned-time from a naive-time, which is a time point with a yet-to-be-determined time zone.

Usage

## S3 method for class 'clock_sys_time'
as_zoned_time(x, zone, ...)

Arguments

Value

A zoned-time vector.

Examples

x <- as_sys_time(year_month_day(2019, 02, 01, 02, 30, 00))
x

# Since sys-time is interpreted as UTC, converting to a zoned-time with
# a zone of UTC retains the printed time
x_utc <- as_zoned_time(x, "UTC")
x_utc

# Converting to a different zone results in a different printed time,
# which corresponds to the exact same point in time, just in a different
# part of the work
x_ny <- as_zoned_time(x, "America/New_York")
x_ny

Description

calendar_group() groups at a multiple of the specified precision. Grouping alters the value of a single component (i.e. the month component if grouping by month). Components that are more precise than the precision being grouped at are dropped altogether (i.e. the day component is dropped if grouping by month).

Each calendar has its own help page describing the grouping process in more detail:

• year-month-day

• year-month-weekday

• year-week-day

• iso-year-week-day

• year-quarter-day

• year-day

Usage

calendar_group(x, precision, ..., n = 1L)

Arguments

Value

x grouped at the specified precision.

Examples

# See the calendar specific help pages for more examples
x <- year_month_day(2019, c(1, 1, 2, 2, 3, 3, 4, 4), 1:8)
x

# Group by two months
calendar_group(x, "month", n = 2)

# Group by two days of the month
calendar_group(x, "day", n = 2)

Description

calendar_leap_year() detects if the calendar year is a leap year - i.e. does it contain one or more extra components than other years?

A particular year is a leap year if:

• year_month_day(): February has 29 days.

• year_month_weekday(): February has a weekday that occurs 5 times.

• year_week_day(): There are 53 weeks in the year, resulting in 371 days in the year.

• iso_year_week_day(): There are 53 weeks in the year, resulting in 371 days in the year.

• year_quarter_day(): One of the quarters has 1 more day than normal (the quarter with an extra day depends on the start used, but will always be the same for a particular start). This aligns with Gregorian leap years for all starts except February, in which case the leap year is always 1 year after the Gregorian leap year.

• year_day(): There are 366 days in the year.

Usage

calendar_leap_year(x)

Arguments

Value

A logical vector the same size as x. Returns TRUE if in a leap year, FALSE if not in a leap year, and NA if x is NA.

Examples

x <- year_month_day(c(2019:2024, NA))
calendar_leap_year(x)

# For year-quarter-day, the leap year typically aligns with the Gregorian
# leap year, unless the `start` is February, in which case the leap year is
# always 1 year after the Gregorian leap year
x <- year_quarter_day(2020:2021, start = clock_months$january)
calendar_leap_year(x)

x <- year_quarter_day(2020:2021, start = clock_months$february)
calendar_leap_year(x)

# With a January start, 2020 has the extra day
get_day(year_quarter_day(2020, 1:4, "last", start = clock_months$january))
get_day(year_quarter_day(2021, 1:4, "last", start = clock_months$january))
get_day(year_quarter_day(2022, 1:4, "last", start = clock_months$january))

# With a February start, 2021 has the extra day
get_day(year_quarter_day(2020, 1:4, "last", start = clock_months$february))
get_day(year_quarter_day(2021, 1:4, "last", start = clock_months$february))
get_day(year_quarter_day(2022, 1:4, "last", start = clock_months$february))

Description

calendar_month_factor() extracts the month values from a calendar and converts them to an ordered factor of month names. This can be useful in combination with ggplot2, or for modeling.

This function is only relevant for calendar types that use a month field, i.e. year_month_day() and year_month_weekday(). The calendar type must have at least month precision.

Usage

calendar_month_factor(x, ..., labels = "en", abbreviate = FALSE)

Arguments

Value

An ordered factor representing the months.

Examples

x <- year_month_day(2019, 1:12)

calendar_month_factor(x)
calendar_month_factor(x, abbreviate = TRUE)
calendar_month_factor(x, labels = "fr")

Description

calendar_narrow() narrows x to the specified precision. It does so by dropping components that represent a precision that is finer than precision.

Each calendar has its own help page describing the precisions that you can narrow to:

• year-month-day

• year-month-weekday

• year-week-day

• iso-year-week-day

• year-quarter-day

• year-day

Usage

calendar_narrow(x, precision)

Arguments

Details

A subsecond precision x cannot be narrowed to another subsecond precision. You cannot narrow from, say, "nanosecond" to "millisecond" precision. clock operates under the philosophy that once you have set the subsecond precision of a calendar, it is "locked in" at that precision. If you expected this to use integer division to divide the nanoseconds by 1e6 to get to millisecond precision, you probably want to convert to a time point first, and use time_point_floor().

Value

x narrowed to the supplied precision.

Examples

# Hour precision
x <- year_month_day(2019, 1, 3, 4)
x

# Narrowed to day precision
calendar_narrow(x, "day")

# Or month precision
calendar_narrow(x, "month")

Description

calendar_precision() extracts the precision from a calendar object. It returns the precision as a single string.

Usage

calendar_precision(x)

Arguments

Value

A single string holding the precision of the calendar.

Examples

calendar_precision(year_month_day(2019))
calendar_precision(year_month_day(2019, 1, 1))
calendar_precision(year_quarter_day(2019, 3))

Description

calendar_spanning_seq() generates a regular sequence along the span of x, i.e. along ⁠[min(x), max(x)]⁠. The sequence is generated at the precision of x.

Importantly, sequences can only be generated if the underlying seq() method for the calendar in question supports a from and to value at the same precision as x. For example, you can't compute a day precision spanning sequence for a year_month_day() calendar (you can only compute a year and month one). To create a day precision sequence, you'd have to convert to a time-point first. See the individual seq() method documentation to learn what precisions are allowed.

Usage

calendar_spanning_seq(x)

Arguments

Details

Missing values are automatically removed before the sequence is generated.

If you need more precise sequence generation, call range() and seq() directly.

Value

A sequence along ⁠[min(x), max(x)]⁠.

Examples

x <- year_month_day(c(2019, 2022, 2020), c(2, 5, 3))
x

# Month precision spanning sequence
calendar_spanning_seq(x)

# Quarter precision:
x <- year_quarter_day(c(2005, 2006, 2003), c(4, 2, 3))
calendar_spanning_seq(x)

# Can't generate sequences if `seq()` doesn't allow the precision
x <- year_month_day(2019, c(1, 2, 1), c(20, 3, 25))
try(calendar_spanning_seq(x))

# Generally this means you need to convert to a time point and use
# `time_point_spanning_seq()` instead
time_point_spanning_seq(as_sys_time(x))

Description

calendar_widen() widens x to the specified precision. It does so by setting new components to their smallest value.

Each calendar has its own help page describing the precisions that you can widen to:

• year-month-day

• year-month-weekday

• year-week-day

• iso-year-week-day

• year-quarter-day

• year-day

Usage

calendar_widen(x, precision)

Arguments

Details

A subsecond precision x cannot be widened. You cannot widen from, say, "millisecond" to "nanosecond" precision. clock operates under the philosophy that once you have set the subsecond precision of a calendar, it is "locked in" at that precision. If you expected this to multiply the milliseconds by 1e6 to get to nanosecond precision, you probably want to convert to a time point first, and use time_point_cast().

Generally, clock treats calendars at a specific precision as a range of values. For example, a month precision year-month-day is treated as a range over ⁠[yyyy-mm-01, yyyy-mm-last]⁠, with no assumption about the day of the month. However, occasionally it is useful to quickly widen a calendar, assuming that you want the beginning of this range to be used for each component. This is where calendar_widen() can come in handy.

Value

x widened to the supplied precision.

Examples

# Month precision
x <- year_month_day(2019, 1)
x

# Widen to day precision
calendar_widen(x, "day")

# Or second precision
calendar_widen(x, "second")

Description

• calendar_start() computes the start of a calendar at a particular precision, such as the "start of the quarter".

• calendar_end() computes the end of a calendar at a particular precision, such as the "end of the month".

For both calendar_start() and calendar_end(), the precision of x is always retained.

Each calendar has its own help page describing the precisions that you can compute a boundary at:

• year-month-day

• year-month-weekday

• year-week-day

• iso-year-week-day

• year-quarter-day

• year-day

Usage

calendar_start(x, precision)

calendar_end(x, precision)

Arguments

Value

x at the same precision, but with some components altered to be at the boundary value.

Examples

# Hour precision
x <- year_month_day(2019, 2:4, 5, 6)
x

# Compute the start of the month
calendar_start(x, "month")

# Or the end of the month, notice that the hour value is adjusted as well
calendar_end(x, "month")

Description

calendar_count_between() counts the number of precision units between start and end (i.e., the number of years or months). This count corresponds to the whole number of units, and will never return a fractional value.

This is suitable for, say, computing the whole number of years or months between two calendar dates, accounting for the day and time of day.

Each calendar has its own help page describing the precisions that you can count at:

• year-month-day

• year-month-weekday

• year-week-day

• iso-year-week-day

• year-quarter-day

• year-day

Usage

calendar_count_between(start, end, precision, ..., n = 1L)

Arguments

Value

An integer representing the number of precision units between start and end.

Comparison Direction

The computed count has the property that if start <= end, then ⁠start + <count> <= end⁠. Similarly, if start >= end, then ⁠start + <count> >= end⁠. In other words, the comparison direction between start and end will never change after adding the count to start. This makes this function useful for repeated count computations at increasingly fine precisions.

Examples

# Number of whole years between these dates
x <- year_month_day(2000, 01, 05)
y <- year_month_day(2005, 01, 04:06)

# Note that `2000-01-05 -> 2005-01-04` is only 4 full years
calendar_count_between(x, y, "year")

Description

When parsing and formatting dates, you often need to know how weekdays of the week and months are represented as text. These functions allow you to either create your own labels, or look them up from a standard set of language specific labels. The standard list is derived from ICU (https://unicode-org.github.io/icu/) via the stringi package.

• clock_labels_lookup() looks up a set of labels from a given language code.

• clock_labels_languages() lists the language codes that are accepted.

• clock_labels() lets you create your own set of labels. Use this if the currently supported languages don't meet your needs.

Usage

clock_labels(
  month,
  month_abbrev = month,
  weekday,
  weekday_abbrev = weekday,
  am_pm
)

clock_labels_lookup(language)

clock_labels_languages()

Arguments

Value

A "clock_labels" object.

Examples

clock_labels_lookup("en")
clock_labels_lookup("ko")
clock_labels_lookup("fr")

Description

A clock locale contains the information required to format and parse dates. The defaults have been chosen to match US English. A clock locale object can be provided to format() methods or parse functions (like year_month_day_parse()) to override the defaults.

Usage

clock_locale(labels = "en", decimal_mark = ".")

Arguments

Value

A "clock_locale" object.

Examples

clock_locale()
clock_locale(labels = "fr")

Description

This is the landing page for all clock arithmetic functions. There are specific sub-pages describing how arithmetic works for different calendars and time points, which is where you should look for more information.

Calendars are efficient at arithmetic with irregular units of time, such as month, quarters, or years.

• year-month-day

• year-month-weekday

• year-quarter-day

• year-week-day

• iso-year-week-day

• year-day

Time points, such as naive-times and sys-times, are efficient at arithmetic with regular, well-defined units of time, such as days, hours, seconds, or nanoseconds.

• time-point

Durations can use any of these arithmetic functions, and return a new duration with a precision corresponding to the common type of the input and the function used.

• duration

Weekdays can perform day-based circular arithmetic.

• weekday

There are also convenience methods for doing arithmetic directly on a native R date or date-time type:

• dates (Date)

• date-times (POSIXct / POSIXlt)

Usage

add_years(x, n, ...)

add_quarters(x, n, ...)

add_months(x, n, ...)

add_weeks(x, n, ...)

add_days(x, n, ...)

add_hours(x, n, ...)

add_minutes(x, n, ...)

add_seconds(x, n, ...)

add_milliseconds(x, n, ...)

add_microseconds(x, n, ...)

add_nanoseconds(x, n, ...)

Arguments

Details

x and n are recycled against each other using tidyverse recycling rules.

Months and years are considered "irregular" because some months have more days then others (28, 29, 30, or 31), and some years have more days than others (365 or 366).

Days are considered "regular" because they are defined as 86,400 seconds.

Value

x after performing the arithmetic.

Examples

# See each sub-page for more specific examples
x <- year_month_day(2019, 2, 1)
add_months(x, 1)

Description

Objects with useful mappings from month names and weekday names to integer codes.

Month codes (clock_months)

• january == 1

• february == 2

• march == 3

• april == 4

• may == 5

• june == 6

• july == 7

• august == 8

• september == 9

• october == 10

• november == 11

• december == 12

Weekday codes (clock_weekdays)

• sunday == 1

• monday == 2

• tuesday == 3

• wednesday == 4

• thursday == 5

• friday == 6

• saturday == 7

ISO weekday codes (clock_iso_weekdays)

• monday == 1

• tuesday == 2

• wednesday == 3

• thursday == 4

• friday == 5

• saturday == 6

• sunday == 7

Usage

clock_months

clock_weekdays

clock_iso_weekdays

Format

• clock_months: An environment containing month codes.

• clock_weekdays: An environment containing weekday codes.

• clock_iso_weekdays: An environment containing ISO weekday codes.

Examples

weekday(clock_weekdays$wednesday)

year_month_weekday(2019, clock_months$april, clock_weekdays$monday, 1:4)

year_week_day(2020, 52, start = clock_weekdays$monday)

iso_year_week_day(2020, 52, clock_iso_weekdays$thursday)

Description

This family of functions extract fields from a calendar vector. Each calendar has its own set of supported getters, which are documented on their own help page:

• year-month-day

• year-month-weekday

• year-week-day

• iso-year-week-day

• year-quarter-day

• year-day

There are also convenience methods for extracting certain components directly from R's native date and date-time types.

• dates (Date)

• date-times (POSIXct / POSIXlt)

Usage

get_year(x)

get_quarter(x)

get_month(x)

get_week(x)

get_day(x)

get_hour(x)

get_minute(x)

get_second(x)

get_millisecond(x)

get_microsecond(x)

get_nanosecond(x)

get_index(x)

Arguments

Details

You cannot extract components directly from a time point type, such as sys-time or naive-time. Convert it to a calendar type first. Similarly, a zoned-time must be converted to either a sys-time or naive-time, and then to a calendar type, to be able to extract components from it.

Value

The component.

Examples

x <- year_month_day(2019, 1:3, 5:7, 1, 20, 30)
get_month(x)
get_day(x)
get_second(x)

Description

This family of functions is for working with invalid calendar dates.

Invalid dates represent dates made up of valid individual components, which taken as a whole don't represent valid calendar dates. For example, for year_month_day() the following component ranges are valid: ⁠year: [-32767, 32767]⁠, ⁠month: [1, 12]⁠, ⁠day: [1, 31]⁠. However, the date 2019-02-31 doesn't exist even though it is made up of valid components. This is an example of an invalid date.

Invalid dates are allowed in clock, provided that they are eventually resolved by using invalid_resolve() or by manually resolving them through arithmetic or setter functions.

Usage

invalid_detect(x)

invalid_any(x)

invalid_count(x)

invalid_remove(x)

invalid_resolve(x, ..., invalid = NULL)

Arguments

Details

Invalid dates must be resolved before converting them to a time point.

It is recommended to use "previous" or "next" for resolving invalid dates, as these ensure that relative ordering among x is maintained. This is a often a very important property to maintain when doing time series data analysis. See the examples for more information.

Value

• invalid_detect(): Returns a logical vector detecting invalid dates.

• invalid_any(): Returns TRUE if any invalid dates are detected.

• invalid_count(): Returns a single integer containing the number of invalid dates.

• invalid_remove(): Returns x with invalid dates removed.

• invalid_resolve(): Returns x with invalid dates resolved using the invalid strategy.

Examples

# Invalid date
x <- year_month_day(2019, 04, 30:31, c(3, 2), 30, 00)
x

invalid_detect(x)

# Previous valid moment in time
x_previous <- invalid_resolve(x, invalid = "previous")
x_previous

# Previous valid day, retaining time of day
x_previous_day <- invalid_resolve(x, invalid = "previous-day")
x_previous_day

# Note that `"previous"` retains the relative ordering in `x`
x[1] < x[2]
x_previous[1] < x_previous[2]

# But `"previous-day"` here does not!
x_previous_day[1] < x_previous_day[2]

# Remove invalid dates entirely
invalid_remove(x)

y <- year_quarter_day(2019, 1, 90:92)
y

# Overflow rolls forward by the number of days between `y` and the previous
# valid date
invalid_resolve(y, invalid = "overflow")

Description

This family of functions sets fields in a calendar vector. Each calendar has its own set of supported setters, which are documented on their own help page:

• year-month-day

• year-month-weekday

• year-week-day

• iso-year-week-day

• year-quarter-day

• year-day

There are also convenience methods for setting certain components directly on R's native date and date-time types.

• dates (Date)

• date-times (POSIXct / POSIXlt)

Some general rules about setting components on calendar types:

• You can only set components that are relevant to the calendar type that you are working with. For example, you can't set the quarter of a year-month-day type. You'd have to convert to year-quarter-day first.

• You can set a component that is at the current precision, or one level of precision more precise than the current precision. For example, you can set the day field of a month precision year-month-day type, but not the hour field.

• Setting a component can result in an invalid date, such as set_day(year_month_day(2019, 02), 31), as long as it is eventually resolved either manually or with a strategy from invalid_resolve().

• With sub-second precisions, you can only set the component corresponding to the precision that you are at. For example, you can set the nanoseconds of the second while at nanosecond precision, but not milliseconds.

Usage

set_year(x, value, ...)

set_quarter(x, value, ...)

set_month(x, value, ...)

set_week(x, value, ...)

set_day(x, value, ...)

set_hour(x, value, ...)

set_minute(x, value, ...)

set_second(x, value, ...)

set_millisecond(x, value, ...)

set_microsecond(x, value, ...)

set_nanosecond(x, value, ...)

set_index(x, value, ...)

Arguments

Details

You cannot set components directly on a time point type, such as sys-time or naive-time. Convert it to a calendar type first. Similarly, a zoned-time must be converted to either a sys-time or naive-time, and then to a calendar type, to be able to set components on it.

Value

x with the component set.

Examples

x <- year_month_day(2019, 1:3)

# Set the day
set_day(x, 12:14)

# Set to the "last" day of the month
set_day(x, "last")

Description

date_build() builds a Date from it's individual components.

Usage

date_build(year, month = 1L, day = 1L, ..., invalid = NULL)

Arguments

Details

Components are recycled against each other using tidyverse recycling rules.

Value

A Date.

Examples

date_build(2019)
date_build(2019, 1:3)

# Generating invalid dates will trigger an error
try(date_build(2019, 1:12, 31))

# You can resolve this with `invalid`
date_build(2019, 1:12, 31, invalid = "previous")

# But this particular case (the last day of the month) is better
# specified as:
date_build(2019, 1:12, "last")

Description

date_count_between() counts the number of precision units between start and end (i.e., the number of years or months or hours). This count corresponds to the whole number of units, and will never return a fractional value.

This is suitable for, say, computing the whole number of years or months between two dates, accounting for the day and time of day.

There are separate help pages for counting for dates and date-times:

• dates (Date)

• date-times (POSIXct/POSIXlt)

Usage

date_count_between(start, end, precision, ..., n = 1L)

Arguments

Value

An integer representing the number of precision units between start and end.

Comparison Direction

The computed count has the property that if start <= end, then ⁠start + <count> <= end⁠. Similarly, if start >= end, then ⁠start + <count> >= end⁠. In other words, the comparison direction between start and end will never change after adding the count to start. This makes this function useful for repeated count computations at increasingly fine precisions.

Examples

# See method specific documentation for more examples

start <- date_parse("2000-05-05")
end <- date_parse(c("2020-05-04", "2020-05-06"))

# Age in years
date_count_between(start, end, "year")

# Number of "whole" months between these dates
date_count_between(start, end, "month")

Description

date_format() formats a date (Date) or date-time (POSIXct/POSIXlt) using a format string.

There are separate help pages for formatting dates and date-times:

• dates (Date)

• date-times (POSIXct/POSIXlt)

Usage

date_format(x, ...)

Arguments

Value

A character vector of the formatted input.

Examples

# See method specific documentation for more examples

x <- as.Date("2019-01-01")
date_format(x, format = "year: %Y, month: %m, day: %d")

Description

date_group() groups by a single component of a date-time, such as month of the year, or day of the month.

There are separate help pages for grouping dates and date-times:

• dates (Date)

• date-times (POSIXct/POSIXlt)

Usage

date_group(x, precision, ..., n = 1L)

Arguments

Value

x, grouped at precision.

Examples

# See type specific documentation for more examples
date_group(as.Date("2019-01-01") + 0:5, "day", n = 2)

Description

date_leap_year() detects if the year is a leap year.

Usage

date_leap_year(x)

Arguments

Value

A logical vector the same size as x. Returns TRUE if in a leap year, FALSE if not in a leap year, and NA if x is NA.

Examples

x <- as.Date("2019-01-01")
x <- add_years(x, 0:5)
date_leap_year(x)

y <- as.POSIXct("2019-01-01", "America/New_York")
y <- add_years(y, 0:5)
date_leap_year(y)

Description

date_month_factor() extracts the month values from a date or date-time and converts them to an ordered factor of month names. This can be useful in combination with ggplot2, or for modeling.

Usage

date_month_factor(x, ..., labels = "en", abbreviate = FALSE)

Arguments

Value

An ordered factor representing the months.

Examples

x <- add_months(as.Date("2019-01-01"), 0:11)

date_month_factor(x)
date_month_factor(x, abbreviate = TRUE)
date_month_factor(x, labels = "fr")

Description

date_parse() parses strings into a Date.

The default format used is "%Y-%m-%d". This matches the default result from calling print() or format() on a Date.

Usage

date_parse(x, ..., format = NULL, locale = clock_locale())

Arguments

Details

date_parse() ignores both the ⁠%z⁠ and ⁠%Z⁠ commands, as clock treats Date as a naive type, with a yet-to-be-specified time zone.

Parsing strings with sub-daily components, such as hours, minutes, or seconds, should generally be done with date_time_parse(). If you only need the date components from a string with sub-daily components, choose one of the following:

• If the date components are at the front of the string, and you don't want the time components to affect the date in any way, you can use date_parse() to parse only the date components. For example, date_parse("2019-01-05 00:01:02", format = "%Y-%m-%d") will parse through 05 and then stop.

• If you want the time components to influence the date, then parse the full string with date_time_parse(), round to day precision with a rounding function like date_round(), and cast to date with as_date().

Attempting to directly parse all components of a sub-daily string into a Date is ambiguous and undefined, and is unlikely to work as you might expect. For example, date_parse("2019-01-05 00:01:02", format = "%Y-%m-%d %H:%M:%S") is not officially supported, even if it works in some cases.

Value

A Date.

Examples

date_parse("2020-01-01")

date_parse(
  "January 5, 2020",
  format = "%B %d, %Y"
)

# With a different locale
date_parse(
  "janvier 5, 2020",
  format = "%B %d, %Y",
  locale = clock_locale("fr")
)

# A neat feature of `date_parse()` is the ability to parse
# the ISO year-week-day format
date_parse("2020-W01-2", format = "%G-W%V-%u")

# ---------------------------------------------------------------------------
# Sub-daily components

# If you have a string with sub-daily components, but only require the date,
# first parse them as date-times to fully parse the sub-daily components,
# then round using whatever convention is required for your use case before
# converting to date.
x <- c("2019-01-01 11", "2019-01-01 12")

x <- date_time_parse(x, zone = "UTC", format = "%Y-%m-%d %H")
x

date_floor(x, "day")
date_round(x, "day")

as_date(date_round(x, "day"))

Description

date_seq() generates a date (Date) or date-time (POSIXct/POSIXlt) sequence.

There are separate help pages for generating sequences for dates and date-times:

• dates (Date)

• date-times (POSIXct/POSIXlt)

Usage

date_seq(from, ..., to = NULL, by = NULL, total_size = NULL)

Arguments

Value

A date or date-time vector.

Examples

# See method specific documentation for more examples

x <- as.Date("2019-01-01")
date_seq(x, by = duration_months(2), total_size = 20)

Description

date_spanning_seq() generates a regular sequence along the span of x, i.e. along ⁠[min(x), max(x)]⁠. For dates, this generates a day precision sequence, and for date-times it generates a second precision sequence.

Usage

date_spanning_seq(x)

Arguments

Details

Missing and infinite values are automatically removed before the sequence is generated.

For date-times, sys-time based sequences are generated, consistent with date_seq() when using a second precision by value.

If you need more precise sequence generation, call range() and date_seq() directly.

Value

A sequence along ⁠[min(x), max(x)]⁠.

Examples

x <- date_build(2020, c(1, 2, 1), c(10, 5, 12))
date_spanning_seq(x)

# Missing and infinite dates are removed before the sequence is generated
x <- c(x, NA, Inf, -Inf)
x

date_spanning_seq(x)

# For date-times, sequences are generated at second precision
x <- date_time_build(
  2020, 1, 2, 3, c(5, 4, 5), c(10, 48, 12),
  zone = "America/New_York"
)
x

date_spanning_seq(x)

Description

date_time_build() builds a POSIXct from it's individual components.

To build a POSIXct, it is required that you specify the zone.

Usage

date_time_build(
  year,
  month = 1L,
  day = 1L,
  hour = 0L,
  minute = 0L,
  second = 0L,
  ...,
  zone,
  invalid = NULL,
  nonexistent = NULL,
  ambiguous = NULL
)

Arguments

Details

Components are recycled against each other using tidyverse recycling rules.

Value

A POSIXct.

Examples

# The zone argument is required!
# clock always requires you to be explicit about your choice of `zone`.
try(date_time_build(2020))

date_time_build(2020, zone = "America/New_York")

# Nonexistent time due to daylight saving time gap from 01:59:59 -> 03:00:00
try(date_time_build(1970, 4, 26, 1:12, 30, zone = "America/New_York"))

# Resolve with a nonexistent time resolution strategy
date_time_build(
  1970, 4, 26, 1:12, 30,
  zone = "America/New_York",
  nonexistent = "roll-forward"
)

Description

date_time_info() retrieves a set of low-level information generally not required for most date-time manipulations. It returns a data frame with the same columns as sys_time_info(), but the begin and end columns are date-times with the same time zone as x, and the offset column is an integer rather than a second based duration column since this is part of the high-level API.

Usage

date_time_info(x)

Arguments

Value

A data frame of low level information.

Examples

x <- date_time_build(
  2021, 03, 14, c(01, 03), c(59, 00), c(59, 00),
  zone = "America/New_York"
)

# x[1] is in EST, x[2] is in EDT
x

info <- date_time_info(x)
info

# `end` can be used to iterate through daylight saving time transitions
date_time_info(info$end)

Description

date_weekday_factor() converts a date or date-time to an ordered factor with levels representing the weekday. This can be useful in combination with ggplot2, or for modeling.

Usage

date_weekday_factor(
  x,
  ...,
  labels = "en",
  abbreviate = TRUE,
  encoding = "western"
)

Arguments

Value

An ordered factor representing the weekdays.

Examples

x <- as.Date("2019-01-01") + 0:6

# Default to Sunday -> Saturday
date_weekday_factor(x)

# ISO encoding is Monday -> Sunday
date_weekday_factor(x, encoding = "iso")

# With full names
date_weekday_factor(x, abbreviate = FALSE)

# Or a different language
date_weekday_factor(x, labels = "fr")

Description

• date_start() computes the date at the start of a particular precision, such as the "start of the year".

• date_end() computes the date at the end of a particular precision, such as the "end of the month".

There are separate help pages for computing boundaries for dates and date-times:

• dates (Date)

• date-times (POSIXct/POSIXlt)

Usage

date_start(x, precision, ...)

date_end(x, precision, ...)

Arguments

Value

x but with some components altered to be at the boundary value.

Examples

# See type specific documentation for more examples

x <- date_build(2019, 2:4)

date_end(x, "month")

x <- date_time_build(2019, 2:4, 3:5, 4, 5, zone = "America/New_York")

# Note that the hour, minute, and second components are also adjusted
date_end(x, "month")

Description

• date_floor() rounds a date or date-time down to a multiple of the specified precision.

• date_ceiling() rounds a date or date-time up to a multiple of the specified precision.

• date_round() rounds up or down depending on what is closer, rounding up on ties.

There are separate help pages for rounding dates and date-times:

• dates (Date)

• date-times (POSIXct/POSIXlt)

These functions round the underlying duration itself, relative to an origin. For example, rounding to 15 hours will construct groups of 15 hours, starting from origin, which defaults to a naive time of 1970-01-01 00:00:00.

If you want to group by components, such as "day of the month", see date_group().

Usage

date_floor(x, precision, ..., n = 1L, origin = NULL)

date_ceiling(x, precision, ..., n = 1L, origin = NULL)

date_round(x, precision, ..., n = 1L, origin = NULL)

Arguments

Value

x rounded to the specified precision.

Examples

# See the type specific documentation for more examples

x <- as.Date("2019-03-31") + 0:5
x

# Flooring by 2 days, note that this is not tied to the current month,
# and instead counts from the specified `origin`.
date_floor(x, "day", n = 2)

Description

date_shift() shifts x to the target weekday. You can shift to the next or previous weekday. If x is currently on the target weekday, you can choose to leave it alone or advance it to the next instance of the target.

There are separate help pages for shifting dates and date-times:

• dates (Date)

• date-times (POSIXct/POSIXlt)

Usage

date_shift(x, target, ..., which = "next", boundary = "keep")

Arguments

Value

x shifted to the target weekday.

Examples

# See the type specific documentation for more examples

x <- as.Date("2019-01-01") + 0:1

# A Tuesday and Wednesday
as_weekday(x)

monday <- weekday(clock_weekdays$monday)

# Shift to the next Monday
date_shift(x, monday)

Description

These are Date methods for the arithmetic generics.

Calendrical based arithmetic:

These functions convert to a year-month-day calendar, perform the arithmetic, then convert back to a Date.

• add_years()

• add_quarters()

• add_months()

Time point based arithmetic:

These functions convert to a time point, perform the arithmetic, then convert back to a Date.

• add_weeks()

• add_days()

Usage

## S3 method for class 'Date'
add_years(x, n, ..., invalid = NULL)

## S3 method for class 'Date'
add_quarters(x, n, ..., invalid = NULL)

## S3 method for class 'Date'
add_months(x, n, ..., invalid = NULL)

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

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

Arguments

Details

Adding a single quarter with add_quarters() is equivalent to adding 3 months.

x and n are recycled against each other using tidyverse recycling rules.

Only calendrical based arithmetic has the potential to generate invalid dates. Time point based arithmetic, like adding days, will always generate a valid date.

Value

x after performing the arithmetic.

Examples

x <- as.Date("2019-01-01")

add_years(x, 1:5)

y <- as.Date("2019-01-31")

# Adding 1 month to `y` generates an invalid date. Unlike year-month-day
# types, R's native Date type cannot handle invalid dates, so you must
# resolve them immediately. If you don't you get an error:
try(add_months(y, 1:2))
add_months(as_year_month_day(y), 1:2)

# Resolve invalid dates by specifying an invalid date resolution strategy
# with the `invalid` argument. Using `"previous"` here sets the date to
# the previous valid date - i.e. the end of the month.
add_months(y, 1:2, invalid = "previous")

Description

This is a Date method for the date_start() and date_end() generics.

Usage

## S3 method for class 'Date'
date_start(x, precision, ..., invalid = NULL)

## S3 method for class 'Date'
date_end(x, precision, ..., invalid = NULL)

Arguments

Value

x but with some components altered to be at the boundary value.

Examples

x <- date_build(2019:2021, 2:4, 3:5)
x

# Last day of the month
date_end(x, "month")

# Last day of the year
date_end(x, "year")

# First day of the year
date_start(x, "year")

Description

This is a Date method for the date_count_between() generic.

date_count_between() counts the number of precision units between start and end (i.e., the number of years or months). This count corresponds to the whole number of units, and will never return a fractional value.

This is suitable for, say, computing the whole number of years or months between two dates, accounting for the day of the month.

Calendrical based counting:

These precisions convert to a year-month-day calendar and count while in that type.

• "year"

• "quarter"

• "month"

Time point based counting:

These precisions convert to a time point and count while in that type.

• "week"

• "day"

For dates, whether a calendar or time point is used is not all that important, but is is fairly important for date-times.

Usage

## S3 method for class 'Date'
date_count_between(start, end, precision, ..., n = 1L)

Arguments

Details

"quarter" is equivalent to "month" precision with n set to n * 3L.

Value

An integer representing the number of precision units between start and end.

Comparison Direction

The computed count has the property that if start <= end, then ⁠start + <count> <= end⁠. Similarly, if start >= end, then ⁠start + <count> >= end⁠. In other words, the comparison direction between start and end will never change after adding the count to start. This makes this function useful for repeated count computations at increasingly fine precisions.

Examples

start <- date_parse("2000-05-05")
end <- date_parse(c("2020-05-04", "2020-05-06"))

# Age in years
date_count_between(start, end, "year")

# Number of "whole" months between these dates. i.e.
# `2000-05-05 -> 2020-04-05` is 239 months
# `2000-05-05 -> 2020-05-05` is 240 months
# Since 2020-05-04 occurs before the 5th of that month,
# it gets a count of 239
date_count_between(start, end, "month")

# Number of "whole" quarters between (same as `"month"` with `n * 3`)
date_count_between(start, end, "quarter")
date_count_between(start, end, "month", n = 3)

# Number of days between
date_count_between(start, end, "day")

# Number of full 3 day periods between these two dates
date_count_between(start, end, "day", n = 3)

# Essentially the truncated value of this
date_count_between(start, end, "day") / 3

# ---------------------------------------------------------------------------

# Breakdown into full years, months, and days between
x <- start

years <- date_count_between(x, end, "year")
x <- add_years(x, years)

months <- date_count_between(x, end, "month")
x <- add_months(x, months)

days <- date_count_between(x, end, "day")
x <- add_days(x, days)

data.frame(
  start = start,
  end = end,
  years = years,
  months = months,
  days = days
)

# Note that when breaking down a date like that, you may need to
# set `invalid` during intermediate calculations
start <- date_build(2019, c(3, 3, 4), c(30, 31, 1))
end <- date_build(2019, 5, 05)

# These are 1 month apart (plus a few days)
months <- date_count_between(start, end, "month")

# But adding that 1 month to `start` results in an invalid date
try(add_months(start, months))

# You can choose various ways to resolve this
start_previous <- add_months(start, months, invalid = "previous")
start_next <- add_months(start, months, invalid = "next")

days_previous <- date_count_between(start_previous, end, "day")
days_next <- date_count_between(start_next, end, "day")

# Resulting in slightly different day values.
# No result is "perfect". Choosing "previous" or "next" both result
# in multiple `start` dates having the same month/day breakdown values.
data.frame(
  start = start,
  end = end,
  months = months,
  days_previous = days_previous,
  days_next = days_next
)

Description

This is a Date method for the date_format() generic.

date_format() formats a date (Date) using a format string.

If format is NULL, a default format of "%Y-%m-%d" is used.

Usage

## S3 method for class 'Date'
date_format(x, ..., format = NULL, locale = clock_locale())

Arguments

Details

Because a Date is considered to be a naive type in clock, meaning that it currently has no implied time zone, using the ⁠%z⁠ or ⁠%Z⁠ format commands is not allowed and will result in NA.

Value

A character vector of the formatted input.

Examples

x <- as.Date("2019-01-01")

# Default
date_format(x)

date_format(x, format = "year: %Y, month: %m, day: %d")

# With different locales
date_format(x, format = "%A, %B %d, %Y")
date_format(x, format = "%A, %B %d, %Y", locale = clock_locale("fr"))

Description

These are Date methods for the getter generics.

• get_year() returns the Gregorian year.

• get_month() returns the month of the year.

• get_day() returns the day of the month.

For more advanced component extraction, convert to the calendar type that you are interested in.

Usage

## S3 method for class 'Date'
get_year(x)

## S3 method for class 'Date'
get_month(x)

## S3 method for class 'Date'
get_day(x)

Arguments

Value

The component.

Examples

x <- as.Date("2019-01-01") + 0:5
get_day(x)

Description

This is a Date method for the date_group() generic.

date_group() groups by a single component of a Date, such as month of the year, or day of the month.

If you need to group by more complex components, like ISO weeks, or quarters, convert to a calendar type that contains the component you are interested in grouping by.

Usage

## S3 method for class 'Date'
date_group(x, precision, ..., n = 1L, invalid = NULL)

Arguments

Value

x, grouped at precision.

Examples

x <- as.Date("2019-01-01") + -3:5
x

# Group by 2 days of the current month.
# Note that this resets at the beginning of the month, creating day groups
# of [29, 30] [31] [01, 02] [03, 04].
date_group(x, "day", n = 2)

# Group by month
date_group(x, "month")

Description

These are Date methods for the rounding generics.

• date_floor() rounds a date down to a multiple of the specified precision.

• date_ceiling() rounds a date up to a multiple of the specified precision.

• date_round() rounds up or down depending on what is closer, rounding up on ties.

The only supported rounding precisions for Dates are "day" and "week". You can group by irregular periods such as "month" or "year" by using date_group().

Usage

## S3 method for class 'Date'
date_floor(x, precision, ..., n = 1L, origin = NULL)

## S3 method for class 'Date'
date_ceiling(x, precision, ..., n = 1L, origin = NULL)

## S3 method for class 'Date'
date_round(x, precision, ..., n = 1L, origin = NULL)

Arguments

Details

When rounding by "week", remember that the origin determines the "week start". By default, 1970-01-01 is the implicit origin, which is a Thursday. If you would like to round by weeks with a different week start, just supply an origin on the weekday you are interested in.

Value

x rounded to the specified precision.

Examples

x <- as.Date("2019-03-31") + 0:5
x

# Flooring by 2 days, note that this is not tied to the current month,
# and instead counts from the specified `origin`, so groups can cross
# the month boundary
date_floor(x, "day", n = 2)

# Compare to `date_group()`, which groups by the day of the month
date_group(x, "day", n = 2)

y <- as.Date("2019-01-01") + 0:20
y

# Flooring by week uses an implicit `origin` of 1970-01-01, which
# is a Thursday
date_floor(y, "week")
as_weekday(date_floor(y, "week"))

# If you want to round by weeks with a different week start, supply an
# `origin` that falls on the weekday you care about. This uses a Monday.
origin <- as.Date("1970-01-05")
as_weekday(origin)

date_floor(y, "week", origin = origin)
as_weekday(date_floor(y, "week", origin = origin))

Description

This is a Date method for the date_seq() generic.

date_seq() generates a date (Date) sequence.

When calling date_seq(), exactly two of the following must be specified:

• to

• by

• total_size

Usage

## S3 method for class 'Date'
date_seq(from, ..., to = NULL, by = NULL, total_size = NULL, invalid = NULL)

Arguments

Value

A date vector.

Examples

from <- date_build(2019, 1)
to <- date_build(2019, 4)

# Defaults to daily sequence
date_seq(from, to = to, by = 7)

# Use durations to change to monthly or yearly sequences
date_seq(from, to = to, by = duration_months(1))
date_seq(from, by = duration_years(-2), total_size = 3)

# Note that components of `to` more precise than the precision of `by`
# must match `from` exactly. For example, this is not well defined:
from <- date_build(2019, 5, 2)
to <- date_build(2025, 7, 5)
try(date_seq(from, to = to, by = duration_years(1)))

# The month and day components of `to` must match `from`
to <- date_build(2025, 5, 2)
date_seq(from, to = to, by = duration_years(1))

# ---------------------------------------------------------------------------

# Invalid dates must be resolved with the `invalid` argument
from <- date_build(2019, 1, 31)
to <- date_build(2019, 12, 31)

try(date_seq(from, to = to, by = duration_months(1)))
date_seq(from, to = to, by = duration_months(1), invalid = "previous")

# Compare this to the base R result, which is often a source of confusion
seq(from, to = to, by = "1 month")

# This is equivalent to the overflow invalid resolution strategy
date_seq(from, to = to, by = duration_months(1), invalid = "overflow")

# ---------------------------------------------------------------------------

# Usage of `to` and `total_size` must generate a non-fractional sequence
# between `from` and `to`
from <- date_build(2019, 1, 1)
to <- date_build(2019, 1, 4)

# These are fine
date_seq(from, to = to, total_size = 2)
date_seq(from, to = to, total_size = 4)

# But this is not!
try(date_seq(from, to = to, total_size = 3))

Description

These are Date methods for the setter generics.

• set_year() sets the year.

• set_month() sets the month of the year. Valid values are in the range of ⁠[1, 12]⁠.

• set_day() sets the day of the month. Valid values are in the range of ⁠[1, 31]⁠.

Usage

## S3 method for class 'Date'
set_year(x, value, ..., invalid = NULL)

## S3 method for class 'Date'
set_month(x, value, ..., invalid = NULL)

## S3 method for class 'Date'
set_day(x, value, ..., invalid = NULL)

Arguments

Value

x with the component set.

Examples

x <- as.Date("2019-02-01")

# Set the day
set_day(x, 12:14)

# Set to the "last" day of the month
set_day(x, "last")

# You cannot set a Date to an invalid day like you can with
# a year-month-day. Instead, the default strategy is to error.
try(set_day(x, 31))
set_day(as_year_month_day(x), 31)

# You can resolve these issues while setting the day by specifying
# an invalid date resolution strategy with `invalid`
set_day(x, 31, invalid = "previous")

Description

date_shift() shifts x to the target weekday. You can shift to the next or previous weekday. If x is currently on the target weekday, you can choose to leave it alone or advance it to the next instance of the target.

Weekday shifting is one of the easiest ways to floor by week while controlling what is considered the first day of the week. You can also accomplish this with the origin argument of date_floor(), but this is slightly easier.

Usage

## S3 method for class 'Date'
date_shift(x, target, ..., which = "next", boundary = "keep")

Arguments