clock: Date-Time Types and Tools

Description

Provides a comprehensive library for date-time manipulations using a new family of orthogonal date-time classes (durations, time points, zoned-times, and calendars) that partition responsibilities so that the complexities of time zones are only considered when they are really needed. Capabilities include: date-time parsing, formatting, arithmetic, extraction and updating of components, and rounding.

Author(s)

Maintainer: Davis Vaughan davis@posit.co

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://clock.r-lib.org

• https://github.com/r-lib/clock

• Report bugs at https://github.com/r-lib/clock/issues

Convert to a date

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))

Convert to a date-time

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")

Convert to a duration

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)

Convert to iso-year-week-day

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))

Convert to a naive-time

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)

Convert to a sys-time

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)

Convert to a weekday

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.

Convert to year-day

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))

Convert to year-month-day

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))

Convert to year-month-weekday

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))

Convert to year-quarter-day

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)

Convert to year-week-day

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))

Convert to a zoned-time

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")

Convert to a zoned-time from a date

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")

Convert to a zoned-time from a naive-time

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"))

Convert to a zoned-time from a date-time

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)

Convert to a zoned-time from a sys-time

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

Group calendar components

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)

Is the calendar year a leap year?

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))

Convert a calendar to an ordered factor of month names

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")

Narrow a calendar to a less precise precision

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")

Precision: calendar

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))

Spanning sequence: calendars

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))

Widen a calendar to a more precise precision

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")

Boundaries: calendars

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")

Counting: calendars

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")

Create or retrieve date related labels

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")

Create a clock locale

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")

Clock arithmetic

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)

Integer codes

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)

Calendar getters

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)

Invalid calendar dates

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")

Calendar setters

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")

Building: date

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")

Counting: date and date-time

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")

Formatting: date and date-time

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")

Group date and date-time components

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)

Is the year a leap year?

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)

Convert a date or date-time to an ordered factor of month names

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")

Parsing: date

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"))

Sequences: date and date-time

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)

Spanning sequence: date and date-time

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)

Building: date-time

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"
)

Info: date-time

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)

Convert a date or date-time to a weekday factor

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")

Boundaries: date and date-time

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")

Date and date-time rounding

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)

Shifting: date and date-time

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)

Arithmetic: date

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")

Boundaries: date

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")

Counting: date

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
)

Formatting: date

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"))

Getters: date

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)

Group date components

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")

Rounding: date

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))

Sequences: date

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))

Setters: date

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")

Shifting: date

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

Value

x shifted to the target weekday.

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)

# Shift to the previous Monday
# This is an easy way to "floor by week" with a target weekday in mind
date_shift(x, monday, which = "previous")

# What about Tuesday?
tuesday <- weekday(clock_weekdays$tuesday)

# Notice that the day that was currently on a Tuesday was not shifted
date_shift(x, tuesday)

# You can force it to `"advance"`
date_shift(x, tuesday, boundary = "advance")

Parsing: date-time

Description

There are four parsers for parsing strings into POSIXct date-times, date_time_parse(), date_time_parse_complete(), date_time_parse_abbrev(), and date_time_parse_RFC_3339().

date_time_parse()

date_time_parse() is useful for strings like "2019-01-01 00:00:00", where the UTC offset and full time zone name are not present in the string. The string is first parsed as a naive-time without any time zone assumptions, and is then converted to a POSIXct with the supplied zone.

Because converting from naive-time to POSIXct may result in nonexistent or ambiguous times due to daylight saving time, these must be resolved explicitly with the nonexistent and ambiguous arguments.

date_time_parse() completely ignores the ⁠%z⁠ and ⁠%Z⁠ commands. The only time zone specific information that is used is the zone.

The default format used is "%Y-%m-%d %H:%M:%S". This matches the default result from calling format() on a POSIXct date-time.

date_time_parse_complete()

date_time_parse_complete() is a parser for complete date-time strings, like "2019-01-01T00:00:00-05:00[America/New_York]". A complete date-time string has both the time zone offset and full time zone name in the string, which is the only way for the string itself to contain all of the information required to unambiguously construct a zoned-time. Because of this, date_time_parse_complete() requires both the ⁠%z⁠ and ⁠%Z⁠ commands to be supplied in the format string.

The default format used is "%Y-%m-%dT%H:%M:%S%Ez[%Z]". This matches the default result from calling date_format() on a POSIXct date-time. Additionally, this format matches the de-facto standard extension to RFC 3339 for creating completely unambiguous date-times.

date_time_parse_abbrev()

date_time_parse_abbrev() is a parser for date-time strings containing only a time zone abbreviation, like "2019-01-01 00:00:00 EST". The time zone abbreviation is not enough to identify the full time zone name that the date-time belongs to, so the full time zone name must be supplied as the zone argument. However, the time zone abbreviation can help with resolving ambiguity around daylight saving time fallbacks.

For date_time_parse_abbrev(), ⁠%Z⁠ must be supplied and is interpreted as the time zone abbreviation rather than the full time zone name.

If used, the ⁠%z⁠ command must parse correctly, but its value will be completely ignored.

The default format used is "%Y-%m-%d %H:%M:%S %Z". This matches the default result from calling print() or format(usetz = TRUE) on a POSIXct date-time.

date_time_parse_RFC_3339()

date_time_parse_RFC_3339() is a parser for date-time strings in the extremely common date-time format outlined by RFC 3339. This document outlines a profile of the ISO 8601 format that is even more restrictive, but corresponds to the most common formats that are likely to be used in internet protocols (i.e. through APIs).

In particular, this function is intended to parse the following three formats:

2019-01-01T00:00:00Z
2019-01-01T00:00:00+0430
2019-01-01T00:00:00+04:30

This function defaults to parsing the first of these formats by using a format string of "%Y-%m-%dT%H:%M:%SZ".

If your date-time strings use offsets from UTC rather than "Z", then set offset to one of the following:

• "%z" if the offset is of the form "+0430".

• "%Ez" if the offset is of the form "+04:30".

The RFC 3339 standard allows for replacing the "T" with a "t" or a space (" "). Set separator to adjust this as needed.

The date-times returned by this function will always be in the UTC time zone.

Usage

date_time_parse(
  x,
  zone,
  ...,
  format = NULL,
  locale = clock_locale(),
  nonexistent = NULL,
  ambiguous = NULL
)

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

date_time_parse_abbrev(x, zone, ..., format = NULL, locale = clock_locale())

date_time_parse_RFC_3339(x, ..., separator = "T", offset = "Z")

Arguments

Details

If date_time_parse_complete() is given input that is length zero, all NAs, or completely fails to parse, then no time zone will be able to be determined. In that case, the result will use "UTC".

If you have strings with sub-second components, then these date-time parsers are not appropriate for you. Remember that clock treats POSIXct as a second precision type, so parsing a string with fractional seconds directly into a POSIXct is ambiguous and undefined. Instead, fully parse the string, including its fractional seconds, into a clock type that can handle it, such as a naive-time with naive_time_parse(), then round to seconds with whatever rounding convention is appropriate for your use case, such as time_point_floor(), and finally convert that to POSIXct with as_date_time(). This gives you complete control over how the fractional seconds are handled when converting to POSIXct.

Value

A POSIXct.

Examples

# Parse with a known `zone`, even though that information isn't in the string
date_time_parse("2020-01-01 05:06:07", "America/New_York")

# Same time as above, except this is a completely unambiguous parse that
# doesn't require a `zone` argument, because the zone name and offset are
# both present in the string
date_time_parse_complete("2020-01-01T05:06:07-05:00[America/New_York]")

# Only day components
date_time_parse("2020-01-01", "America/New_York", format = "%Y-%m-%d")

# `date_time_parse()` may have issues with ambiguous times due to daylight
# saving time fallbacks. For example, there were two 1'oclock hours here:
x <- date_time_parse("1970-10-25 00:59:59", "America/New_York")

# First (earliest) 1'oclock hour
add_seconds(x, 1)
# Second (latest) 1'oclock hour
add_seconds(x, 3601)

# If you try to parse this ambiguous time directly, you'll get an error:
ambiguous_time <- "1970-10-25 01:00:00"
try(date_time_parse(ambiguous_time, "America/New_York"))

# Resolve it by specifying whether you'd like to use the
# `earliest` or `latest` of the two possible times
date_time_parse(ambiguous_time, "America/New_York", ambiguous = "earliest")
date_time_parse(ambiguous_time, "America/New_York", ambiguous = "latest")

# `date_time_parse_complete()` doesn't have these issues, as it requires
# that the offset and zone name are both in the string, which resolves
# the ambiguity
complete_times <- c(
  "1970-10-25T01:00:00-04:00[America/New_York]",
  "1970-10-25T01:00:00-05:00[America/New_York]"
)
date_time_parse_complete(complete_times)

# `date_time_parse_abbrev()` also doesn't have these issues, since it
# uses the time zone abbreviation name to resolve the ambiguity
abbrev_times <- c(
  "1970-10-25 01:00:00 EDT",
  "1970-10-25 01:00:00 EST"
)
date_time_parse_abbrev(abbrev_times, "America/New_York")

# ---------------------------------------------------------------------------
# RFC 3339

# Typical UTC format
x <- "2019-01-01T00:01:02Z"
date_time_parse_RFC_3339(x)

# With a UTC offset containing a `:`
x <- "2019-01-01T00:01:02+02:30"
date_time_parse_RFC_3339(x, offset = "%Ez")

# With a space between the date and time and no `:` in the offset
x <- "2019-01-01 00:01:02+0230"
date_time_parse_RFC_3339(x, separator = " ", offset = "%z")

# ---------------------------------------------------------------------------
# Sub-second components

# If you have a string with sub-second components, but only require up to
# seconds, first parse them into a clock type that can handle sub-seconds to
# fully capture that information, then round using whatever convention is
# required for your use case before converting to a date-time.
x <- c("2019-01-01T00:00:01.1", "2019-01-01T00:00:01.78")

x <- naive_time_parse(x, precision = "millisecond")
x

time_point_floor(x, "second")
time_point_round(x, "second")

as_date_time(time_point_round(x, "second"), "America/New_York")

Get or set the time zone

Description

• date_time_zone() gets the time zone.

• date_time_set_zone() sets the time zone. This retains the underlying duration, but changes the printed time depending on the zone that is chosen.

Usage

date_time_zone(x)

date_time_set_zone(x, zone)

Arguments

Details

This function is only valid for date-times, as clock treats R's Date class as a naive type, which always has a yet-to-be-specified time zone.

Value

• date_time_zone() returns a string containing the time zone.

• date_time_set_zone() returns x with an altered printed time. The underlying duration is not changed.

Examples

library(magrittr)

# Cannot set or get the zone of Date.
# clock assumes that Dates are naive types, like naive-time.
x <- date_parse("2019-01-01")
try(date_time_zone(x))
try(date_time_set_zone(x, "America/New_York"))

x <- date_time_parse("2019-01-02 01:30:00", "America/New_York")
x

date_time_zone(x)

# If it is 1:30am in New York, what time is it in Los Angeles?
# Same underlying duration, new printed time
date_time_set_zone(x, "America/Los_Angeles")

# If you want to retain the printed time, but change the underlying duration,
# convert to a naive-time to drop the time zone, then convert back to a
# date-time. Be aware that this requires that you handle daylight saving time
# irregularities with the `nonexistent` and `ambiguous` arguments to
# `as_date_time()`!
x %>%
  as_naive_time() %>%
  as_date_time("America/Los_Angeles")

y <- date_time_parse("2021-03-28 03:30:00", "America/New_York")
y

y_nt <- as_naive_time(y)
y_nt

# Helsinki had a daylight saving time gap where they jumped from
# 02:59:59 -> 04:00:00
try(as_date_time(y_nt, "Europe/Helsinki"))

as_date_time(y_nt, "Europe/Helsinki", nonexistent = "roll-forward")
as_date_time(y_nt, "Europe/Helsinki", nonexistent = "roll-backward")

Current date and date-time

Description

• date_today() returns the current date in the specified zone as a Date.

• date_now() returns the current date-time in the specified zone as a POSIXct.

Usage

date_today(zone)

date_now(zone)

Arguments

Details

clock assumes that Date is a naive type, like naive-time. This means that date_today() first looks up the current date-time in the specified zone, then converts that to a Date, retaining the printed time while dropping any information about that time zone.

Value

• date_today() a single Date.

• date_now() a single POSIXct.

Examples

# Current date in the local time zone
date_today("")

# Current date in a specified time zone
date_today("Europe/London")

# Current date-time in that same time zone
date_now("Europe/London")

Get or set the time zone

Description

• date_zone() is deprecated in favor of date_time_zone().

• date_set_zone() is deprecated in favor of date_time_set_zone().

Usage

date_zone(x)

date_set_zone(x, zone)

Arguments

Cast a duration between precisions

Description

Casting is one way to change a duration's precision.

Casting to a less precise precision will completely drop information that is more precise than the precision that you are casting to. It does so in a way that makes it round towards zero.

Casting to a more precise precision is done through a multiplication by a conversion factor between the current precision and the new precision.

Usage

duration_cast(x, precision)

Arguments

Details

When you want to change to a less precise precision, you often want duration_floor() instead of duration_cast(), as that rounds towards negative infinity, which is generally the desired behavior when working with time points (especially ones pre-1970, which are stored as negative durations).

Value

x cast to the new precision.

Examples

x <- duration_seconds(c(86401, -86401))

# Casting rounds towards 0
cast <- duration_cast(x, "day")
cast

# Flooring rounds towards negative infinity
floor <- duration_floor(x, "day")
floor

# Flooring is generally more useful when working with time points,
# note that the cast ends up rounding the pre-1970 date up to the next
# day, while the post-1970 date is rounded down.
as_sys_time(x)
as_sys_time(cast)
as_sys_time(floor)

# Casting to a more precise precision
duration_cast(x, "millisecond")

Precision: duration

Description

duration_precision() extracts the precision from a duration object. It returns the precision as a single string.

Usage

duration_precision(x)

Arguments

Value

A single string holding the precision of the duration.

Examples

duration_precision(duration_seconds(1))
duration_precision(duration_nanoseconds(2))
duration_precision(duration_quarters(1:5))

Spanning sequence: duration

Description

duration_spanning_seq() generates a regular sequence along the span of x, i.e. along ⁠[min(x), max(x)]⁠.

Usage

duration_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 <- duration_days(c(1, 5, 2))
duration_spanning_seq(x)

# Missing values are removed before the sequence is created
x <- vctrs::vec_c(NA, x, NA)
duration_spanning_seq(x)

Arithmetic: duration

Description

These are duration methods for the arithmetic generics.

• add_years()

• add_quarters()

• add_months()

• add_weeks()

• add_days()

• add_hours()

• add_minutes()

• add_seconds()

• add_milliseconds()

• add_microseconds()

• add_nanoseconds()

When adding to a duration using one of these functions, a second duration is created based on the function name and n. The two durations are then added together, and the precision of the result is determined as the more precise precision of the two durations.

Usage

## S3 method for class 'clock_duration'
add_years(x, n, ...)

## S3 method for class 'clock_duration'
add_quarters(x, n, ...)

## S3 method for class 'clock_duration'
add_months(x, n, ...)

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

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

## S3 method for class 'clock_duration'
add_hours(x, n, ...)

## S3 method for class 'clock_duration'
add_minutes(x, n, ...)

## S3 method for class 'clock_duration'
add_seconds(x, n, ...)

## S3 method for class 'clock_duration'
add_milliseconds(x, n, ...)

## S3 method for class 'clock_duration'
add_microseconds(x, n, ...)

## S3 method for class 'clock_duration'
add_nanoseconds(x, n, ...)

Arguments

Details

You can add calendrical durations to other calendrical durations, and chronological durations to other chronological durations, but you can't add a chronological duration to a calendrical duration (such as adding days and months). For more information, see the documentation on the duration helper page.

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

Value

x after performing the arithmetic, possibly with a more precise precision.

Examples

x <- duration_seconds(5)

# Addition in the same precision
add_seconds(x, 1:10)

# Addition with days, defined as 86400 seconds
add_days(x, 1)

# Similarly, if you start with days and add seconds, you get the common
# precision of the two back, which is seconds
y <- duration_days(1)
add_seconds(y, 5)

# But you can't add a chronological duration (days) and
# a calendrical duration (months)
try(add_months(y, 1))

# You can add years to a duration of months, which adds
# an additional 12 months / year
z <- duration_months(5)
add_years(z, 1)

Construct a duration

Description

These helpers construct durations of the specified precision. Durations represent units of time.

Durations are separated into two categories:

Calendrical

• year

• quarter

• month

Chronological

• week

• day

• hour

• minute

• second

• millisecond

• microsecond

• nanosecond

Calendrical durations are generally used when manipulating calendar types, like year-month-day. Chronological durations are generally used when working with time points, like sys-time or naive-time.

Usage

duration_years(n = integer())

duration_quarters(n = integer())

duration_months(n = integer())

duration_weeks(n = integer())

duration_days(n = integer())

duration_hours(n = integer())

duration_minutes(n = integer())

duration_seconds(n = integer())

duration_milliseconds(n = integer())

duration_microseconds(n = integer())

duration_nanoseconds(n = integer())

Arguments

Value

A duration of the specified precision.

Internal Representation

Durations are internally represented as an integer number of "ticks" along with a ratio describing how it converts to a number of seconds. The following duration ratios are used in clock:

• ⁠1 year == 31556952 seconds⁠

• ⁠1 quarter == 7889238 seconds⁠

• ⁠1 month == 2629746 seconds⁠

• ⁠1 week == 604800 seconds⁠

• ⁠1 day == 86400 seconds⁠

• ⁠1 hour == 3600 seconds⁠

• ⁠1 minute == 60 seconds⁠

• ⁠1 second == 1 second⁠

• ⁠1 millisecond == 1 / 1000 seconds⁠

• ⁠1 microsecond == 1 / 1000000 seconds⁠

• ⁠1 nanosecond == 1 / 1000000000 seconds⁠

A duration of 1 year is defined to correspond to the average length of a proleptic Gregorian year, i.e. 365.2425 days.

A duration of 1 month is defined as exactly 1/12 of a year.

A duration of 1 quarter is defined as exactly 1/4 of a year.

A duration of 1 week is defined as exactly 7 days.

These conversions come into play when doing operations like adding or flooring durations. Generally, you add two calendrical durations together to get a new calendrical duration, rather than adding a calendrical and a chronological duration together. The one exception is duration_cast(), which can cast durations to any other precision, with a potential loss of information.

Examples

duration_years(1:5)
duration_nanoseconds(1:5)

Duration rounding

Description

• duration_floor() rounds a duration down to a multiple of the specified precision.

• duration_ceiling() rounds a duration up to a multiple of the specified precision.

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

Usage

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

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

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

Arguments

Details

You can floor calendrical durations to other calendrical durations, and chronological durations to other chronological durations, but you can't floor a chronological duration to a calendrical duration (such as flooring from day to month). For more information, see the documentation on the duration helper page.

Value

x rounded to the precision.

Examples

x <- duration_seconds(c(86399, 86401))

duration_floor(x, "day")
duration_ceiling(x, "day")

# Can't floor from a chronological duration (seconds)
# to a calendrical duration (months)
try(duration_floor(x, "month"))

# Every 2 days, using an origin of day 0
y <- duration_seconds(c(0, 86400, 86400 * 2, 86400 * 3))
duration_floor(y, "day", n = 2)

# Shifting the origin to be day 1
origin <- duration_days(1)
duration_floor(y - origin, "day", n = 2) + origin

# Rounding will round ties up
half_day <- 86400 / 2
half_day_durations <- duration_seconds(c(half_day - 1, half_day, half_day + 1))
duration_round(half_day_durations, "day")

# With larger units
x <- duration_months(c(0, 15, 24))
duration_floor(x, "year")
duration_floor(x, "quarter")

Formatting: zoned-time

Description

This is a zoned-time method for the format() generic.

This function allows you to format a zoned-time using a flexible format string.

If format is NULL, a default format of "%Y-%m-%dT%H:%M:%S%Ez[%Z]" is used. This matches the default format that zoned_time_parse_complete() parses. Additionally, this format matches the de-facto standard extension to RFC 3339 for creating completely unambiguous date-times.

Usage

## S3 method for class 'clock_zoned_time'
format(x, ..., format = NULL, locale = clock_locale(), abbreviate_zone = FALSE)

Arguments

Value

A character vector of the formatted input.

Examples

x <- year_month_day(2019, 1, 1)
x <- as_zoned_time(as_naive_time(x), "America/New_York")

format(x)
format(x, format = "%B %d, %Y")
format(x, format = "%B %d, %Y", locale = clock_locale("fr"))

Is x a duration?

Description

This function determines if the input is a duration object.

Usage

is_duration(x)

Arguments

Value

TRUE if x inherits from "clock_duration", otherwise FALSE.

Examples

is_duration(1)
is_duration(duration_days(1))

Is x a iso-year-week-day?

Description

Check if x is a iso-year-week-day.

Usage

is_iso_year_week_day(x)

Arguments

Value

Returns TRUE if x inherits from "clock_iso_year_week_day", otherwise returns FALSE.

Examples

is_iso_year_week_day(iso_year_week_day(2019))

Is x a naive-time?

Description

This function determines if the input is a naive-time object.

Usage

is_naive_time(x)

Arguments

Value

TRUE if x inherits from "clock_naive_time", otherwise FALSE.

Examples

is_naive_time(1)
is_naive_time(as_naive_time(duration_days(1)))

Is x a sys-time?

Description

This function determines if the input is a sys-time object.

Usage

is_sys_time(x)

Arguments

Value

TRUE if x inherits from "clock_sys_time", otherwise FALSE.

Examples

is_sys_time(1)
is_sys_time(as_sys_time(duration_days(1)))

Is x a weekday?

Description

This function determines if the input is a weekday object.

Usage

is_weekday(x)

Arguments

Value

TRUE if x inherits from "clock_weekday", otherwise FALSE.

Examples

is_weekday(1)
is_weekday(weekday(1))

Is x a year-day?

Description

Check if x is a year-day.

Usage

is_year_day(x)

Arguments

Value

Returns TRUE if x inherits from "clock_year_day", otherwise returns FALSE.

Examples

is_year_day(year_day(2019))

Is x a year-month-day?

Description

Check if x is a year-month-day.

Usage

is_year_month_day(x)

Arguments

Value

Returns TRUE if x inherits from "clock_year_month_day", otherwise returns FALSE.

Examples

is_year_month_day(year_month_day(2019))

Is x a year-month-weekday?

Description

Check if x is a year-month-weekday.

Usage

is_year_month_weekday(x)

Arguments

Value

Returns TRUE if x inherits from "clock_year_month_weekday", otherwise returns FALSE.

Examples

is_year_month_weekday(year_month_weekday(2019))

Is x a year-quarter-day?

Description

Check if x is a year-quarter-day.

Usage

is_year_quarter_day(x)

Arguments

Value

Returns TRUE if x inherits from "clock_year_quarter_day", otherwise returns FALSE.

Examples

is_year_quarter_day(year_quarter_day(2019))

Is x a year-week-day?

Description

Check if x is a year-week-day.

Usage

is_year_week_day(x)

Arguments

Value

Returns TRUE if x inherits from "clock_year_week_day", otherwise returns FALSE.

Examples

is_year_week_day(year_week_day(2019))

Is x a zoned-time?

Description

This function determines if the input is a zoned-time object.

Usage

is_zoned_time(x)

Arguments

Value

TRUE if x inherits from "clock_zoned_time", otherwise FALSE.

Examples

is_zoned_time(1)
is_zoned_time(zoned_time_now("America/New_York"))

Calendar: iso-year-week-day

Description

iso_year_week_day() constructs a calendar from the ISO year, week number, and week day.

Usage

iso_year_week_day(
  year,
  week = NULL,
  day = NULL,
  hour = NULL,
  minute = NULL,
  second = NULL,
  subsecond = NULL,
  ...,
  subsecond_precision = NULL
)

Arguments

Details

Fields are recycled against each other using tidyverse recycling rules.

Fields are collected in order until the first NULL field is located. No fields after the first NULL field are used.

Value

A iso-year-week-day calendar vector.

Examples

# Year-week
x <- iso_year_week_day(2019:2025, 1)
x

# 2nd day of the first ISO week in multiple years
iso_days <- set_day(x, clock_iso_weekdays$tuesday)
iso_days

# What year-month-day is this?
as_year_month_day(iso_days)

Arithmetic: iso-year-week-day

Description

These are iso-year-week-day methods for the arithmetic generics.

• add_years()

You cannot add weeks or days to an iso-year-week-day calendar. Adding days is much more efficiently done by converting to a time point first by using as_naive_time() or as_sys_time(). Adding weeks is equally as efficient as adding 7 days. Additionally, adding weeks to an invalid iso-year-week object containing iso_year_week_day(2019, 53) would be undefined, as the 53rd ISO week of 2019 doesn't exist to begin with.

Usage

## S3 method for class 'clock_iso_year_week_day'
add_years(x, n, ...)

Arguments

Details

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

Value

x after performing the arithmetic.

Examples

x <- iso_year_week_day(2019, 1, 1)
add_years(x, 1:2)

Boundaries: iso-year-week-day

Description

This is an iso-year-week-day method for the calendar_start() and calendar_end() generics. They adjust components of a calendar to the start or end of a specified precision.

Usage

## S3 method for class 'clock_iso_year_week_day'
calendar_start(x, precision)

## S3 method for class 'clock_iso_year_week_day'
calendar_end(x, precision)

Arguments

Value

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

Examples

x <- iso_year_week_day(2019:2020, 5, 6, 10)
x

# Compute the last moment of the last iso week of the year
calendar_end(x, "year")

# Compare that to just setting the week to `"last"`,
# which doesn't affect the other components
set_week(x, "last")

Counting: iso-year-week-day

Description

This is an iso-year-week-day method for the calendar_count_between() generic. It counts the number of precision units between start and end (i.e., the number of ISO years).

Usage

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

Arguments

Value

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

Examples

# Compute the number of whole ISO years between two dates
x <- iso_year_week_day(2001, 1, 2)
y <- iso_year_week_day(2021, 1, c(1, 3))
calendar_count_between(x, y, "year")

Getters: iso-year-week-day

Description

These are iso-year-week-day methods for the getter generics.

• get_year() returns the ISO year. Note that this can differ from the Gregorian year.

• get_week() returns the ISO week of the current ISO year.

• get_day() returns a value between 1-7 indicating the weekday of the current ISO week, where 1 = Monday and 7 = Sunday, in line with the ISO standard.

• There are sub-daily getters for extracting more precise components.

Usage

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

## S3 method for class 'clock_iso_year_week_day'
get_week(x)

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

## S3 method for class 'clock_iso_year_week_day'
get_hour(x)

## S3 method for class 'clock_iso_year_week_day'
get_minute(x)

## S3 method for class 'clock_iso_year_week_day'
get_second(x)

## S3 method for class 'clock_iso_year_week_day'
get_millisecond(x)

## S3 method for class 'clock_iso_year_week_day'
get_microsecond(x)

## S3 method for class 'clock_iso_year_week_day'
get_nanosecond(x)

Arguments

Value

The component.

Examples

x <- iso_year_week_day(2019, 50:52, 1:3)
x

# Get the ISO week
get_week(x)

# Gets the weekday, 1 = Monday, 7 = Sunday
get_day(x)

# Note that the ISO year can differ from the Gregorian year
iso <- iso_year_week_day(2019, 1, 1)
ymd <- as_year_month_day(iso)

get_year(iso)
get_year(ymd)

Grouping: iso-year-week-day

Description

This is a iso-year-week-day method for the calendar_group() generic.

Grouping for a iso-year-week-day object can be done at any precision, as long as x is at least as precise as precision.

Usage

## S3 method for class 'clock_iso_year_week_day'
calendar_group(x, precision, ..., n = 1L)

Arguments

Value

x grouped at the specified precision.

Examples

x <- iso_year_week_day(2019, 1:52)

# Group by 3 ISO weeks
calendar_group(x, "week", n = 3)

y <- iso_year_week_day(2000:2020, 1, 1)

# Group by 2 ISO years
calendar_group(y, "year", n = 2)

Narrow: iso-year-week-day

Description

This is a iso-year-week-day method for the calendar_narrow() generic. It narrows a iso-year-week-day vector to the specified precision.

Usage

## S3 method for class 'clock_iso_year_week_day'
calendar_narrow(x, precision)

Arguments

Value

x narrowed to the supplied precision.

Examples

# Day precision
x <- iso_year_week_day(2019, 1, 5)
x

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

Setters: iso-year-week-day

Description

These are iso-year-week-day methods for the setter generics.

• set_year() sets the ISO year.

• set_week() sets the ISO week of the year. Valid values are in the range of ⁠[1, 53]⁠.

• set_day() sets the day of the week. Valid values are in the range of ⁠[1, 7]⁠, with 1 = Monday, and 7 = Sunday.

• There are sub-daily setters for setting more precise components.

Usage

## S3 method for class 'clock_iso_year_week_day'
set_year(x, value, ...)

## S3 method for class 'clock_iso_year_week_day'
set_week(x, value, ...)

## S3 method for class 'clock_iso_year_week_day'
set_day(x, value, ...)

## S3 method for class 'clock_iso_year_week_day'
set_hour(x, value, ...)

## S3 method for class 'clock_iso_year_week_day'
set_minute(x, value, ...)

## S3 method for class 'clock_iso_year_week_day'
set_second(x, value, ...)

## S3 method for class 'clock_iso_year_week_day'
set_millisecond(x, value, ...)

## S3 method for class 'clock_iso_year_week_day'
set_microsecond(x, value, ...)

## S3 method for class 'clock_iso_year_week_day'
set_nanosecond(x, value, ...)

Arguments

Value

x with the component set.

Examples

# Year precision vector
x <- iso_year_week_day(2019:2023)

# Promote to week precision by setting the week
# (Note that some ISO weeks have 52 weeks, and others have 53)
x <- set_week(x, "last")
x

# Set to an invalid week
invalid <- set_week(x, 53)
invalid

# Here are the invalid ones (they only have 52 weeks)
invalid[invalid_detect(invalid)]

# Resolve the invalid dates by choosing the previous/next valid moment
invalid_resolve(invalid, invalid = "previous")
invalid_resolve(invalid, invalid = "next")

Widen: iso-year-week-day

Description

This is a iso-year-week-day method for the calendar_widen() generic. It widens a iso-year-week-day vector to the specified precision.

Usage

## S3 method for class 'clock_iso_year_week_day'
calendar_widen(x, precision)

Arguments

Value

x widened to the supplied precision.

Examples

# Week precision
x <- iso_year_week_day(2019, 1)
x

# Widen to day precision
# In the ISO calendar, the first day of the week is a Monday
calendar_widen(x, "day")

# Or second precision
sec <- calendar_widen(x, "second")
sec

Info: naive-time

Description

naive_time_info() retrieves a set of low-level information generally not required for most date-time manipulations. It is used implicitly by as_zoned_time() when converting from a naive-time.

It returns a data frame with the following columns:

• type: A character vector containing one of:

  • "unique": The naive-time maps uniquely to a zoned-time that can be created with zone.

  • "nonexistent": The naive-time does not exist as a zoned-time that can be created with zone.

  • "ambiguous": The naive-time exists twice as a zoned-time that can be created with zone.

• first: A sys_time_info() data frame.

• second: A sys_time_info() data frame.

type == "unique"

• first will be filled out with sys-info representing daylight saving time information for that time point in zone.

• second will contain only NA values, as there is no ambiguity to represent information for.

type == "nonexistent"

• first will be filled out with the sys-info that ends just prior to x.

• second will be filled out with the sys-info that begins just after x.

type == "ambiguous"

• first will be filled out with the sys-info that ends just after x.

• second will be filled out with the sys-info that starts just before x.

Usage

naive_time_info(x, zone)

Arguments

Details

If the tibble package is installed, it is recommended to convert the output to a tibble with as_tibble(), as that will print the df-cols much nicer.

Value

A data frame of low level information.

Examples

library(vctrs)

x <- year_month_day(1970, 04, 26, 02, 30, 00)
x <- as_naive_time(x)

# Maps uniquely to a time in London
naive_time_info(x, "Europe/London")

# This naive-time never existed in New York!
# A DST gap jumped the time from 01:59:59 -> 03:00:00,
# skipping the 2 o'clock hour
zone <- "America/New_York"
info <- naive_time_info(x, zone)
info

# You can recreate various `nonexistent` strategies with this info
as_zoned_time(x, zone, nonexistent = "roll-forward")
as_zoned_time(info$first$end, zone)

as_zoned_time(x, zone, nonexistent = "roll-backward")
as_zoned_time(info$first$end - 1, zone)

as_zoned_time(x, zone, nonexistent = "shift-forward")
as_zoned_time(as_sys_time(x) - info$first$offset, zone)

as_zoned_time(x, zone, nonexistent = "shift-backward")
as_zoned_time(as_sys_time(x) - info$second$offset, zone)

# ---------------------------------------------------------------------------
# Normalizing to UTC

# Imagine you had the following printed times, and knowledge that they
# are to be interpreted as in the corresponding time zones
df <- data_frame(
  x = c("2020-01-05 02:30:00", "2020-06-03 12:20:05"),
  zone = c("America/Los_Angeles", "Europe/London")
)

# The times are assumed to be naive-times, i.e. if you lived in the `zone`
# at the moment the time was recorded, then you would have seen that time
# printed on the clock. Currently, these are strings. To convert them to
# a time based type, you'll have to acknowledge that R only lets you have
# 1 time zone in a vector of date-times at a time. So you'll need to
# normalize these naive-times. The easiest thing to normalize them to
# is UTC.
df$naive <- naive_time_parse(df$x)

# Get info about the naive times using a vector of zones
info <- naive_time_info(df$naive, df$zone)
info

# We'll assume that some system generated these naive-times with no
# chance of them ever being nonexistent or ambiguous. So now all we have
# to do is use the offset to convert the naive-time to a sys-time. The
# relationship used is:
# offset = naive_time - sys_time
df$sys <- as_sys_time(df$naive) - info$first$offset
df

# At this point, both times are in UTC. From here, you can convert them
# both to either America/Los_Angeles or Europe/London as required.
as_zoned_time(df$sys, "America/Los_Angeles")
as_zoned_time(df$sys, "Europe/London")

Parsing: naive-time

Description

naive_time_parse() is a parser into a naive-time.

naive_time_parse() is useful when you have date-time strings like "2020-01-01T01:04:30". If there is no attached UTC offset or time zone name, then parsing this string as a naive-time is your best option. If you know that this string should be interpreted in a specific time zone, parse as a naive-time, then use as_zoned_time().

The default options assume that x should be parsed at second precision, using a format string of "%Y-%m-%dT%H:%M:%S". This matches the default result from calling format() on a naive-time.

naive_time_parse() ignores both the ⁠%z⁠ and ⁠%Z⁠ commands.

If your date-time strings contain a full time zone name and a UTC offset, use zoned_time_parse_complete(). If they contain a time zone abbreviation, use zoned_time_parse_abbrev().

If your date-time strings contain a UTC offset, but not a full time zone name, use sys_time_parse().

Usage

naive_time_parse(
  x,
  ...,
  format = NULL,
  precision = "second",
  locale = clock_locale()
)

Arguments

Value

A naive-time.

Full Precision Parsing

It is highly recommended to parse all of the information in the date-time string into a type at least as precise as the string. For example, if your string has fractional seconds, but you only require seconds, specify a sub-second precision, then round to seconds manually using whatever convention is appropriate for your use case. Parsing such a string directly into a second precision result is ambiguous and undefined, and is unlikely to work as you might expect.

Examples

naive_time_parse("2020-01-01T05:06:07")

# Day precision
naive_time_parse("2020-01-01", precision = "day")

# Nanosecond precision, but using a day based format
naive_time_parse("2020-01-01", format = "%Y-%m-%d", precision = "nanosecond")

# Remember that the `%z` and `%Z` commands are ignored entirely!
naive_time_parse(
  "2020-01-01 -4000 America/New_York",
  format = "%Y-%m-%d %z %Z"
)

# ---------------------------------------------------------------------------
# Fractional seconds and POSIXct

# If you have a string with fractional seconds and want to convert it to
# a POSIXct, remember that clock treats POSIXct as a second precision type.
# Ideally, you'd use a clock type that can support fractional seconds, but
# if you really want to parse it into a POSIXct, the correct way to do so
# is to parse the full fractional time point with the correct `precision`,
# then round to seconds using whatever convention you require, and finally
# convert that to POSIXct.
x <- c("2020-01-01T00:00:00.123", "2020-01-01T00:00:00.555")

# First, parse string with full precision
x <- naive_time_parse(x, precision = "millisecond")
x

# Then round to second with a floor, ceiling, or round to nearest
time_point_floor(x, "second")
time_point_round(x, "second")

# Finally, convert to POSIXct
as_date_time(time_point_round(x, "second"), zone = "UTC")

Arithmetic: date-time

Description

These are POSIXct/POSIXlt methods for the arithmetic generics.

Calendrical based arithmetic:

These functions convert to a naive-time, then to a year-month-day, perform the arithmetic, then convert back to a date-time.

• add_years()

• add_quarters()

• add_months()

Naive-time based arithmetic:

These functions convert to a naive-time, perform the arithmetic, then convert back to a date-time.

• add_weeks()

• add_days()

Sys-time based arithmetic:

These functions convert to a sys-time, perform the arithmetic, then convert back to a date-time.

• add_hours()

• add_minutes()

• add_seconds()

Usage

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

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

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

## S3 method for class 'POSIXt'
add_weeks(x, n, ..., nonexistent = NULL, ambiguous = x)

## S3 method for class 'POSIXt'
add_days(x, n, ..., nonexistent = NULL, ambiguous = x)

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

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

## S3 method for class 'POSIXt'
add_seconds(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.

Calendrical based arithmetic has the potential to generate invalid dates (like the 31st of February), nonexistent times (due to daylight saving time gaps), and ambiguous times (due to daylight saving time fallbacks).

Naive-time based arithmetic will never generate an invalid date, but may generate a nonexistent or ambiguous time (i.e. you added 1 day and landed in a daylight saving time gap).

Sys-time based arithmetic operates in the UTC time zone, which means that it will never generate any invalid dates or nonexistent / ambiguous times.

The conversion from POSIXct/POSIXlt to the corresponding clock type uses a "best guess" about whether you want to do the arithmetic using a naive-time or a sys-time. For example, when adding months, you probably want to retain the printed time when converting to a year-month-day to perform the arithmetic, so the conversion goes through naive-time. However, when adding smaller units like seconds, you probably want ⁠"2020-03-08 01:59:59" + 1 second⁠ in the America/New_York time zone to return "2020-03-08 03:00:00", taking into account the fact that there was a daylight saving time gap. This requires doing the arithmetic in sys-time, so that is what clock converts to. If you disagree with this heuristic for any reason, you can take control and perform the conversions yourself. For example, you could convert the previous example to a naive-time instead of a sys-time manually with as_naive_time(), add 1 second giving "2020-03-08 02:00:00", then convert back to a POSIXct/POSIXlt, dealing with the nonexistent time that gets created by using the nonexistent argument of as.POSIXct().

Value

x after performing the arithmetic.

Relative ordering

For the most part, adding time based units to date-times will retain the relative ordering of the input. For example, if x[1] < x[2] before the ⁠add_*()⁠ call, then it is generally also true of the result. Using invalid = "previous" / "next" and nonexistent = "roll-forward" / "roll-backward" ensures that this holds when invalid and nonexistent issues are encountered.

That said, with date-times there is an edge case related to ambiguous times where the relative ordering could change. Consider these three date-times:

x <- c(
  date_time_build(2012, 4, 1, 2, 30, zone = "Australia/Melbourne", ambiguous = "earliest"),
  date_time_build(2012, 4, 1, 2, 00, zone = "Australia/Melbourne", ambiguous = "latest"),
  date_time_build(2012, 4, 1, 2, 30, zone = "Australia/Melbourne", ambiguous = "latest")
)
x
#> [1] "2012-04-01 02:30:00 AEDT" "2012-04-01 02:00:00 AEST"
#> [3] "2012-04-01 02:30:00 AEST"

In this case, there was a daylight saving time fallback on 2012-04-01 where the clocks went from ⁠02:59:59 AEDT -> 02:00:00 AEST⁠. So the times above are precisely 30 minutes apart, and they are in increasing order.

If we add sys-time based units like hours, minutes, or seconds, then the relative ordering of these date-times will be preserved. However, arithmetic that goes through naive-time, like adding days or months, won't preserve the ordering here:

add_days(x, 1)
#> [1] "2012-04-02 02:30:00 AEST" "2012-04-02 02:00:00 AEST"
#> [3] "2012-04-02 02:30:00 AEST"
add_months(x, 1)
#> [1] "2012-05-01 02:30:00 AEST" "2012-05-01 02:00:00 AEST"
#> [3] "2012-05-01 02:30:00 AEST"

Note that the 1st and 3rd values of the result are the same, and the 1st value is no longer before the 2nd value.

Adding larger units of time in naive-time generally does make more sense than adding it in sys-time, but it does come with this one edge case to be aware of when working with date-times (this does not affect dates). If this has the potential to be an issue, consider only adding sys-time based units (hours, minutes, and seconds) which can't have these issues.

Examples

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

add_years(x, 1:5)

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

# Adding 1 month to `y` generates an invalid date. Unlike year-month-day
# types, R's native date-time types 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-time to
# the previous valid moment in time - i.e. the end of the month. The
# time is set to the last moment in the day to retain the relative ordering
# within your input. If you are okay with potentially losing this, and
# want to retain your time of day, you can use `"previous-day"` to set the
# date-time to the previous valid day, while keeping the time of day.
add_months(y, 1:2, invalid = "previous")
add_months(y, 1:2, invalid = "previous-day")

Boundaries: date-time

Description

This is a POSIXct/POSIXlt method for the date_start() and date_end() generics.

Usage

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

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

Arguments

Value

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

Examples

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

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

# Notice that this is different from just setting the day to `"last"`
set_day(x, "last")

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

# First moment of the hour
date_start(x, "hour")

Counting: date-times

Description

This is a POSIXct/POSIXlt 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 and the time of day.

Internally, the date-time is converted to one of the following three clock types, and the counting is done directly on that type. The choice of type is based on the most common interpretation of each precision, but is ultimately a heuristic. See the examples for more information.

Calendrical based counting:

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

• "year"

• "quarter"

• "month"

Naive-time based counting:

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

• "week"

• "day"

Sys-time based counting:

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

• "hour"

• "minute"

• "second"

Usage

## S3 method for class 'POSIXt'
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_time_parse("2000-05-05 02:00:00", zone = "America/New_York")
end <- date_time_parse(
  c("2020-05-05 01:00:00", "2020-05-05 03:00:00"),
  zone = "America/New_York"
)

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

# Number of "whole" months between these dates. i.e.
# `2000-05-05 02:00:00 -> 2020-04-05 02:00:00` is 239 months
# `2000-05-05 02:00:00 -> 2020-05-05 02:00:00` is 240 months
# Since `2020-05-05 01:00:00` occurs before the 2nd hour,
# it gets a count of 239
date_count_between(start, end, "month")

# Number of seconds between
date_count_between(start, end, "second")

# ---------------------------------------------------------------------------
# Naive-time VS Sys-time interpretation

# The difference between whether `start` and `end` are converted to a
# naive-time vs a sys-time comes into play when dealing with daylight
# savings.

# Here are two times around a 1 hour DST gap where clocks jumped from
# 01:59:59 -> 03:00:00
x <- date_time_build(1970, 4, 26, 1, 50, 00, zone = "America/New_York")
y <- date_time_build(1970, 4, 26, 3, 00, 00, zone = "America/New_York")

# When treated like sys-times, these are considered to be 10 minutes apart,
# which is the amount of time that would have elapsed if you were watching
# a clock as it changed between these two times.
date_count_between(x, y, "minute")

# Lets add a 3rd date that is ~1 day ahead of these
z <- date_time_build(1970, 4, 27, 1, 55, 00, zone = "America/New_York")

# When treated like naive-times, `z` is considered to be at least 1 day ahead
# of `x`, because `01:55:00` is after `01:50:00`. This is probably what you
# expected.
date_count_between(x, z, "day")

# If these were interpreted like sys-times, then `z` would not be considered
# to be 1 day ahead. That would look something like this:
date_count_between(x, z, "second")
trunc(date_count_between(x, z, "second") / 86400)

# This is because there have only been 83,100 elapsed seconds since `x`,
# which isn't a full day's worth (86,400 seconds). But we'd generally
# consider `z` to be 1 day ahead of `x` (and ignore the DST gap), so that is
# how it is implemented.

# You can override this by converting directly to sys-time, then using
# `time_point_count_between()`
x_st <- as_sys_time(x)
x_st

z_st <- as_sys_time(z)
z_st

time_point_count_between(x_st, z_st, "day")

Formatting: date-time

Description

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

date_format() formats a date-time (POSIXct) using a format string.

If format is NULL, a default format of "%Y-%m-%dT%H:%M:%S%Ez[%Z]" is used. This matches the default format that date_time_parse_complete() parses. Additionally, this format matches the de-facto standard extension to RFC 3339 for creating completely unambiguous date-times.

Usage

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

Arguments

Value

A character vector of the formatted input.

Examples

x <- date_time_parse(
  c("1970-04-26 01:30:00", "1970-04-26 03:30:00"),
  zone = "America/New_York"
)

# Default
date_format(x)

# Which is parseable by `date_time_parse_complete()`
date_time_parse_complete(date_format(x))

date_format(x, format = "%B %d, %Y %H:%M:%S")

# By default, `%Z` uses the full zone name, but you can switch to the
# abbreviated name
date_format(x, format = "%z %Z")
date_format(x, format = "%z %Z", abbreviate_zone = TRUE)

Getters: date-time

Description

These are POSIXct/POSIXlt 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.

• There are sub-daily getters for extracting more precise components, up to a precision of seconds.