Title:  DateTime Types and Tools 

Description:  Provides a comprehensive library for datetime manipulations using a new family of orthogonal datetime classes (durations, time points, zonedtimes, and calendars) that partition responsibilities so that the complexities of time zones are only considered when they are really needed. Capabilities include: datetime parsing, formatting, arithmetic, extraction and updating of components, and rounding. 
Authors:  Davis Vaughan [aut, cre], Posit Software, PBC [cph, fnd] 
Maintainer:  Davis Vaughan <[email protected]> 
License:  MIT + file LICENSE 
Version:  0.7.1.9000 
Built:  20241014 05:49:40 UTC 
Source:  https://github.com/rlib/clock 
as_date()
is a generic function that converts its input to a date (Date).
There are methods for converting datetimes (POSIXct), calendars, time points, and zonedtimes to dates.
For converting to a datetime, see as_date_time()
.
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, ...)
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, ...)
x 
A vector. 
... 
These dots are for future extensions and must be empty. 
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 dropin 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()
.
A date with the same length as x
.
x < date_time_parse("20190101 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))
x < date_time_parse("20190101 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))
as_date_time()
is a generic function that converts its input to a datetime
(POSIXct).
There are methods for converting dates (Date), calendars, time points, and zonedtimes to datetimes.
For converting to a date, see as_date()
.
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, ...)
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, ...)
x 
A vector. 
... 
These dots are for future extensions and must be empty. 
zone 
The zone to convert to. 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
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 dropin replacement for as.POSIXct()
, as it only converts a
limited set of types to POSIXct. For parsing characters as datetimes, see
date_time_parse()
. For converting numerics to datetimes, see
vctrs::new_datetime()
or continue to use as.POSIXct()
.
A datetime with the same length as x
.
x < as.Date("20190101") # `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 # 20210327 23:59:59 > 20210328 01:00:00, # skipping the 0th hour entirely. x < as.Date("20210328") try(as_date_time(x, "Asia/Beirut")) # To resolve this, set a `nonexistent` time resolution strategy as_date_time(x, "Asia/Beirut", nonexistent = "rollforward") # You can also convert to datetime from other clock types as_date_time(year_month_day(2019, 2, 3, 03), "America/New_York")
x < as.Date("20190101") # `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 # 20210327 23:59:59 > 20210328 01:00:00, # skipping the 0th hour entirely. x < as.Date("20210328") try(as_date_time(x, "Asia/Beirut")) # To resolve this, set a `nonexistent` time resolution strategy as_date_time(x, "Asia/Beirut", nonexistent = "rollforward") # You can also convert to datetime from other clock types as_date_time(year_month_day(2019, 2, 3, 03), "America/New_York")
You generally convert to a duration from either a systime or a naivetime. The precision of the input is retained in the returned duration.
To round an existing duration to another precision, see duration_floor()
.
as_duration(x, ...)
as_duration(x, ...)
x 
An object to convert to a duration. 
... 
These dots are for future extensions and must be empty. 
A duration with the same precision as x
.
x < as_sys_time(year_month_day(2019, 01, 01)) # The number of days since 19700101 UTC as_duration(x) x < x + duration_seconds(1) x # The number of seconds since 19700101 00:00:00 UTC as_duration(x)
x < as_sys_time(year_month_day(2019, 01, 01)) # The number of days since 19700101 UTC as_duration(x) x < x + duration_seconds(1) x # The number of seconds since 19700101 00:00:00 UTC as_duration(x)
as_iso_year_week_day()
converts a vector to the isoyearweekday
calendar. Time points, Dates, POSIXct, and other calendars can all be
converted to isoyearweekday.
as_iso_year_week_day(x, ...)
as_iso_year_week_day(x, ...)
x 
A vector to convert to isoyearweekday. 
... 
These dots are for future extensions and must be empty. 
A isoyearweekday vector.
# From Date as_iso_year_week_day(as.Date("20190101")) # From POSIXct, which assumes that the naive time is what should be converted as_iso_year_week_day(as.POSIXct("20190101 02:30:30", "America/New_York")) # From other calendars as_iso_year_week_day(year_quarter_day(2019, quarter = 2, day = 50))
# From Date as_iso_year_week_day(as.Date("20190101")) # From POSIXct, which assumes that the naive time is what should be converted as_iso_year_week_day(as.POSIXct("20190101 02:30:30", "America/New_York")) # From other calendars as_iso_year_week_day(year_quarter_day(2019, quarter = 2, day = 50))
as_naive_time()
converts x
to a naivetime.
You can convert to a naivetime 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 naivetime from a systime or zonedtime retains the printed time, but drops the assumption that the time should be interpreted with any specific time zone.
Converting to a naivetime from a duration just wraps the duration in a naivetime 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 naivetime from R's native date and datetime types. Like converting from a zonedtime, these retain the printed time.
as_naive_time(x, ...)
as_naive_time(x, ...)
x 
An object to convert to a naivetime. 
... 
These dots are for future extensions and must be empty. 
A naivetime vector.
x < as.Date("20190101") 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)
x < as.Date("20190101") 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)
as_sys_time()
converts x
to a systime.
You can convert to a systime 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 systime from a naivetime retains the printed time, but adds an assumption that the time should be interpreted in the UTC time zone.
Converting to a systime from a zonedtime retains the underlying duration, but the printed time is the equivalent UTC time to whatever the zonedtime's zone happened to be.
Converting to a systime from a duration just wraps the duration in a systime 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 systime from R's native date and datetime types. Like converting from a zonedtime, these retain the underlying duration, but will change the printed time if the zone was not already UTC.
as_sys_time(x, ...)
as_sys_time(x, ...)
x 
An object to convert to a systime. 
... 
These dots are for future extensions and must be empty. 
A systime vector.
x < as.Date("20190101") # Dates are assumed to be naive, so the printed time is the same whether # we convert it to systime or naivetime as_sys_time(x) as_naive_time(x) y < as.POSIXct("20190101 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)
x < as.Date("20190101") # Dates are assumed to be naive, so the printed time is the same whether # we convert it to systime or naivetime as_sys_time(x) as_naive_time(x) y < as.POSIXct("20190101 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)
as_weekday()
converts to a weekday type. This is normally useful for
converting to a weekday from a systime or naivetime. You can use this
function along with the circular arithmetic that weekday implements to
easily get to the "next Monday" or "previous Sunday".
as_weekday(x, ...)
as_weekday(x, ...)
x 
An object to convert to a weekday. Usually a systime or naivetime. 
... 
These dots are for future extensions and must be empty. 
A weekday.
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.
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.
as_year_day()
converts a vector to the yearday calendar.
Time points, Dates, POSIXct, and other calendars can all be converted to
yearday.
as_year_day(x, ...)
as_year_day(x, ...)
x 
A vector to convert to yearday. 
... 
These dots are for future extensions and must be empty. 
A yearday vector.
# From Date as_year_day(as.Date("20190501")) # From POSIXct, which assumes that the naive time is what should be converted as_year_day(as.POSIXct("20190501 02:30:30", "America/New_York")) # From other calendars as_year_day(year_quarter_day(2019, quarter = 2, day = 50))
# From Date as_year_day(as.Date("20190501")) # From POSIXct, which assumes that the naive time is what should be converted as_year_day(as.POSIXct("20190501 02:30:30", "America/New_York")) # From other calendars as_year_day(year_quarter_day(2019, quarter = 2, day = 50))
as_year_month_day()
converts a vector to the yearmonthday calendar.
Time points, Dates, POSIXct, and other calendars can all be converted to
yearmonthday.
as_year_month_day(x, ...)
as_year_month_day(x, ...)
x 
A vector to convert to yearmonthday. 
... 
These dots are for future extensions and must be empty. 
A yearmonthday vector.
# From Date as_year_month_day(as.Date("20190101")) # From POSIXct, which assumes that the naive time is what should be converted as_year_month_day(as.POSIXct("20190101 02:30:30", "America/New_York")) # From other calendars as_year_month_day(year_quarter_day(2019, quarter = 2, day = 50))
# From Date as_year_month_day(as.Date("20190101")) # From POSIXct, which assumes that the naive time is what should be converted as_year_month_day(as.POSIXct("20190101 02:30:30", "America/New_York")) # From other calendars as_year_month_day(year_quarter_day(2019, quarter = 2, day = 50))
as_year_month_weekday()
converts a vector to the yearmonthweekday
calendar. Time points, Dates, POSIXct, and other calendars can all be
converted to yearmonthweekday.
as_year_month_weekday(x, ...)
as_year_month_weekday(x, ...)
x 
A vector to convert to yearmonthweekday. 
... 
These dots are for future extensions and must be empty. 
A yearmonthweekday vector.
# From Date as_year_month_weekday(as.Date("20190101")) # From POSIXct, which assumes that the naive time is what should be converted as_year_month_weekday(as.POSIXct("20190101 02:30:30", "America/New_York")) # From other calendars as_year_month_weekday(year_quarter_day(2019, quarter = 2, day = 50))
# From Date as_year_month_weekday(as.Date("20190101")) # From POSIXct, which assumes that the naive time is what should be converted as_year_month_weekday(as.POSIXct("20190101 02:30:30", "America/New_York")) # From other calendars as_year_month_weekday(year_quarter_day(2019, quarter = 2, day = 50))
as_year_quarter_day()
converts a vector to the yearquarterday
calendar. Time points, Dates, POSIXct, and other calendars can all be
converted to yearquarterday.
as_year_quarter_day(x, ..., start = NULL)
as_year_quarter_day(x, ..., start = NULL)
x 
A vector to convert to yearquarterday. 
... 
These dots are for future extensions and must be empty. 
start 
The month to start the fiscal year in. 1 = January and 12 = December. If

A yearquarterday vector.
# From Date as_year_quarter_day(as.Date("20190101")) as_year_quarter_day(as.Date("20190101"), start = 3) # From POSIXct, which assumes that the naive time is what should be converted as_year_quarter_day(as.POSIXct("20190101 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)
# From Date as_year_quarter_day(as.Date("20190101")) as_year_quarter_day(as.Date("20190101"), start = 3) # From POSIXct, which assumes that the naive time is what should be converted as_year_quarter_day(as.POSIXct("20190101 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)
as_year_week_day()
converts a vector to the yearweekday
calendar. Time points, Dates, POSIXct, and other calendars can all be
converted to yearweekday.
as_year_week_day(x, ..., start = NULL)
as_year_week_day(x, ..., start = NULL)
x 
A vector to convert to yearweekday. 
... 
These dots are for future extensions and must be empty. 
start 
The day to consider the start of the week. 1 = Sunday and 7 = Saturday. If

A yearweekday vector.
# From Date as_year_week_day(as.Date("20190101")) as_year_week_day(as.Date("20190101"), start = clock_weekdays$monday) # From POSIXct, which assumes that the naive time is what should be converted as_year_week_day(as.POSIXct("20190101 02:30:30", "America/New_York")) # From other calendars as_year_week_day(year_quarter_day(2019, quarter = 2, day = 50))
# From Date as_year_week_day(as.Date("20190101")) as_year_week_day(as.Date("20190101"), start = clock_weekdays$monday) # From POSIXct, which assumes that the naive time is what should be converted as_year_week_day(as.POSIXct("20190101 02:30:30", "America/New_York")) # From other calendars as_year_week_day(year_quarter_day(2019, quarter = 2, day = 50))
as_zoned_time()
converts x
to a zonedtime. You generally convert
to a zoned time from either a systime or a naive time. Each are documented
on their own page:
There are also convenience methods for converting to a zoned time from native R date and datetime types:
as_zoned_time(x, ...)
as_zoned_time(x, ...)
x 
An object to convert to a zonedtime. 
... 
These dots are for future extensions and must be empty. 
A zonedtime vector.
x < as.Date("20190101") as_zoned_time(x, "Europe/London") y < as_naive_time(year_month_day(2019, 2, 1)) as_zoned_time(y, zone = "America/New_York")
x < as.Date("20190101") as_zoned_time(x, "Europe/London") y < as_naive_time(year_month_day(2019, 2, 1)) as_zoned_time(y, zone = "America/New_York")
This is a Date method for the as_zoned_time()
generic.
clock assumes that Dates are naive datetime types. Like naivetimes, they have a yettobespecified 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).
## S3 method for class 'Date' as_zoned_time(x, zone, ..., nonexistent = NULL, ambiguous = NULL)
## S3 method for class 'Date' as_zoned_time(x, zone, ..., nonexistent = NULL, ambiguous = NULL)
x 
A Date. 
zone 
The zone to convert to. 
... 
These dots are for future extensions and must be empty. 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
In the rare instance that the specified time zone does not contain a
datetime 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.
A zonedtime.
x < as.Date("20190101") # The resulting zonedtimes 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 > zonedtime is the same as naivetime > zonedtime 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 # 20210327 23:59:59 > 20210328 01:00:00, # skipping the 0th hour entirely. This means there is no midnight value. x < as.Date("20210328") try(as_zoned_time(x, "Asia/Beirut")) # To resolve this, set a `nonexistent` time resolution strategy as_zoned_time(x, "Asia/Beirut", nonexistent = "rollforward")
x < as.Date("20190101") # The resulting zonedtimes 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 > zonedtime is the same as naivetime > zonedtime 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 # 20210327 23:59:59 > 20210328 01:00:00, # skipping the 0th hour entirely. This means there is no midnight value. x < as.Date("20210328") try(as_zoned_time(x, "Asia/Beirut")) # To resolve this, set a `nonexistent` time resolution strategy as_zoned_time(x, "Asia/Beirut", nonexistent = "rollforward")
This is a naivetime method for the as_zoned_time()
generic.
Converting to a zonedtime from a naivetime retains the printed time,
but changes the underlying duration, depending on the zone
that you choose.
Naivetimes are time points with a yettobedetermined time zone. By converting them to a zonedtime, 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 zonedtime from a systime, which is a time point interpreted as having a UTC time zone.
## S3 method for class 'clock_naive_time' as_zoned_time(x, zone, ..., nonexistent = NULL, ambiguous = NULL)
## S3 method for class 'clock_naive_time' as_zoned_time(x, zone, ..., nonexistent = NULL, ambiguous = NULL)
x 
A naivetime to convert to a zonedtime. 
zone 
The zone to convert to. 
... 
These dots are for future extensions and must be empty. 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
A zonedtime vector.
Converting from a naivetime to a zonedtime 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 "20200308 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 "20200308 02:30:00"
, you
couldn't convert that straight into a zonedtime 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 "20201101 01:59:59 EDT"
, at which
point the clocks "fell backwards" by 1 hour, resulting in a printed time of
"20201101 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
"20201101 01:30:00"
, you wouldn't be able to convert that directly
into a zonedtime 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.
library(magrittr) x < as_naive_time(year_month_day(2019, 1, 1)) # Converting a naivetime to a zonedtime 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 # 20200308 01:59:59 > 03:00:00, which means that one of these # naivetimes 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 = "rollforward") as_zoned_time(nonexistent_time, new_york, nonexistent = "rollbackward") # 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 = "rollbackward") # 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 = "shiftforward" ) 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 20201101 01:59:59 EDT > 20201101 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 zonedtimes, 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 `"20201101 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 naivetime 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 naivetime 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"))
library(magrittr) x < as_naive_time(year_month_day(2019, 1, 1)) # Converting a naivetime to a zonedtime 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 # 20200308 01:59:59 > 03:00:00, which means that one of these # naivetimes 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 = "rollforward") as_zoned_time(nonexistent_time, new_york, nonexistent = "rollbackward") # 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 = "rollbackward") # 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 = "shiftforward" ) 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 20201101 01:59:59 EDT > 20201101 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 zonedtimes, 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 `"20201101 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 naivetime 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 naivetime 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"))
This is a POSIXct/POSIXlt method for the as_zoned_time()
generic.
Converting from one of R's native datetime classes (POSIXct or POSIXlt)
will retain the time zone of that object. There is no zone
argument.
## S3 method for class 'POSIXt' as_zoned_time(x, ...)
## S3 method for class 'POSIXt' as_zoned_time(x, ...)
x 
A datetime. 
... 
These dots are for future extensions and must be empty. 
A zonedtime.
x < as.POSIXct("20190101", tz = "America/New_York") as_zoned_time(x)
x < as.POSIXct("20190101", tz = "America/New_York") as_zoned_time(x)
This is a systime method for the as_zoned_time()
generic.
Converting to a zonedtime from a systime retains the underlying duration,
but changes the printed time, depending on the zone
that you choose.
Remember that systimes are interpreted as UTC.
If you want to retain the printed time, try converting to a zonedtime from a naivetime, which is a time point with a yettobedetermined time zone.
## S3 method for class 'clock_sys_time' as_zoned_time(x, zone, ...)
## S3 method for class 'clock_sys_time' as_zoned_time(x, zone, ...)
x 
A systime to convert to a zonedtime. 
zone 
The zone to convert to. 
... 
These dots are for future extensions and must be empty. 
A zonedtime vector.
x < as_sys_time(year_month_day(2019, 02, 01, 02, 30, 00)) x # Since systime is interpreted as UTC, converting to a zonedtime 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
x < as_sys_time(year_month_day(2019, 02, 01, 02, 30, 00)) x # Since systime is interpreted as UTC, converting to a zonedtime 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
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:
calendar_group(x, precision, ..., n = 1L)
calendar_group(x, precision, ..., n = 1L)
x 
A calendar vector. 
precision 
A precision. Allowed precisions are dependent on the calendar used. 
... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
x
grouped at the specified precision
.
# 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)
# 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)
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 start
s 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.
calendar_leap_year(x)
calendar_leap_year(x)
x 
A calendar type to detect leap years in. 
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
.
x < year_month_day(c(2019:2024, NA)) calendar_leap_year(x) # For yearquarterday, 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))
x < year_month_day(c(2019:2024, NA)) calendar_leap_year(x) # For yearquarterday, 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))
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.
calendar_month_factor(x, ..., labels = "en", abbreviate = FALSE)
calendar_month_factor(x, ..., labels = "en", abbreviate = FALSE)
x 
A calendar vector. 
... 
These dots are for future extensions and must be empty. 
labels 
Character representations of localized weekday names, month names, and
AM/PM names. Either the language code as string (passed on to

abbreviate 
If If 
An ordered factor representing the months.
x < year_month_day(2019, 1:12) calendar_month_factor(x) calendar_month_factor(x, abbreviate = TRUE) calendar_month_factor(x, labels = "fr")
x < year_month_day(2019, 1:12) calendar_month_factor(x) calendar_month_factor(x, abbreviate = TRUE) calendar_month_factor(x, labels = "fr")
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:
calendar_narrow(x, precision)
calendar_narrow(x, precision)
x 
A calendar vector. 
precision 
A precision. Allowed precisions are dependent on the calendar used. 
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()
.
x
narrowed to the supplied precision
.
# 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")
# 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")
calendar_precision()
extracts the precision from a calendar object. It
returns the precision as a single string.
calendar_precision(x)
calendar_precision(x)
x 
A calendar. 
A single string holding the precision of the calendar.
calendar_precision(year_month_day(2019)) calendar_precision(year_month_day(2019, 1, 1)) calendar_precision(year_quarter_day(2019, 3))
calendar_precision(year_month_day(2019)) calendar_precision(year_month_day(2019, 1, 1)) calendar_precision(year_quarter_day(2019, 3))
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 timepoint first. See the individual seq()
method documentation to learn
what precisions are allowed.
calendar_spanning_seq(x)
calendar_spanning_seq(x)
x 
A calendar vector. 
Missing values are automatically removed before the sequence is generated.
If you need more precise sequence generation, call range()
and seq()
directly.
A sequence along [min(x), max(x)]
.
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))
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))
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:
calendar_widen(x, precision)
calendar_widen(x, precision)
x 
A calendar vector. 
precision 
A precision. Allowed precisions are dependent on the calendar used. 
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 yearmonthday is treated as a range
over [yyyymm01, yyyymmlast]
, 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.
x
widened to the supplied precision
.
# Month precision x < year_month_day(2019, 1) x # Widen to day precision calendar_widen(x, "day") # Or second precision calendar_widen(x, "second")
# Month precision x < year_month_day(2019, 1) x # Widen to day precision calendar_widen(x, "day") # Or second precision calendar_widen(x, "second")
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:
calendar_start(x, precision) calendar_end(x, precision)
calendar_start(x, precision) calendar_end(x, precision)
x 
A calendar vector. 
precision 
A precision. Allowed precisions are dependent on the calendar used. 
x
at the same precision, but with some components altered to be
at the boundary value.
# 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")
# 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")
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:
calendar_count_between(start, end, precision, ..., n = 1L)
calendar_count_between(start, end, precision, ..., n = 1L)
start , end

A pair of calendar vectors. These will be recycled to their common size. 
precision 
A precision. Allowed precisions are dependent on the calendar used. 
... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
An integer representing the number of precision
units between
start
and end
.
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.
# Number of whole years between these dates x < year_month_day(2000, 01, 05) y < year_month_day(2005, 01, 04:06) # Note that `20000105 > 20050104` is only 4 full years calendar_count_between(x, y, "year")
# Number of whole years between these dates x < year_month_day(2000, 01, 05) y < year_month_day(2005, 01, 04:06) # Note that `20000105 > 20050104` is only 4 full years calendar_count_between(x, y, "year")
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://unicodeorg.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.
clock_labels( month, month_abbrev = month, weekday, weekday_abbrev = weekday, am_pm ) clock_labels_lookup(language) clock_labels_languages()
clock_labels( month, month_abbrev = month, weekday, weekday_abbrev = weekday, am_pm ) clock_labels_lookup(language) clock_labels_languages()
month , month_abbrev

Full and abbreviated month names. Starts with January. 
weekday , weekday_abbrev

Full and abbreviated weekday names. Starts with Sunday. 
am_pm 
Names used for AM and PM. 
language 
A BCP 47 locale, generally constructed from a two or three
digit language code. See 
A "clock_labels"
object.
clock_labels_lookup("en") clock_labels_lookup("ko") clock_labels_lookup("fr")
clock_labels_lookup("en") clock_labels_lookup("ko") clock_labels_lookup("fr")
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.
clock_locale(labels = "en", decimal_mark = ".")
clock_locale(labels = "en", decimal_mark = ".")
labels 
Character representations of localized weekday names, month names, and
AM/PM names. Either the language code as string (passed on to

decimal_mark 
Symbol used for the decimal place when formatting subsecond datetimes.
Either 
A "clock_locale"
object.
clock_locale() clock_locale(labels = "fr")
clock_locale() clock_locale(labels = "fr")
This is the landing page for all clock arithmetic functions. There are specific subpages 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.
Time points, such as naivetimes and systimes, are efficient at arithmetic with regular, welldefined units of time, such as days, hours, seconds, or nanoseconds.
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.
Weekdays can perform daybased circular arithmetic.
There are also convenience methods for doing arithmetic directly on a native R date or datetime type:
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, ...)
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, ...)
x 
An object. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
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.
x
after performing the arithmetic.
# See each subpage for more specific examples x < year_month_day(2019, 2, 1) add_months(x, 1)
# See each subpage for more specific examples x < year_month_day(2019, 2, 1) add_months(x, 1)
Objects with useful mappings from month names and weekday names to integer 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
clock_weekdays
)sunday == 1
monday == 2
tuesday == 3
wednesday == 4
thursday == 5
friday == 6
saturday == 7
clock_iso_weekdays
)monday == 1
tuesday == 2
wednesday == 3
thursday == 4
friday == 5
saturday == 6
sunday == 7
clock_months clock_weekdays clock_iso_weekdays
clock_months clock_weekdays clock_iso_weekdays
clock_months
: An environment containing month codes.
clock_weekdays
: An environment containing weekday codes.
clock_iso_weekdays
: An environment containing ISO weekday codes.
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)
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)
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:
There are also convenience methods for extracting certain components directly from R's native date and datetime types.
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)
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)
x 
An object to get the component from. 
You cannot extract components directly from a time point type, such as systime or naivetime. Convert it to a calendar type first. Similarly, a zonedtime must be converted to either a systime or naivetime, and then to a calendar type, to be able to extract components from it.
The component.
x < year_month_day(2019, 1:3, 5:7, 1, 20, 30) get_month(x) get_day(x) get_second(x)
x < year_month_day(2019, 1:3, 5:7, 1, 20, 30) get_month(x) get_day(x) get_second(x)
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 20190231
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.
invalid_detect(x) invalid_any(x) invalid_count(x) invalid_remove(x) invalid_resolve(x, ..., invalid = NULL)
invalid_detect(x) invalid_any(x) invalid_count(x) invalid_remove(x) invalid_resolve(x, ..., invalid = NULL)
x 
A calendar vector. 
... 
These dots are for future extensions and must be empty. 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
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.
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.
# 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 = "previousday") x_previous_day # Note that `"previous"` retains the relative ordering in `x` x[1] < x[2] x_previous[1] < x_previous[2] # But `"previousday"` 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")
# 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 = "previousday") x_previous_day # Note that `"previous"` retains the relative ordering in `x` x[1] < x[2] x_previous[1] < x_previous[2] # But `"previousday"` 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")
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:
There are also convenience methods for setting certain components directly on R's native date and datetime types.
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 yearmonthday type. You'd have to convert to yearquarterday 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 yearmonthday 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 subsecond 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.
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, ...)
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, ...)
x 
An object to set the component for. 
value 
The value to set the component to. 
... 
These dots are for future extensions and must be empty. 
You cannot set components directly on a time point type, such as systime or naivetime. Convert it to a calendar type first. Similarly, a zonedtime must be converted to either a systime or naivetime, and then to a calendar type, to be able to set components on it.
x
with the component set.
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")
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")
date_build()
builds a Date from it's individual components.
date_build(year, month = 1L, day = 1L, ..., invalid = NULL)
date_build(year, month = 1L, day = 1L, ..., invalid = NULL)
year 
The year. Values 
month 
The month. Values 
day 
The day of the month. Values If 
... 
These dots are for future extensions and must be empty. 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
Components are recycled against each other using tidyverse recycling rules.
A Date.
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")
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")
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 datetimes:
date_count_between(start, end, precision, ..., n = 1L)
date_count_between(start, end, precision, ..., n = 1L)
start , end

A pair of date or datetime vectors. These will be recycled to their common size. 
precision 
A precision. Allowed precisions are dependent on the calendar used. 
... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
An integer representing the number of precision
units between
start
and end
.
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.
# See method specific documentation for more examples start < date_parse("20000505") end < date_parse(c("20200504", "20200506")) # Age in years date_count_between(start, end, "year") # Number of "whole" months between these dates date_count_between(start, end, "month")
# See method specific documentation for more examples start < date_parse("20000505") end < date_parse(c("20200504", "20200506")) # Age in years date_count_between(start, end, "year") # Number of "whole" months between these dates date_count_between(start, end, "month")
date_format()
formats a date (Date) or datetime (POSIXct/POSIXlt) using
a format
string.
There are separate help pages for formatting dates and datetimes:
date_format(x, ...)
date_format(x, ...)
x 
A date or datetime vector. 
... 
These dots are for future extensions and must be empty. 
A character vector of the formatted input.
# See method specific documentation for more examples x < as.Date("20190101") date_format(x, format = "year: %Y, month: %m, day: %d")
# See method specific documentation for more examples x < as.Date("20190101") date_format(x, format = "year: %Y, month: %m, day: %d")
date_group()
groups by a single component of a datetime, such as month
of the year, or day of the month.
There are separate help pages for grouping dates and datetimes:
date_group(x, precision, ..., n = 1L)
date_group(x, precision, ..., n = 1L)
x 
A date or datetime vector. 
precision 
A precision. Allowed precisions are dependent on the input used. 
... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
x
, grouped at precision
.
# See type specific documentation for more examples date_group(as.Date("20190101") + 0:5, "day", n = 2)
# See type specific documentation for more examples date_group(as.Date("20190101") + 0:5, "day", n = 2)
date_leap_year()
detects if the year is a leap year.
date_leap_year(x)
date_leap_year(x)
x 
A date or datetime to detect leap years in. 
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
.
x < as.Date("20190101") x < add_years(x, 0:5) date_leap_year(x) y < as.POSIXct("20190101", "America/New_York") y < add_years(y, 0:5) date_leap_year(y)
x < as.Date("20190101") x < add_years(x, 0:5) date_leap_year(x) y < as.POSIXct("20190101", "America/New_York") y < add_years(y, 0:5) date_leap_year(y)
date_month_factor()
extracts the month values from a date or datetime and
converts them to an ordered factor of month names. This can be useful in
combination with ggplot2, or for modeling.
date_month_factor(x, ..., labels = "en", abbreviate = FALSE)
date_month_factor(x, ..., labels = "en", abbreviate = FALSE)
x 
A date or datetime vector. 
... 
These dots are for future extensions and must be empty. 
labels 
Character representations of localized weekday names, month names, and
AM/PM names. Either the language code as string (passed on to

abbreviate 
If If 
An ordered factor representing the months.
x < add_months(as.Date("20190101"), 0:11) date_month_factor(x) date_month_factor(x, abbreviate = TRUE) date_month_factor(x, labels = "fr")
x < add_months(as.Date("20190101"), 0:11) date_month_factor(x) date_month_factor(x, abbreviate = TRUE) date_month_factor(x, labels = "fr")
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.
date_parse(x, ..., format = NULL, locale = clock_locale())
date_parse(x, ..., format = NULL, locale = clock_locale())
x 
A character vector to parse. 
... 
These dots are for future extensions and must be empty. 
format 
A format string. A combination of the following commands, or A vector of multiple format strings can be supplied. They will be tried in the order they are provided. Year
Month
Day
Day of the week
ISO 8601 weekbased year
Week of the year
Day of the year
Date
Time of day
Time zone
Miscellaneous

locale 
A locale object created from 
date_parse()
ignores both the %z
and %Z
commands, as clock treats
Date as a naive type, with a yettobespecified time zone.
Parsing strings with subdaily 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 subdaily 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("20190105 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 subdaily string into a
Date is ambiguous and undefined, and is unlikely to work as you might expect.
For example, date_parse("20190105 00:01:02", format = "%Y%m%d %H:%M:%S")
is not officially supported, even if it works in
some cases.
A Date.
date_parse("20200101") 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 yearweekday format date_parse("2020W012", format = "%GW%V%u") #  # Subdaily components # If you have a string with subdaily components, but only require the date, # first parse them as datetimes to fully parse the subdaily components, # then round using whatever convention is required for your use case before # converting to date. x < c("20190101 11", "20190101 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"))
date_parse("20200101") 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 yearweekday format date_parse("2020W012", format = "%GW%V%u") #  # Subdaily components # If you have a string with subdaily components, but only require the date, # first parse them as datetimes to fully parse the subdaily components, # then round using whatever convention is required for your use case before # converting to date. x < c("20190101 11", "20190101 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"))
date_seq()
generates a date (Date) or datetime (POSIXct/POSIXlt) sequence.
There are separate help pages for generating sequences for dates and datetimes:
date_seq(from, ..., to = NULL, by = NULL, total_size = NULL)
date_seq(from, ..., to = NULL, by = NULL, total_size = NULL)
from 
A date or datetime to start the sequence from. 
... 
These dots are for future extensions and must be empty. 
to 
A date or datetime to stop the sequence at.

by 
The unit to increment the sequence by. 
total_size 
The size of the resulting sequence. If specified alongside 
A date or datetime vector.
# See method specific documentation for more examples x < as.Date("20190101") date_seq(x, by = duration_months(2), total_size = 20)
# See method specific documentation for more examples x < as.Date("20190101") date_seq(x, by = duration_months(2), total_size = 20)
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 datetimes it generates a second precision sequence.
date_spanning_seq(x)
date_spanning_seq(x)
x 
A date or datetime vector. 
Missing and infinite values are automatically removed before the sequence is generated.
For datetimes, systime 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.
A sequence along [min(x), max(x)]
.
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 datetimes, 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)
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 datetimes, 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)
date_time_build()
builds a POSIXct from it's individual components.
To build a POSIXct, it is required that you specify the zone
.
date_time_build( year, month = 1L, day = 1L, hour = 0L, minute = 0L, second = 0L, ..., zone, invalid = NULL, nonexistent = NULL, ambiguous = NULL )
date_time_build( year, month = 1L, day = 1L, hour = 0L, minute = 0L, second = 0L, ..., zone, invalid = NULL, nonexistent = NULL, ambiguous = NULL )
year 
The year. Values 
month 
The month. Values 
day 
The day of the month. Values If 
hour 
The hour. Values 
minute 
The minute. Values 
second 
The second. Values 
... 
These dots are for future extensions and must be empty. 
zone 
A valid time zone name. This argument is required, and must be specified by name. 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
Components are recycled against each other using tidyverse recycling rules.
A POSIXct.
# 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 = "rollforward" )
# 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 = "rollforward" )
date_time_info()
retrieves a set of lowlevel information generally not
required for most datetime manipulations. It returns a data frame with the
same columns as sys_time_info()
, but the begin
and end
columns are
datetimes 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 highlevel API.
date_time_info(x)
date_time_info(x)
x 
A datetime. 
A data frame of low level information.
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)
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)
date_weekday_factor()
converts a date or datetime to an ordered factor
with levels representing the weekday. This can be useful in combination with
ggplot2, or for modeling.
date_weekday_factor( x, ..., labels = "en", abbreviate = TRUE, encoding = "western" )
date_weekday_factor( x, ..., labels = "en", abbreviate = TRUE, encoding = "western" )
x 
A date or datetime vector. 
... 
These dots are for future extensions and must be empty. 
labels 
Character representations of localized weekday names, month names, and
AM/PM names. Either the language code as string (passed on to

abbreviate 
If If 
encoding 
One of:

An ordered factor representing the weekdays.
x < as.Date("20190101") + 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")
x < as.Date("20190101") + 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")
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 datetimes:
date_start(x, precision, ...) date_end(x, precision, ...)
date_start(x, precision, ...) date_end(x, precision, ...)
x 
A date or datetime vector. 
precision 
A precision. Allowed precisions are dependent on the input used. 
... 
These dots are for future extensions and must be empty. 
x
but with some components altered to be at the boundary value.
# 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")
# 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_floor()
rounds a date or datetime down to a multiple of
the specified precision
.
date_ceiling()
rounds a date or datetime 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 datetimes:
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
19700101 00:00:00.
If you want to group by components, such as "day of the month", see
date_group()
.
date_floor(x, precision, ..., n = 1L, origin = NULL) date_ceiling(x, precision, ..., n = 1L, origin = NULL) date_round(x, precision, ..., n = 1L, origin = NULL)
date_floor(x, precision, ..., n = 1L, origin = NULL) date_ceiling(x, precision, ..., n = 1L, origin = NULL) date_round(x, precision, ..., n = 1L, origin = NULL)
x 
A date or datetime vector. 
precision 
A precision. Allowed precisions are dependent on the input used. 
... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
origin 
An origin to start counting from. The default 
x
rounded to the specified precision
.
# See the type specific documentation for more examples x < as.Date("20190331") + 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)
# See the type specific documentation for more examples x < as.Date("20190331") + 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)
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 datetimes:
date_shift(x, target, ..., which = "next", boundary = "keep")
date_shift(x, target, ..., which = "next", boundary = "keep")
x 
A date or datetime vector. 
target 
A weekday created from Generally this is length 1, but can also be the same length as 
... 
These dots are for future extensions and must be empty. 
which 
One of:

boundary 
One of:

x
shifted to the target
weekday.
# See the type specific documentation for more examples x < as.Date("20190101") + 0:1 # A Tuesday and Wednesday as_weekday(x) monday < weekday(clock_weekdays$monday) # Shift to the next Monday date_shift(x, monday)
# See the type specific documentation for more examples x < as.Date("20190101") + 0:1 # A Tuesday and Wednesday as_weekday(x) monday < weekday(clock_weekdays$monday) # Shift to the next Monday date_shift(x, monday)
These are Date methods for the arithmetic generics.
Calendrical based arithmetic:
These functions convert to a yearmonthday 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()
## 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, ...)
## 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, ...)
x 
A Date vector. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
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.
x
after performing the arithmetic.
x < as.Date("20190101") add_years(x, 1:5) y < as.Date("20190131") # Adding 1 month to `y` generates an invalid date. Unlike yearmonthday # 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")
x < as.Date("20190101") add_years(x, 1:5) y < as.Date("20190131") # Adding 1 month to `y` generates an invalid date. Unlike yearmonthday # 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")
This is a Date method for the date_start()
and date_end()
generics.
## S3 method for class 'Date' date_start(x, precision, ..., invalid = NULL) ## S3 method for class 'Date' date_end(x, precision, ..., invalid = NULL)
## S3 method for class 'Date' date_start(x, precision, ..., invalid = NULL) ## S3 method for class 'Date' date_end(x, precision, ..., invalid = NULL)
x 
A date vector. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
x
but with some components altered to be at the boundary value.
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")
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")
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 yearmonthday 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 datetimes.
## S3 method for class 'Date' date_count_between(start, end, precision, ..., n = 1L)
## S3 method for class 'Date' date_count_between(start, end, precision, ..., n = 1L)
start , end

A pair of date vectors. These will be recycled to their common size. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
"quarter"
is equivalent to "month"
precision with n
set to n * 3L
.
An integer representing the number of precision
units between
start
and end
.
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.
start < date_parse("20000505") end < date_parse(c("20200504", "20200506")) # Age in years date_count_between(start, end, "year") # Number of "whole" months between these dates. i.e. # `20000505 > 20200405` is 239 months # `20000505 > 20200505` is 240 months # Since 20200504 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 )
start < date_parse("20000505") end < date_parse(c("20200504", "20200506")) # Age in years date_count_between(start, end, "year") # Number of "whole" months between these dates. i.e. # `20000505 > 20200405` is 239 months # `20000505 > 20200505` is 240 months # Since 20200504 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 )
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.
## S3 method for class 'Date' date_format(x, ..., format = NULL, locale = clock_locale())
## S3 method for class 'Date' date_format(x, ..., format = NULL, locale = clock_locale())
x 
A date vector. 
... 
These dots are for future extensions and must be empty. 
format 
If Otherwise, a format string which is a combination of: Year
Month
Day
Day of the week
ISO 8601 weekbased year
Week of the year
Day of the year
Date
Time of day
Time zone
Miscellaneous

locale 
A locale object created from 
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
.
A character vector of the formatted input.
x < as.Date("20190101") # 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"))
x < as.Date("20190101") # 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"))
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.
## S3 method for class 'Date' get_year(x) ## S3 method for class 'Date' get_month(x) ## S3 method for class 'Date' get_day(x)
## S3 method for class 'Date' get_year(x) ## S3 method for class 'Date' get_month(x) ## S3 method for class 'Date' get_day(x)
x 
A Date to get the component from. 
The component.
x < as.Date("20190101") + 0:5 get_day(x)
x < as.Date("20190101") + 0:5 get_day(x)
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.
## S3 method for class 'Date' date_group(x, precision, ..., n = 1L, invalid = NULL)
## S3 method for class 'Date' date_group(x, precision, ..., n = 1L, invalid = NULL)
x 
A date vector. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
x
, grouped at precision
.
x < as.Date("20190101") + 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")
x < as.Date("20190101") + 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")
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 precision
s for Dates are "day"
and "week"
.
You can group by irregular periods such as "month"
or "year"
by using
date_group()
.
## 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)
## 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)
x 
A date vector. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
origin 
An origin to start counting from. The default 
When rounding by "week"
, remember that the origin
determines the "week
start". By default, 19700101 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.
x
rounded to the specified precision
.
x < as.Date("20190331") + 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("20190101") + 0:20 y # Flooring by week uses an implicit `origin` of 19700101, 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("19700105") as_weekday(origin) date_floor(y, "week", origin = origin) as_weekday(date_floor(y, "week", origin = origin))
x < as.Date("20190331") + 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("20190101") + 0:20 y # Flooring by week uses an implicit `origin` of 19700101, 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("19700105") as_weekday(origin) date_floor(y, "week", origin = origin) as_weekday(date_floor(y, "week", origin = origin))
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
## S3 method for class 'Date' date_seq(from, ..., to = NULL, by = NULL, total_size = NULL, invalid = NULL)
## S3 method for class 'Date' date_seq(from, ..., to = NULL, by = NULL, total_size = NULL, invalid = NULL)
from 
A date to start the sequence from. 
... 
These dots are for future extensions and must be empty. 
to 
A date to stop the sequence at.
If 
by 
The unit to increment the sequence by. If If

total_size 
The size of the resulting sequence. If specified alongside 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
A date vector.
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 nonfractional 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))
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 nonfractional 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))
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]
.
## 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)
## 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)
x 
A Date vector. 
value 
The value to set the component to. For 
... 
These dots are for future extensions and must be empty. 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
x
with the component set.
x < as.Date("20190201") # 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 yearmonthday. 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")
x < as.Date("20190201") # 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 yearmonthday. 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")
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.
## S3 method for class 'Date' date_shift(x, target, ..., which = "next", boundary = "keep")
## S3 method for class 'Date' date_shift(x, target, ..., which = "next", boundary = "keep")
x 
A date vector. 
target 
A weekday created from Generally this is length 1, but can also be the same length as 
... 
These dots are for future extensions and must be empty. 
which 
One of:

boundary 
One of:

x
shifted to the target
weekday.
x < as.Date("20190101") + 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")
x < as.Date("20190101") + 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")
There are four parsers for parsing strings into POSIXct datetimes,
date_time_parse()
, date_time_parse_complete()
,
date_time_parse_abbrev()
, and date_time_parse_RFC_3339()
.
date_time_parse()
is useful for strings like "20190101 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 naivetime without any time zone assumptions, and
is then converted to a POSIXct with the supplied zone
.
Because converting from naivetime 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 datetime.
date_time_parse_complete()
is a parser for complete datetime strings,
like "20190101T00:00:0005:00[America/New_York]"
. A complete datetime
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 zonedtime. 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 datetime.
Additionally, this format matches the defacto standard extension to RFC 3339
for creating completely unambiguous datetimes.
date_time_parse_abbrev()
is a parser for datetime strings containing only
a time zone abbreviation, like "20190101 00:00:00 EST"
. The time zone
abbreviation is not enough to identify the full time zone name that the
datetime 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
datetime.
date_time_parse_RFC_3339()
is a parser for datetime strings in the
extremely common datetime 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:
20190101T00:00:00Z 20190101T00:00:00+0430 20190101T00: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 datetime 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 datetimes returned by this function will always be in the UTC time zone.
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")
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")
x 
A character vector to parse. 
zone 
A full time zone name. 
... 
These dots are for future extensions and must be empty. 
format 
A format string. A combination of the following commands, or A vector of multiple format strings can be supplied. They will be tried in the order they are provided. Year
Month
Day
Day of the week
ISO 8601 weekbased year
Week of the year
Day of the year
Date
Time of day
Time zone
Miscellaneous

locale 
A locale object created from 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
separator 
The separator between the date and time components of the string. One of:

offset 
The format of the offset from UTC contained in the string. One of:

If date_time_parse_complete()
is given input that is length zero, all
NA
s, 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 subsecond components, then these datetime 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 naivetime 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.
A POSIXct.
# Parse with a known `zone`, even though that information isn't in the string date_time_parse("20200101 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("20200101T05:06:0705:00[America/New_York]") # Only day components date_time_parse("20200101", "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("19701025 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 < "19701025 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( "19701025T01:00:0004:00[America/New_York]", "19701025T01:00:0005: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( "19701025 01:00:00 EDT", "19701025 01:00:00 EST" ) date_time_parse_abbrev(abbrev_times, "America/New_York") #  # RFC 3339 # Typical UTC format x < "20190101T00:01:02Z" date_time_parse_RFC_3339(x) # With a UTC offset containing a `:` x < "20190101T00: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 < "20190101 00:01:02+0230" date_time_parse_RFC_3339(x, separator = " ", offset = "%z") #  # Subsecond components # If you have a string with subsecond components, but only require up to # seconds, first parse them into a clock type that can handle subseconds to # fully capture that information, then round using whatever convention is # required for your use case before converting to a datetime. x < c("20190101T00:00:01.1", "20190101T00: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")
# Parse with a known `zone`, even though that information isn't in the string date_time_parse("20200101 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("20200101T05:06:0705:00[America/New_York]") # Only day components date_time_parse("20200101", "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("19701025 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 < "19701025 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( "19701025T01:00:0004:00[America/New_York]", "19701025T01:00:0005: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( "19701025 01:00:00 EDT", "19701025 01:00:00 EST" ) date_time_parse_abbrev(abbrev_times, "America/New_York") #  # RFC 3339 # Typical UTC format x < "20190101T00:01:02Z" date_time_parse_RFC_3339(x) # With a UTC offset containing a `:` x < "20190101T00: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 < "20190101 00:01:02+0230" date_time_parse_RFC_3339(x, separator = " ", offset = "%z") #  # Subsecond components # If you have a string with subsecond components, but only require up to # seconds, first parse them into a clock type that can handle subseconds to # fully capture that information, then round using whatever convention is # required for your use case before converting to a datetime. x < c("20190101T00:00:01.1", "20190101T00: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")
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.
date_time_zone(x) date_time_set_zone(x, zone)
date_time_zone(x) date_time_set_zone(x, zone)
x 
A datetime vector. 
zone 
A valid time zone to switch to. 
This function is only valid for datetimes, as clock treats R's Date class as a naive type, which always has a yettobespecified time zone.
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.
library(magrittr) # Cannot set or get the zone of Date. # clock assumes that Dates are naive types, like naivetime. x < date_parse("20190101") try(date_time_zone(x)) try(date_time_set_zone(x, "America/New_York")) x < date_time_parse("20190102 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 naivetime to drop the time zone, then convert back to a # datetime. 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("20210328 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 = "rollforward") as_date_time(y_nt, "Europe/Helsinki", nonexistent = "rollbackward")
library(magrittr) # Cannot set or get the zone of Date. # clock assumes that Dates are naive types, like naivetime. x < date_parse("20190101") try(date_time_zone(x)) try(date_time_set_zone(x, "America/New_York")) x < date_time_parse("20190102 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 naivetime to drop the time zone, then convert back to a # datetime. 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("20210328 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 = "rollforward") as_date_time(y_nt, "Europe/Helsinki", nonexistent = "rollbackward")
date_today()
returns the current date in the specified zone
as a Date.
date_now()
returns the current datetime in the specified zone
as a
POSIXct.
date_today(zone) date_now(zone)
date_today(zone) date_now(zone)
zone 
A time zone to get the current time for. 
clock assumes that Date is a naive type, like naivetime. This means that
date_today()
first looks up the current datetime in the specified zone
,
then converts that to a Date, retaining the printed time while dropping any
information about that time zone.
date_today()
a single Date.
date_now()
a single POSIXct.
# Current date in the local time zone date_today("") # Current date in a specified time zone date_today("Europe/London") # Current datetime in that same time zone date_now("Europe/London")
# Current date in the local time zone date_today("") # Current date in a specified time zone date_today("Europe/London") # Current datetime in that same time zone date_now("Europe/London")
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.
duration_cast(x, precision)
duration_cast(x, precision)
x 
A duration. 
precision 
A precision. One of:

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 pre1970, which are stored as negative
durations).
x
cast to the new precision
.
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 pre1970 date up to the next # day, while the post1970 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")
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 pre1970 date up to the next # day, while the post1970 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")
duration_precision()
extracts the precision from a duration object. It
returns the precision as a single string.
duration_precision(x)
duration_precision(x)
x 
A duration. 
A single string holding the precision of the duration.
duration_precision(duration_seconds(1)) duration_precision(duration_nanoseconds(2)) duration_precision(duration_quarters(1:5))
duration_precision(duration_seconds(1)) duration_precision(duration_nanoseconds(2)) duration_precision(duration_quarters(1:5))
duration_spanning_seq()
generates a regular sequence along the span of x
,
i.e. along [min(x), max(x)]
.
duration_spanning_seq(x)
duration_spanning_seq(x)
x 
A duration vector. 
Missing values are automatically removed before the sequence is generated.
If you need more precise sequence generation, call range()
and seq()
directly.
A sequence along [min(x), max(x)]
.
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)
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)
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.
## 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, ...)
## 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, ...)
x 
A duration vector. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
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.
x
after performing the arithmetic, possibly with a more precise
precision.
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)
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)
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 yearmonthday. Chronological durations are generally used when working with time points, like systime or naivetime.
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())
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())
n 
The number of units of time to use when creating the duration. 
A duration of the specified precision.
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.
duration_years(1:5) duration_nanoseconds(1:5)
duration_years(1:5) duration_nanoseconds(1:5)
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.
duration_floor(x, precision, ..., n = 1L) duration_ceiling(x, precision, ..., n = 1L) duration_round(x, precision, ..., n = 1L)
duration_floor(x, precision, ..., n = 1L) duration_ceiling(x, precision, ..., n = 1L) duration_round(x, precision, ..., n = 1L)
x 
A duration. 
precision 
A precision. One of:

... 
These dots are for future extensions and must be empty. 
n 
A positive integer specifying the multiple of 
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.
x
rounded to the precision
.
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")
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")
This is a zonedtime method for the format()
generic.
This function allows you to format a zonedtime 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 defacto standard extension to
RFC 3339 for creating completely unambiguous datetimes.
## S3 method for class 'clock_zoned_time' format(x, ..., format = NULL, locale = clock_locale(), abbreviate_zone = FALSE)
## S3 method for class 'clock_zoned_time' format(x, ..., format = NULL, locale = clock_locale(), abbreviate_zone = FALSE)
x 
A zonedtime. 
... 
Not used, but no error will be thrown if not empty to remain compatible
with usage of the 
format 
If Otherwise, a format string which is a combination of: Year
Month
Day
Day of the week
ISO 8601 weekbased year
Week of the year
Day of the year
Date
Time of day
Time zone
Miscellaneous

locale 
A locale object created from 
abbreviate_zone 
If If 
A character vector of the formatted input.
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"))
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"))
x
a duration?This function determines if the input is a duration object.
is_duration(x)
is_duration(x)
x 
An object. 
TRUE
if x
inherits from "clock_duration"
, otherwise FALSE
.
is_duration(1) is_duration(duration_days(1))
is_duration(1) is_duration(duration_days(1))
x
a isoyearweekday?Check if x
is a isoyearweekday.
is_iso_year_week_day(x)
is_iso_year_week_day(x)
x 
An object. 
Returns TRUE
if x
inherits from "clock_iso_year_week_day"
,
otherwise returns FALSE
.
is_iso_year_week_day(iso_year_week_day(2019))
is_iso_year_week_day(iso_year_week_day(2019))
x
a naivetime?This function determines if the input is a naivetime object.
is_naive_time(x)
is_naive_time(x)
x 
An object. 
TRUE
if x
inherits from "clock_naive_time"
, otherwise FALSE
.
is_naive_time(1) is_naive_time(as_naive_time(duration_days(1)))
is_naive_time(1) is_naive_time(as_naive_time(duration_days(1)))
x
a systime?This function determines if the input is a systime object.
is_sys_time(x)
is_sys_time(x)
x 
An object. 
TRUE
if x
inherits from "clock_sys_time"
, otherwise FALSE
.
is_sys_time(1) is_sys_time(as_sys_time(duration_days(1)))
is_sys_time(1) is_sys_time(as_sys_time(duration_days(1)))
x
a weekday?This function determines if the input is a weekday object.
is_weekday(x)
is_weekday(x)
x 
An object. 
TRUE
if x
inherits from "clock_weekday"
, otherwise FALSE
.
is_weekday(1) is_weekday(weekday(1))
is_weekday(1) is_weekday(weekday(1))
x
a yearday?Check if x
is a yearday.
is_year_day(x)
is_year_day(x)
x 
An object. 
Returns TRUE
if x
inherits from "clock_year_day"
,
otherwise returns FALSE
.
is_year_day(year_day(2019))
is_year_day(year_day(2019))
x
a yearmonthday?Check if x
is a yearmonthday.
is_year_month_day(x)
is_year_month_day(x)
x 
An object. 
Returns TRUE
if x
inherits from "clock_year_month_day"
,
otherwise returns FALSE
.
is_year_month_day(year_month_day(2019))
is_year_month_day(year_month_day(2019))
x
a yearmonthweekday?Check if x
is a yearmonthweekday.
is_year_month_weekday(x)
is_year_month_weekday(x)
x 
An object. 
Returns TRUE
if x
inherits from "clock_year_month_weekday"
,
otherwise returns FALSE
.
is_year_month_weekday(year_month_weekday(2019))
is_year_month_weekday(year_month_weekday(2019))
x
a yearquarterday?Check if x
is a yearquarterday.
is_year_quarter_day(x)
is_year_quarter_day(x)
x 
An object. 
Returns TRUE
if x
inherits from "clock_year_quarter_day"
,
otherwise returns FALSE
.
is_year_quarter_day(year_quarter_day(2019))
is_year_quarter_day(year_quarter_day(2019))
x
a yearweekday?Check if x
is a yearweekday.
is_year_week_day(x)
is_year_week_day(x)
x 
An object. 
Returns TRUE
if x
inherits from "clock_year_week_day"
,
otherwise returns FALSE
.
is_year_week_day(year_week_day(2019))
is_year_week_day(year_week_day(2019))
x
a zonedtime?This function determines if the input is a zonedtime object.
is_zoned_time(x)
is_zoned_time(x)
x 
An object. 
TRUE
if x
inherits from "clock_zoned_time"
, otherwise FALSE
.
is_zoned_time(1) is_zoned_time(zoned_time_now("America/New_York"))
is_zoned_time(1) is_zoned_time(zoned_time_now("America/New_York"))
iso_year_week_day()
constructs a calendar from the ISO year, week number,
and week day.
iso_year_week_day( year, week = NULL, day = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., subsecond_precision = NULL )
iso_year_week_day( year, week = NULL, day = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., subsecond_precision = NULL )
year 
The ISO year. Values 
week 
The ISO week. Values If 
day 
The day of the week. Values 
hour 
The hour. Values 
minute 
The minute. Values 
second 
The second. Values 
subsecond 
The subsecond. If specified, If using milliseconds, values If using microseconds, values If using nanoseconds, values 
... 
These dots are for future extensions and must be empty. 
subsecond_precision 
The precision to interpret 
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.
A isoyearweekday calendar vector.
# Yearweek 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 yearmonthday is this? as_year_month_day(iso_days)
# Yearweek 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 yearmonthday is this? as_year_month_day(iso_days)
These are isoyearweekday methods for the arithmetic generics.
add_years()
You cannot add weeks or days to an isoyearweekday 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
isoyearweek object containing iso_year_week_day(2019, 53)
would be
undefined, as the 53rd ISO week of 2019 doesn't exist to begin with.
## S3 method for class 'clock_iso_year_week_day' add_years(x, n, ...)
## S3 method for class 'clock_iso_year_week_day' add_years(x, n, ...)
x 
A isoyearweekday vector. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
x
and n
are recycled against each other using
tidyverse recycling rules.
x
after performing the arithmetic.
x < iso_year_week_day(2019, 1, 1) add_years(x, 1:2)
x < iso_year_week_day(2019, 1, 1) add_years(x, 1:2)
This is an isoyearweekday method for the calendar_start()
and
calendar_end()
generics. They adjust components of a calendar to the
start or end of a specified precision
.
## 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)
## 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)
x 
A isoyearweekday vector. 
precision 
One of:

x
at the same precision, but with some components altered to be
at the boundary value.
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")
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")
This is an isoyearweekday 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).
## S3 method for class 'clock_iso_year_week_day' calendar_count_between(start, end, precision, ..., n = 1L)
## S3 method for class 'clock_iso_year_week_day' calendar_count_between(start, end, precision, ..., n = 1L)
start , end

A pair of isoyearweekday vectors. These will be recycled to their common size. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
An integer representing the number of precision
units between
start
and end
.
# 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")
# 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")
These are isoyearweekday 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 17 indicating the weekday of the
current ISO week, where 1 = Monday and 7 = Sunday, in line with the
ISO standard.
There are subdaily getters for extracting more precise components.
## 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)
## 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)
x 
A isoyearweekday to get the component from. 
The component.
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)
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)
This is a isoyearweekday method for the calendar_group()
generic.
Grouping for a isoyearweekday object can be done at any precision, as
long as x
is at least as precise as precision
.
## S3 method for class 'clock_iso_year_week_day' calendar_group(x, precision, ..., n = 1L)
## S3 method for class 'clock_iso_year_week_day' calendar_group(x, precision, ..., n = 1L)
x 
A isoyearweekday vector. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
x
grouped at the specified precision
.
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)
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)
This is a isoyearweekday method for the calendar_narrow()
generic. It
narrows a isoyearweekday vector to the specified precision
.
## S3 method for class 'clock_iso_year_week_day' calendar_narrow(x, precision)
## S3 method for class 'clock_iso_year_week_day' calendar_narrow(x, precision)
x 
A isoyearweekday vector. 
precision 
One of:

x
narrowed to the supplied precision
.
# Day precision x < iso_year_week_day(2019, 1, 5) x # Narrowed to week precision calendar_narrow(x, "week")
# Day precision x < iso_year_week_day(2019, 1, 5) x # Narrowed to week precision calendar_narrow(x, "week")
These are isoyearweekday 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 subdaily setters for setting more precise components.
## 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, ...)
## 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, ...)
x 
A isoyearweekday vector. 
value 
The value to set the component to. For 
... 
These dots are for future extensions and must be empty. 
x
with the component set.
# 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")
# 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")
This is a isoyearweekday method for the calendar_widen()
generic. It
widens a isoyearweekday vector to the specified precision
.
## S3 method for class 'clock_iso_year_week_day' calendar_widen(x, precision)
## S3 method for class 'clock_iso_year_week_day' calendar_widen(x, precision)
x 
A isoyearweekday vector. 
precision 
One of:

x
widened to the supplied precision
.
# 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
# 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
naive_time_info()
retrieves a set of lowlevel information generally not
required for most datetime manipulations. It is used implicitly
by as_zoned_time()
when converting from a naivetime.
It returns a data frame with the following columns:
type
: A character vector containing one of:
"unique"
: The naivetime maps uniquely to a zonedtime that can be
created with zone
.
"nonexistent"
: The naivetime does not exist as a zonedtime that can
be created with zone
.
"ambiguous"
: The naivetime exists twice as a zonedtime that can be
created with zone
.
first
: A sys_time_info()
data frame.
second
: A sys_time_info()
data frame.
first
will be filled out with sysinfo 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.
first
will be filled out with the sysinfo that ends just prior to x
.
second
will be filled out with the sysinfo that begins just after x
.
first
will be filled out with the sysinfo that ends just after x
.
second
will be filled out with the sysinfo that starts just before x
.
naive_time_info(x, zone)
naive_time_info(x, zone)
x 
A naivetime. 
zone 
A valid time zone name. Unlike most functions in clock, in 
If the tibble package is installed, it is recommended to convert the output
to a tibble with as_tibble()
, as that will print the dfcols much nicer.
A data frame of low level information.
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 naivetime 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 = "rollforward") as_zoned_time(info$first$end, zone) as_zoned_time(x, zone, nonexistent = "rollbackward") as_zoned_time(info$first$end  1, zone) as_zoned_time(x, zone, nonexistent = "shiftforward") as_zoned_time(as_sys_time(x)  info$first$offset, zone) as_zoned_time(x, zone, nonexistent = "shiftbackward") 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("20200105 02:30:00", "20200603 12:20:05"), zone = c("America/Los_Angeles", "Europe/London") ) # The times are assumed to be naivetimes, 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 datetimes at a time. So you'll need to # normalize these naivetimes. 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 naivetimes with no # chance of them ever being nonexistent or ambiguous. So now all we have # to do is use the offset to convert the naivetime to a systime. 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")
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 naivetime 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 = "rollforward") as_zoned_time(info$first$end, zone) as_zoned_time(x, zone, nonexistent = "rollbackward") as_zoned_time(info$first$end  1, zone) as_zoned_time(x, zone, nonexistent = "shiftforward") as_zoned_time(as_sys_time(x)  info$first$offset, zone) as_zoned_time(x, zone, nonexistent = "shiftbackward") 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("20200105 02:30:00", "20200603 12:20:05"), zone = c("America/Los_Angeles", "Europe/London") ) # The times are assumed to be naivetimes, 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 datetimes at a time. So you'll need to # normalize these naivetimes. 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 naivetimes with no # chance of them ever being nonexistent or ambiguous. So now all we have # to do is use the offset to convert the naivetime to a systime. 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")
naive_time_parse()
is a parser into a naivetime.
naive_time_parse()
is useful when you have datetime strings like
"20200101T01:04:30"
. If there is no attached UTC offset or time zone
name, then parsing this string as a naivetime is your best option. If
you know that this string should be interpreted in a specific time zone,
parse as a naivetime, 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 naivetime.
naive_time_parse()
ignores both the %z
and %Z
commands.
If your datetime 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 datetime strings contain a UTC offset, but not a full time zone
name, use sys_time_parse()
.
naive_time_parse( x, ..., format = NULL, precision = "second", locale = clock_locale() )
naive_time_parse( x, ..., format = NULL, precision = "second", locale = clock_locale() )
x 
A character vector to parse. 
... 
These dots are for future extensions and must be empty. 
format 
A format string. A combination of the following commands, or A vector of multiple format strings can be supplied. They will be tried in the order they are provided. Year
Month
Day
Day of the week
ISO 8601 weekbased year
Week of the year
Day of the year
Date
Time of day
Time zone
Miscellaneous

precision 
A precision for the resulting time point. One of:
Setting the 
locale 
A locale object created from 
A naivetime.
It is highly recommended to parse all of the information in the datetime
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
subsecond 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.
naive_time_parse("20200101T05:06:07") # Day precision naive_time_parse("20200101", precision = "day") # Nanosecond precision, but using a day based format naive_time_parse("20200101", format = "%Y%m%d", precision = "nanosecond") # Remember that the `%z` and `%Z` commands are ignored entirely! naive_time_parse( "20200101 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("20200101T00:00:00.123", "20200101T00: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")
naive_time_parse("20200101T05:06:07") # Day precision naive_time_parse("20200101", precision = "day") # Nanosecond precision, but using a day based format naive_time_parse("20200101", format = "%Y%m%d", precision = "nanosecond") # Remember that the `%z` and `%Z` commands are ignored entirely! naive_time_parse( "20200101 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("20200101T00:00:00.123", "20200101T00: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")
These are POSIXct/POSIXlt methods for the arithmetic generics.
Calendrical based arithmetic:
These functions convert to a naivetime, then to a yearmonthday, perform the arithmetic, then convert back to a datetime.
add_years()
add_quarters()
add_months()
Naivetime based arithmetic:
These functions convert to a naivetime, perform the arithmetic, then convert back to a datetime.
add_weeks()
add_days()
Systime based arithmetic:
These functions convert to a systime, perform the arithmetic, then convert back to a datetime.
add_hours()
add_minutes()
add_seconds()
## 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, ...)
## 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, ...)
x 
A datetime vector. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
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).
Naivetime 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).
Systime 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 naivetime
or a systime. For example, when adding months, you probably want to
retain the printed time when converting to a yearmonthday to perform
the arithmetic, so the conversion goes through naivetime. However,
when adding smaller units like seconds, you probably want
"20200308 01:59:59" + 1 second
in the America/New_York time zone to
return "20200308 03:00:00"
, taking into account the fact that there
was a daylight saving time gap. This requires doing the arithmetic in
systime, 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
naivetime instead of a systime manually with as_naive_time()
, add
1 second giving "20200308 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()
.
x
after performing the arithmetic.
For the most part, adding time based units to datetimes 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 = "rollforward" / "rollbackward"
ensures that this holds
when invalid and nonexistent issues are encountered.
That said, with datetimes there is an edge case related to ambiguous times where the relative ordering could change. Consider these three datetimes:
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] "20120401 02:30:00 AEDT" "20120401 02:00:00 AEST" #> [3] "20120401 02:30:00 AEST"
In this case, there was a daylight saving time fallback on 20120401
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 systime based units like hours, minutes, or seconds, then the relative ordering of these datetimes will be preserved. However, arithmetic that goes through naivetime, like adding days or months, won't preserve the ordering here:
add_days(x, 1) #> [1] "20120402 02:30:00 AEST" "20120402 02:00:00 AEST" #> [3] "20120402 02:30:00 AEST" add_months(x, 1) #> [1] "20120501 02:30:00 AEST" "20120501 02:00:00 AEST" #> [3] "20120501 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 naivetime generally does make more sense than adding it in systime, but it does come with this one edge case to be aware of when working with datetimes (this does not affect dates). If this has the potential to be an issue, consider only adding systime based units (hours, minutes, and seconds) which can't have these issues.
x < as.POSIXct("20190101", tz = "America/New_York") add_years(x, 1:5) y < as.POSIXct("20190131 00:30:00", tz = "America/New_York") # Adding 1 month to `y` generates an invalid date. Unlike yearmonthday # types, R's native datetime 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 datetime 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 `"previousday"` to set the # datetime to the previous valid day, while keeping the time of day. add_months(y, 1:2, invalid = "previous") add_months(y, 1:2, invalid = "previousday")
x < as.POSIXct("20190101", tz = "America/New_York") add_years(x, 1:5) y < as.POSIXct("20190131 00:30:00", tz = "America/New_York") # Adding 1 month to `y` generates an invalid date. Unlike yearmonthday # types, R's native datetime 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 datetime 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 `"previousday"` to set the # datetime to the previous valid day, while keeping the time of day. add_months(y, 1:2, invalid = "previous") add_months(y, 1:2, invalid = "previousday")
This is a POSIXct/POSIXlt method for the date_start()
and date_end()
generics.
## 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)
## 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)
x 
A datetime vector. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
x
but with some components altered to be at the boundary value.
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")
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")
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 datetime 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 yearmonthday calendar and count while in that type.
"year"
"quarter"
"month"
Naivetime based counting:
These precisions convert to a naivetime and count while in that type.
"week"
"day"
Systime based counting:
These precisions convert to a systime and count while in that type.
"hour"
"minute"
"second"
## S3 method for class 'POSIXt' date_count_between(start, end, precision, ..., n = 1L)
## S3 method for class 'POSIXt' date_count_between(start, end, precision, ..., n = 1L)
start , end

A pair of datetime vectors. These will be recycled to their common size. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
"quarter"
is equivalent to "month"
precision with n
set to n * 3L
.
An integer representing the number of precision
units between
start
and end
.
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.
start < date_time_parse("20000505 02:00:00", zone = "America/New_York") end < date_time_parse( c("20200505 01:00:00", "20200505 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. # `20000505 02:00:00 > 20200405 02:00:00` is 239 months # `20000505 02:00:00 > 20200505 02:00:00` is 240 months # Since `20200505 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") #  # Naivetime VS Systime interpretation # The difference between whether `start` and `end` are converted to a # naivetime vs a systime 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 systimes, 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 naivetimes, `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 systimes, 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 systime, 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")
start < date_time_parse("20000505 02:00:00", zone = "America/New_York") end < date_time_parse( c("20200505 01:00:00", "20200505 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. # `20000505 02:00:00 > 20200405 02:00:00` is 239 months # `20000505 02:00:00 > 20200505 02:00:00` is 240 months # Since `20200505 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") #  # Naivetime VS Systime interpretation # The difference between whether `start` and `end` are converted to a # naivetime vs a systime 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 systimes, 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 naivetimes, `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 systimes, 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 systime, 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")
This is a POSIXct method for the date_format()
generic.
date_format()
formats a datetime (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 defacto standard extension to
RFC 3339 for creating completely unambiguous datetimes.
## S3 method for class 'POSIXt' date_format( x, ..., format = NULL, locale = clock_locale(), abbreviate_zone = FALSE )
## S3 method for class 'POSIXt' date_format( x, ..., format = NULL, locale = clock_locale(), abbreviate_zone = FALSE )
x 
A datetime vector. 
... 
These dots are for future extensions and must be empty. 
format 
If Otherwise, a format string which is a combination of: Year
Month
Day
Day of the week
ISO 8601 weekbased year
Week of the year
Day of the year
Date
Time of day
Time zone
Miscellaneous

locale 
A locale object created from 
abbreviate_zone 
If If 
A character vector of the formatted input.
x < date_time_parse( c("19700426 01:30:00", "19700426 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)
x < date_time_parse( c("19700426 01:30:00", "19700426 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)
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 subdaily getters for extracting more precise components, up to a precision of seconds.
For more advanced component extraction, convert to the calendar type that you are interested in.
## S3 method for class 'POSIXt' get_year(x) ## S3 method for class 'POSIXt' get_month(x) ## S3 method for class 'POSIXt' get_day(x) ## S3 method for class 'POSIXt' get_hour(x) ## S3 method for class 'POSIXt' get_minute(x) ## S3 method for class 'POSIXt' get_second(x)
## S3 method for class 'POSIXt' get_year(x) ## S3 method for class 'POSIXt' get_month(x) ## S3 method for class 'POSIXt' get_day(x) ## S3 method for class 'POSIXt' get_hour(x) ## S3 method for class 'POSIXt' get_minute(x) ## S3 method for class 'POSIXt' get_second(x)
x 
A datetime type to get the component from. 
The component.
x < as.POSIXct("20190101", tz = "America/New_York") x < add_days(x, 0:5) x < set_second(x, 10:15) get_day(x) get_second(x)
x < as.POSIXct("20190101", tz = "America/New_York") x < add_days(x, 0:5) x < set_second(x, 10:15) get_day(x) get_second(x)
This is a POSIXct/POSIXlt method for the date_group()
generic.
date_group()
groups by a single component of a datetime, such as month
of the year, day of the month, or hour of the day.
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.
## S3 method for class 'POSIXt' date_group( x, precision, ..., n = 1L, invalid = NULL, nonexistent = NULL, ambiguous = x )
## S3 method for class 'POSIXt' date_group( x, precision, ..., n = 1L, invalid = NULL, nonexistent = NULL, ambiguous = x )
x 
A datetime vector. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
x
, grouped at precision
.
x < as.POSIXct("20190101", "America/New_York") x < add_days(x, 3:5) # 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") # Group by hour of the day y < as.POSIXct("20191230", "America/New_York") y < add_hours(y, 0:12) y date_group(y, "hour", n = 3)
x < as.POSIXct("20190101", "America/New_York") x < add_days(x, 3:5) # 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") # Group by hour of the day y < as.POSIXct("20191230", "America/New_York") y < add_hours(y, 0:12) y date_group(y, "hour", n = 3)
These are POSIXct/POSIXlt methods for the rounding generics.
date_floor()
rounds a datetime down to a multiple of
the specified precision
.
date_ceiling()
rounds a datetime up to a multiple of
the specified precision
.
date_round()
rounds up or down depending on what is closer,
rounding up on ties.
You can group by irregular periods such as "month"
or "year"
by using
date_group()
.
## S3 method for class 'POSIXt' date_floor( x, precision, ..., n = 1L, origin = NULL, nonexistent = NULL, ambiguous = x ) ## S3 method for class 'POSIXt' date_ceiling( x, precision, ..., n = 1L, origin = NULL, nonexistent = NULL, ambiguous = x ) ## S3 method for class 'POSIXt' date_round( x, precision, ..., n = 1L, origin = NULL, nonexistent = NULL, ambiguous = x )
## S3 method for class 'POSIXt' date_floor( x, precision, ..., n = 1L, origin = NULL, nonexistent = NULL, ambiguous = x ) ## S3 method for class 'POSIXt' date_ceiling( x, precision, ..., n = 1L, origin = NULL, nonexistent = NULL, ambiguous = x ) ## S3 method for class 'POSIXt' date_round( x, precision, ..., n = 1L, origin = NULL, nonexistent = NULL, ambiguous = x )
x 
A datetime vector. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
origin 
An origin to start counting from.
If 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
When rounding by "week"
, remember that the origin
determines the "week
start". By default, 19700101 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.
x
rounded to the specified precision
.
x < as.POSIXct("20190331", "America/New_York") x < add_days(x, 0:5) # 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) # Note that daylight saving time gaps can throw off rounding x < as.POSIXct("19700426 01:59:59", "America/New_York") + c(0, 1) x # Rounding is done in naivetime, which means that rounding by 2 hours # will attempt to generate a time of 19700426 02:00:00, which doesn't # exist in this time zone try(date_floor(x, "hour", n = 2)) # You can handle this by specifying a nonexistent time resolution strategy date_floor(x, "hour", n = 2, nonexistent = "rollforward")
x < as.POSIXct("20190331", "America/New_York") x < add_days(x, 0:5) # 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) # Note that daylight saving time gaps can throw off rounding x < as.POSIXct("19700426 01:59:59", "America/New_York") + c(0, 1) x # Rounding is done in naivetime, which means that rounding by 2 hours # will attempt to generate a time of 19700426 02:00:00, which doesn't # exist in this time zone try(date_floor(x, "hour", n = 2)) # You can handle this by specifying a nonexistent time resolution strategy date_floor(x, "hour", n = 2, nonexistent = "rollforward")
This is a POSIXct method for the date_seq()
generic.
date_seq()
generates a datetime (POSIXct) sequence.
When calling date_seq()
, exactly two of the following must be specified:
to
by
total_size
## S3 method for class 'POSIXt' date_seq( from, ..., to = NULL, by = NULL, total_size = NULL, invalid = NULL, nonexistent = NULL, ambiguous = NULL )
## S3 method for class 'POSIXt' date_seq( from, ..., to = NULL, by = NULL, total_size = NULL, invalid = NULL, nonexistent = NULL, ambiguous = NULL )
from 
A datetime to start the sequence from. 
... 
These dots are for future extensions and must be empty. 
to 
A datetime to stop the sequence at.
If The time zone of 
by 
The unit to increment the sequence by. If If

total_size 
The size of the resulting sequence. If specified alongside 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
A datetime vector.
Different methods are used to generate the sequences, depending on the
precision implied by by
. They are intended to generate the most intuitive
sequences, especially around daylight saving time gaps and fallbacks.
See the examples for more details.
These convert to a naivetime, then to a yearmonthday, generate the sequence, then convert back to a datetime.
by = duration_years()
by = duration_quarters()
by = duration_months()
These convert to a naivetime, generate the sequence, then convert back to a datetime.
by = duration_weeks()
by = duration_days()
These convert to a systime, generate the sequence, then convert back to a datetime.
by = duration_hours()
by = duration_minutes()
by = duration_seconds()
zone < "America/New_York" from < date_time_build(2019, 1, zone = zone) to < date_time_build(2019, 1, second = 50, zone = zone) # Defaults to second precision sequence date_seq(from, to = to, by = 7) to < date_time_build(2019, 1, 5, zone = zone) # Use durations to change to alternative precisions date_seq(from, to = to, by = duration_days(1)) date_seq(from, to = to, by = duration_hours(10)) date_seq(from, by = duration_minutes(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_time_build(2019, 1, 1, 0, 1, 30, zone = zone) to < date_time_build(2019, 1, 1, 5, 2, 20, zone = zone) try(date_seq(from, to = to, by = duration_hours(1))) # The minute and second components of `to` must match `from` to < date_time_build(2019, 1, 1, 5, 1, 30, zone = zone) date_seq(from, to = to, by = duration_hours(1)) #  # Invalid dates must be resolved with the `invalid` argument from < date_time_build(2019, 1, 31, zone = zone) to < date_time_build(2019, 12, 31, zone = zone) try(date_seq(from, to = to, by = duration_months(1))) date_seq(from, to = to, by = duration_months(1), invalid = "previousday") # 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") #  # This datetime is 2 days before a daylight saving time gap that occurred # on 20210314 between 01:59:59 > 03:00:00 from < as.POSIXct("20210312 02:30:00", "America/New_York") # So creating a daily sequence lands us in that daylight saving time gap, # creating a nonexistent time try(date_seq(from, by = duration_days(1), total_size = 5)) # Resolve the nonexistent time with `nonexistent`. Note that this importantly # allows times after the gap to retain the `02:30:00` time. date_seq(from, by = duration_days(1), total_size = 5, nonexistent = "rollforward") # Compare this to the base R behavior, where the hour is adjusted from 2>3 # as you cross the daylight saving time gap, and is never restored. This is # equivalent to always using systime (rather than naivetime, like clock # uses for daily sequences). seq(from, by = "1 day", length.out = 5) # You can replicate this behavior by generating a second precision sequence # of 86,400 seconds. Seconds always add in systime. date_seq(from, by = duration_seconds(86400), total_size = 5) #  # Usage of `to` and `total_size` must generate a nonfractional sequence # between `from` and `to` from < date_time_build(2019, 1, 1, 0, 0, 0, zone = "America/New_York") to < date_time_build(2019, 1, 1, 0, 0, 3, zone = "America/New_York") # 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))
zone < "America/New_York" from < date_time_build(2019, 1, zone = zone) to < date_time_build(2019, 1, second = 50, zone = zone) # Defaults to second precision sequence date_seq(from, to = to, by = 7) to < date_time_build(2019, 1, 5, zone = zone) # Use durations to change to alternative precisions date_seq(from, to = to, by = duration_days(1)) date_seq(from, to = to, by = duration_hours(10)) date_seq(from, by = duration_minutes(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_time_build(2019, 1, 1, 0, 1, 30, zone = zone) to < date_time_build(2019, 1, 1, 5, 2, 20, zone = zone) try(date_seq(from, to = to, by = duration_hours(1))) # The minute and second components of `to` must match `from` to < date_time_build(2019, 1, 1, 5, 1, 30, zone = zone) date_seq(from, to = to, by = duration_hours(1)) #  # Invalid dates must be resolved with the `invalid` argument from < date_time_build(2019, 1, 31, zone = zone) to < date_time_build(2019, 12, 31, zone = zone) try(date_seq(from, to = to, by = duration_months(1))) date_seq(from, to = to, by = duration_months(1), invalid = "previousday") # 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") #  # This datetime is 2 days before a daylight saving time gap that occurred # on 20210314 between 01:59:59 > 03:00:00 from < as.POSIXct("20210312 02:30:00", "America/New_York") # So creating a daily sequence lands us in that daylight saving time gap, # creating a nonexistent time try(date_seq(from, by = duration_days(1), total_size = 5)) # Resolve the nonexistent time with `nonexistent`. Note that this importantly # allows times after the gap to retain the `02:30:00` time. date_seq(from, by = duration_days(1), total_size = 5, nonexistent = "rollforward") # Compare this to the base R behavior, where the hour is adjusted from 2>3 # as you cross the daylight saving time gap, and is never restored. This is # equivalent to always using systime (rather than naivetime, like clock # uses for daily sequences). seq(from, by = "1 day", length.out = 5) # You can replicate this behavior by generating a second precision sequence # of 86,400 seconds. Seconds always add in systime. date_seq(from, by = duration_seconds(86400), total_size = 5) #  # Usage of `to` and `total_size` must generate a nonfractional sequence # between `from` and `to` from < date_time_build(2019, 1, 1, 0, 0, 0, zone = "America/New_York") to < date_time_build(2019, 1, 1, 0, 0, 3, zone = "America/New_York") # 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))
These are POSIXct/POSIXlt 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]
.
There are subdaily setters for setting more precise components, up to a precision of seconds.
## S3 method for class 'POSIXt' set_year(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x) ## S3 method for class 'POSIXt' set_month(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x) ## S3 method for class 'POSIXt' set_day(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x) ## S3 method for class 'POSIXt' set_hour(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x) ## S3 method for class 'POSIXt' set_minute(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x) ## S3 method for class 'POSIXt' set_second(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt' set_year(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x) ## S3 method for class 'POSIXt' set_month(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x) ## S3 method for class 'POSIXt' set_day(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x) ## S3 method for class 'POSIXt' set_hour(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x) ## S3 method for class 'POSIXt' set_minute(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x) ## S3 method for class 'POSIXt' set_second(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
x 
A datetime vector. 
value 
The value to set the component to. For 
... 
These dots are for future extensions and must be empty. 
invalid 
One of the following invalid date resolution strategies:
Using either If If 
nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
x
with the component set.
x < as.POSIXct("20190201", tz = "America/New_York") # Set the day set_day(x, 12:14) # Set to the "last" day of the month set_day(x, "last") # You cannot set a datetime to an invalid date like you can with # a yearmonthday. 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") y < as.POSIXct("20200308 01:30:00", tz = "America/New_York") # Nonexistent and ambiguous times must be resolved immediately when # working with R's native datetime types. An error is thrown by default. try(set_hour(y, 2)) set_hour(y, 2, nonexistent = "rollforward") set_hour(y, 2, nonexistent = "rollbackward")
x < as.POSIXct("20190201", tz = "America/New_York") # Set the day set_day(x, 12:14) # Set to the "last" day of the month set_day(x, "last") # You cannot set a datetime to an invalid date like you can with # a yearmonthday. 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") y < as.POSIXct("20200308 01:30:00", tz = "America/New_York") # Nonexistent and ambiguous times must be resolved immediately when # working with R's native datetime types. An error is thrown by default. try(set_hour(y, 2)) set_hour(y, 2, nonexistent = "rollforward") set_hour(y, 2, nonexistent = "rollbackward")
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
.
Shifting with datetimes retains the time of day where possible. Be aware that you can run into daylight saving time issues if you shift into a daylight saving time gap or fallback period.
## S3 method for class 'POSIXt' date_shift( x, target, ..., which = "next", boundary = "keep", nonexistent = NULL, ambiguous = x )
## S3 method for class 'POSIXt' date_shift( x, target, ..., which = "next", boundary = "keep", nonexistent = NULL, ambiguous = x )
x 
A datetime vector. 
target 
A weekday created from Generally this is length 1, but can also be the same length as 
... 
These dots are for future extensions and must be empty. 
which 
One of:

boundary 
One of:

nonexistent 
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If 
ambiguous 
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If 
x
shifted to the target
weekday.
tuesday < weekday(clock_weekdays$tuesday) x < as.POSIXct("19700422 02:30:00", "America/New_York") # Shift to the next Tuesday date_shift(x, tuesday) # Be aware that you can run into daylight saving time issues! # Here we shift directly into a daylight saving time gap # from 01:59:59 > 03:00:00 sunday < weekday(clock_weekdays$sunday) try(date_shift(x, sunday)) # You can resolve this with the `nonexistent` argument date_shift(x, sunday, nonexistent = "rollforward")
tuesday < weekday(clock_weekdays$tuesday) x < as.POSIXct("19700422 02:30:00", "America/New_York") # Shift to the next Tuesday date_shift(x, tuesday) # Be aware that you can run into daylight saving time issues! # Here we shift directly into a daylight saving time gap # from 01:59:59 > 03:00:00 sunday < weekday(clock_weekdays$sunday) try(date_shift(x, sunday)) # You can resolve this with the `nonexistent` argument date_shift(x, sunday, nonexistent = "rollforward")
This is a duration method for the seq()
generic.
Using seq()
on duration objects always retains the type of from
.
When calling seq()
, exactly two of the following must be specified:
to
by
Either length.out
or along.with
## S3 method for class 'clock_duration' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S3 method for class 'clock_duration' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from 
A duration to start the sequence from. 
to 
A duration to stop the sequence at.

by 
The unit to increment the sequence by. If If 
length.out 
The length of the resulting sequence. If specified, 
along.with 
A vector who's length determines the length of the resulting sequence. Equivalent to If specified, 
... 
These dots are for future extensions and must be empty. 
If from > to
and by > 0
, then the result will be length 0. This matches
the behavior of rlang::seq2()
, and results in nicer theoretical
properties when compared with throwing an error. Similarly, if from < to
and by < 0
, then the result will also be length 0.
A sequence with the type of from
.
seq(duration_days(0), duration_days(100), by = 5) # Using a duration `by`. Note that `by` is cast to the type of `from`. seq(duration_days(0), duration_days(100), by = duration_weeks(1)) # `to` is cast from 5 years to 60 months # `by` is cast from 1 quarter to 4 months seq(duration_months(0), duration_years(5), by = duration_quarters(1)) seq(duration_days(20), by = 2, length.out = 5)
seq(duration_days(0), duration_days(100), by = 5) # Using a duration `by`. Note that `by` is cast to the type of `from`. seq(duration_days(0), duration_days(100), by = duration_weeks(1)) # `to` is cast from 5 years to 60 months # `by` is cast from 1 quarter to 4 months seq(duration_months(0), duration_years(5), by = duration_quarters(1)) seq(duration_days(20), by = 2, length.out = 5)
This is a isoyearweekday method for the seq()
generic.
Sequences can only be generated for "year"
precision
isoyearweekday vectors. If you need to generate weekbased sequences,
you'll have to convert to a time point first.
When calling seq()
, exactly two of the following must be specified:
to
by
Either length.out
or along.with
## S3 method for class 'clock_iso_year_week_day' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S3 method for class 'clock_iso_year_week_day' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from 
A

to 
A

by 
The unit to increment the sequence by. If If 
length.out 
The length of the resulting sequence. If specified, 
along.with 
A vector who's length determines the length of the resulting sequence. Equivalent to If specified, 
... 
These dots are for future extensions and must be empty. 
A sequence with the type of from
.
# Yearly sequence x < seq(iso_year_week_day(2020), iso_year_week_day(2026), by = 2) x # Which we can then set the week of. # Some years have 53 ISO weeks, some have 52. set_week(x, "last")
# Yearly sequence x < seq(iso_year_week_day(2020), iso_year_week_day(2026), by = 2) x # Which we can then set the week of. # Some years have 53 ISO weeks, some have 52. set_week(x, "last")
This is a time point method for the seq()
generic. It works for systime
and naivetime vectors.
Sequences can be generated for all valid time point precisions (daily through nanosecond).
When calling seq()
, exactly two of the following must be specified:
to
by
Either length.out
or along.with
## S3 method for class 'clock_time_point' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S3 method for class 'clock_time_point' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from 
A time point to start the sequence from.

to 
A time point to stop the sequence at.

by 
The unit to increment the sequence by. If If 
length.out 
The length of the resulting sequence. If specified, 
along.with 
A vector who's length determines the length of the resulting sequence. Equivalent to If specified, 
... 
These dots are for future extensions and must be empty. 
A sequence with the type of from
.
# Daily sequence seq( as_naive_time(year_month_day(2019, 1, 1)), as_naive_time(year_month_day(2019, 2, 4)), by = 5 ) # Minutely sequence using minute precision naivetime x < as_naive_time(year_month_day(2019, 1, 2, 3, 3)) x seq(x, by = 4, length.out = 10) # You can use larger step sizes by using a durationbased `by` seq(x, by = duration_days(1), length.out = 5) # Nanosecond sequence from < as_naive_time(year_month_day(2019, 1, 1)) from < time_point_cast(from, "nanosecond") to < from + 100 seq(from, to, by = 10)
# Daily sequence seq( as_naive_time(year_month_day(2019, 1, 1)), as_naive_time(year_month_day(2019, 2, 4)), by = 5 ) # Minutely sequence using minute precision naivetime x < as_naive_time(year_month_day(2019, 1, 2, 3, 3)) x seq(x, by = 4, length.out = 10) # You can use larger step sizes by using a durationbased `by` seq(x, by = duration_days(1), length.out = 5) # Nanosecond sequence from < as_naive_time(year_month_day(2019, 1, 1)) from < time_point_cast(from, "nanosecond") to < from + 100 seq(from, to, by = 10)
This is a yearday method for the seq()
generic.
Sequences can only be generated for "year"
precision yearday vectors.
When calling seq()
, exactly two of the following must be specified:
to
by
Either length.out
or along.with
## S3 method for class 'clock_year_day' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S3 method for class 'clock_year_day' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from 
A

to 
A

by 
The unit to increment the sequence by. If If 
length.out 
The length of the resulting sequence. If specified, 
along.with 
A vector who's length determines the length of the resulting sequence. Equivalent to If specified, 
... 
These dots are for future extensions and must be empty. 
A sequence with the type of from
.
# Yearly sequence x < seq(year_day(2020), year_day(2040), by = 2) x # Which we can then set the day of to get a sequence of endofyear values set_day(x, "last") # Daily sequences are not allowed. Use a naivetime for this instead. try(seq(year_day(2019, 1), by = 2, length.out = 2)) as_year_day(seq(as_naive_time(year_day(2019, 1)), by = 2, length.out = 2))
# Yearly sequence x < seq(year_day(2020), year_day(2040), by = 2) x # Which we can then set the day of to get a sequence of endofyear values set_day(x, "last") # Daily sequences are not allowed. Use a naivetime for this instead. try(seq(year_day(2019, 1), by = 2, length.out = 2)) as_year_day(seq(as_naive_time(year_day(2019, 1)), by = 2, length.out = 2))
This is a yearmonthday method for the seq()
generic.
Sequences can only be generated for "year"
and "month"
precision
yearmonthday vectors.
When calling seq()
, exactly two of the following must be specified:
to
by
Either length.out
or along.with
## S3 method for class 'clock_year_month_day' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S3 method for class 'clock_year_month_day' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from 
A

to 
A

by 
The unit to increment the sequence by. If If 
length.out 
The length of the resulting sequence. If specified, 
along.with 
A vector who's length determines the length of the resulting sequence. Equivalent to If specified, 
... 
These dots are for future extensions and must be empty. 
A sequence with the type of from
.
# Monthly sequence x < seq(year_month_day(2019, 1), year_month_day(2020, 12), by = 1) x # Which we can then set the day of to get a sequence of endofmonth values set_day(x, "last") # Daily sequences are not allowed. Use a naivetime for this instead. try(seq(year_month_day(2019, 1, 1), by = 2, length.out = 2)) seq(as_naive_time(year_month_day(2019, 1, 1)), by = 2, length.out = 2)
# Monthly sequence x < seq(year_month_day(2019, 1), year_month_day(2020, 12), by = 1) x # Which we can then set the day of to get a sequence of endofmonth values set_day(x, "last") # Daily sequences are not allowed. Use a naivetime for this instead. try(seq(year_month_day(2019, 1, 1), by = 2, length.out = 2)) seq(as_naive_time(year_month_day(2019, 1, 1)), by = 2, length.out = 2)
This is a yearmonthweekday method for the seq()
generic.
Sequences can only be generated for "year"
and "month"
precision
yearmonthweekday vectors.
When calling seq()
, exactly two of the following must be specified:
to
by
Either length.out
or along.with
## S3 method for class 'clock_year_month_weekday' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S3 method for class 'clock_year_month_weekday' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from 
A

to 
A

by 
The unit to increment the sequence by. If If 
length.out 
The length of the resulting sequence. If specified, 
along.with 
A vector who's length determines the length of the resulting sequence. Equivalent to If specified, 
... 
These dots are for future extensions and must be empty. 
A sequence with the type of from
.
# Monthly sequence x < seq(year_month_weekday(2019, 1), year_month_weekday(2020, 12), by = 1) x # Which we can then set the indexed weekday of set_day(x, clock_weekdays$sunday, index = "last")
# Monthly sequence x < seq(year_month_weekday(2019, 1), year_month_weekday(2020, 12), by = 1) x # Which we can then set the indexed weekday of set_day(x, clock_weekdays$sunday, index = "last")
This is a yearquarterday method for the seq()
generic.
Sequences can only be generated for "year"
and "quarter"
precision
yearquarterday vectors.
When calling seq()
, exactly two of the following must be specified:
to
by
Either length.out
or along.with
## S3 method for class 'clock_year_quarter_day' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S3 method for class 'clock_year_quarter_day' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from 
A

to 
A

by 
The unit to increment the sequence by. If If 
length.out 
The length of the resulting sequence. If specified, 
along.with 
A vector who's length determines the length of the resulting sequence. Equivalent to If specified, 
... 
These dots are for future extensions and must be empty. 
A sequence with the type of from
.
# Quarterly sequence x < seq(year_quarter_day(2020, 1), year_quarter_day(2026, 3), by = 2) x # Which we can then set the day of the quarter of set_day(x, "last")
# Quarterly sequence x < seq(year_quarter_day(2020, 1), year_quarter_day(2026, 3), by = 2) x # Which we can then set the day of the quarter of set_day(x, "last")
This is a yearweekday method for the seq()
generic.
Sequences can only be generated for "year"
precision
yearweekday vectors. If you need to generate weekbased sequences,
you'll have to convert to a time point first.
When calling seq()
, exactly two of the following must be specified:
to
by
Either length.out
or along.with
## S3 method for class 'clock_year_week_day' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S3 method for class 'clock_year_week_day' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from 
A

to 
A

by 
The unit to increment the sequence by. If If 
length.out 
The length of the resulting sequence. If specified, 
along.with 
A vector who's length determines the length of the resulting sequence. Equivalent to If specified, 
... 
These dots are for future extensions and must be empty. 
A sequence with the type of from
.
# Yearly sequence x < seq(year_week_day(2020), year_week_day(2026), by = 2) x # Which we can then set the week of. # Some years have 53 weeks, some have 52. set_week(x, "last")
# Yearly sequence x < seq(year_week_day(2020), year_week_day(2026), by = 2) x # Which we can then set the week of. # Some years have 53 weeks, some have 52. set_week(x, "last")
sys_time_info()
retrieves a set of lowlevel information generally not
required for most datetime manipulations. It returns a data frame with the
following columns:
begin
, end
: Second precision systimes specifying the range of the
current daylight saving time rule. The range is a halfopen interval of
[begin, end)
.
offset
: A second precision duration
specifying the offset from UTC.
dst
: A logical vector specifying if daylight saving time is currently
active.
abbreviation
: The time zone abbreviation in use throughout this begin
to end
range.
sys_time_info(x, zone)
sys_time_info(x, zone)
x 
A systime. 
zone 
A valid time zone name. Unlike most functions in clock, in 
If there have never been any daylight saving time transitions, the minimum
supported year value is returned for begin
(typically, a year value of
32767
).
If daylight saving time is no longer used in a time zone, the maximum
supported year value is returned for end
(typically, a year value of
32767
).
The offset
is the bridge between systime and naivetime for the zone
being used. The relationship of the three values is:
offset = naive_time  sys_time
A data frame of low level information.
library(vctrs) x < year_month_day(2021, 03, 14, c(01, 03), c(59, 00), c(59, 00)) x < as_naive_time(x) x < as_zoned_time(x, "America/New_York") # x[1] is in EST, x[2] is in EDT x x_sys < as_sys_time(x) info < sys_time_info(x_sys, zoned_time_zone(x)) info # Convert `begin` and `end` to zonedtimes to see the previous and # next daylight saving time transitions data_frame( x = x, begin = as_zoned_time(info$begin, zoned_time_zone(x)), end = as_zoned_time(info$end, zoned_time_zone(x)) ) # `end` can be used to iterate through daylight saving time transitions # by repeatedly calling `sys_time_info()` sys_time_info(info$end, zoned_time_zone(x)) # Multiple `zone`s can be supplied to look up daylight saving time # information in different time zones zones < c("America/New_York", "America/Los_Angeles") info2 < sys_time_info(x_sys[1], zones) info2 # The offset can be used to display the naivetime (i.e. the printed time) # in both of those time zones data_frame( zone = zones, naive_time = x_sys[1] + info2$offset )
library(vctrs) x < year_month_day(2021, 03, 14, c(01, 03), c(59, 00), c(59, 00)) x < as_naive_time(x) x < as_zoned_time(x, "America/New_York") # x[1] is in EST, x[2] is in EDT x x_sys < as_sys_time(x) info < sys_time_info(x_sys, zoned_time_zone(x)) info # Convert `begin` and `end` to zonedtimes to see the previous and # next daylight saving time transitions data_frame( x = x, begin = as_zoned_time(info$begin, zoned_time_zone(x)), end = as_zoned_time(info$end, zoned_time_zone(x)) ) # `end` can be used to iterate through daylight saving time transitions # by repeatedly calling `sys_time_info()` sys_time_info(info$end, zoned_time_zone(x)) # Multiple `zone`s can be supplied to look up daylight saving time # information in different time zones zones < c("America/New_York", "America/Los_Angeles") info2 < sys_time_info(x_sys[1], zones) info2 # The offset can be used to display the naivetime (i.e. the printed time) # in both of those time zones data_frame( zone = zones, naive_time = x_sys[1] + info2$offset )
sys_time_now()
returns the current time in UTC.
sys_time_now()
sys_time_now()
The time is returned with a nanosecond precision, but the actual amount of data returned is OS dependent. Usually, information at at least the microsecond level is returned, with some platforms returning nanosecond information.
A systime of the current time in UTC.
x < sys_time_now()
x < sys_time_now()
There are two parsers into a systime, sys_time_parse()
and
sys_time_parse_RFC_3339()
.
sys_time_parse()
is useful when you have datetime strings like
"20200101T01:04:30"
that you know should be interpreted as UTC, or like
"20200101T01:04:3004:00"
with a UTC offset but no zone name. If you find
yourself in the latter situation, then parsing this string as a systime
using the %Ez
command to capture the offset is probably your best option.
If you know that this string should be interpreted in a specific time zone,
parse as a systime to get the UTC equivalent, 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 systime.
sys_time_parse()
is nearly equivalent to naive_time_parse()
, except for
the fact that the %z
command is actually used. Using %z
assumes that the
rest of the datetime string should be interpreted as a naivetime, which is
then shifted by the UTC offset found in %z
. The returned time can then be
validly interpreted as UTC.
sys_time_parse()
ignores the %Z
command.
sys_time_parse_RFC_3339()
is a wrapper around sys_time_parse()
that is
intended to parse the extremely common datetime format outlined by
RFC 3339. This document
outlines a profile of the ISO 8601 format that is even more restrictive.
In particular, this function is intended to parse the following three formats:
20190101T00:00:00Z 20190101T00:00:00+0430 20190101T00: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 datetime 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.
For this function, the precision
must be at least "second"
.
sys_time_parse( x, ..., format = NULL, precision = "second", locale = clock_locale() ) sys_time_parse_RFC_3339( x, ..., separator = "T", offset = "Z", precision = "second" )
sys_time_parse( x, ..., format = NULL, precision = "second", locale = clock_locale() ) sys_time_parse_RFC_3339( x, ..., separator = "T", offset = "Z", precision = "second" )
x 
A character vector to parse. 
... 
These dots are for future extensions and must be empty. 
format 
A format string. A combination of the following commands, or A vector of multiple format strings can be supplied. They will be tried in the order they are provided. Year
Month
Day
Day of the week
ISO 8601 weekbased year
Week of the year
Day of the year
Date
Time of day
Time zone
Miscellaneous

precision 
A precision for the resulting time point. One of:
Setting the 
locale 
A locale object created from 
separator 
The separator between the date and time components of the string. One of:

offset 
The format of the offset from UTC contained in the string. One of:

If your datetime 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 datetime strings don't contain an offset from UTC and you aren't
sure if they should be treated as UTC or not, you might consider using
naive_time_parse()
, since the resulting naivetime doesn't come with an
assumption of a UTC time zone.
A systime.
It is highly recommended to parse all of the information in the datetime
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
subsecond 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.
sys_time_parse("20200101T05:06:07") # Day precision sys_time_parse("20200101", precision = "day") # Nanosecond precision, but using a day based format sys_time_parse("20200101", format = "%Y%m%d", precision = "nanosecond") # Multiple format strings are allowed for heterogeneous times sys_time_parse( c("20190101", "2019/1/1"), format = c("%Y/%m/%d", "%Y%m%d"), precision = "day" ) # The `%z` command shifts the datetime by subtracting the UTC offset so # that the returned systime can be interpreted as UTC sys_time_parse( "20200101 02:00:00 0400", format = "%Y%m%d %H:%M:%S %z" ) # Remember that the `%Z` command is ignored entirely! sys_time_parse("20200101 America/New_York", format = "%Y%m%d %Z") #  # RFC 3339 # Typical UTC format x < "20190101T00:01:02Z" sys_time_parse_RFC_3339(x) # With a UTC offset containing a `:` x < "20190101T00:01:02+02:30" sys_time_parse_RFC_3339(x, offset = "%Ez") # With a space between the date and time and no `:` in the offset x < "20190101 00:01:02+0230" sys_time_parse_RFC_3339(x, separator = " ", offset = "%z")
sys_time_parse("20200101T05:06:07") # Day precision sys_time_parse("20200101", precision = "day") # Nanosecond precision, but using a day based format sys_time_parse("20200101", format = "%Y%m%d", precision = "nanosecond") # Multiple format strings are allowed for heterogeneous times sys_time_parse( c("20190101", "2019/1/1"), format = c("%Y/%m/%d", "%Y%m%d"), precision = "day" ) # The `%z` command shifts the datetime by subtracting the UTC offset so # that the returned systime can be interpreted as UTC sys_time_parse( "20200101 02:00:00 0400", format = "%Y%m%d %H:%M:%S %z" ) # Remember that the `%Z` command is ignored entirely! sys_time_parse("20200101 America/New_York", format = "%Y%m%d %Z") #  # RFC 3339 # Typical UTC format x < "20190101T00:01:02Z" sys_time_parse_RFC_3339(x) # With a UTC offset containing a `:` x < "20190101T00:01:02+02:30" sys_time_parse_RFC_3339(x, offset = "%Ez") # With a space between the date and time and no `:` in the offset x < "20190101 00:01:02+0230" sys_time_parse_RFC_3339(x, separator = " ", offset = "%z")
Casting is one way to change a time point'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. When converting time points
to a less precise precision, you often want time_point_floor()
instead
of time_point_cast()
, as that handles pre1970 dates (which are
stored as negative durations) in a more intuitive manner.
Casting to a more precise precision is done through a multiplication by a conversion factor between the current precision and the new precision.
time_point_cast(x, precision)
time_point_cast(x, precision)
x 
A systime or naivetime. 
precision 
A time point precision. One of:

x
cast to the new precision
.
# Hour precision time points # One is pre1970, one is post1970 x < duration_hours(c(25, 25)) x < as_naive_time(x) x # Casting rounds the underlying duration towards 0 cast < time_point_cast(x, "day") cast # Flooring rounds the underlying duration towards negative infinity, # which is often more intuitive for time points. # Note that the cast ends up rounding the pre1970 date up to the next # day, while the post1970 date is rounded down. floor < time_point_floor(x, "day") floor # Casting to a more precise precision, hour>millisecond time_point_cast(x, "millisecond")
# Hour precision time points # One is pre1970, one is post1970 x < duration_hours(c(25, 25)) x < as_naive_time(x) x # Casting rounds the underlying duration towards 0 cast < time_point_cast(x, "day") cast # Flooring rounds the underlying duration towards negative infinity, # which is often more intuitive for time points. # Note that the cast ends up rounding the pre1970 date up to the next # day, while the post1970 date is rounded down. floor < time_point_floor(x, "day") floor # Casting to a more precise precision, hour>millisecond time_point_cast(x, "millisecond")
time_point_count_between()
counts the number of precision
units
between start
and end
(i.e., the number of days 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 days between two time points, accounting for the time of day.
time_point_count_between(start, end, precision, ..., n = 1L)
time_point_count_between(start, end, precision, ..., n = 1L)
start , end

A pair of time points. These will be recycled to their common size. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
Remember that time_point_count_between()
returns an integer vector.
With extremely fine precisions, such as nanoseconds, the count can quickly
exceed the maximum value that is allowed in an integer. In this case, an
NA
will be returned with a warning.
An integer representing the number of precision
units between
start
and end
.
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.
x < as_naive_time(year_month_day(2019, 2, 3)) y < as_naive_time(year_month_day(2019, 2, 10)) # Whole number of days or hours between two time points time_point_count_between(x, y, "day") time_point_count_between(x, y, "hour") # Whole number of 2day units time_point_count_between(x, y, "day", n = 2) # Leap years are taken into account x < as_naive_time(year_month_day(c(2020, 2021), 2, 28)) y < as_naive_time(year_month_day(c(2020, 2021), 3, 01)) time_point_count_between(x, y, "day") # Time of day is taken into account. # `20200202T04 > 20200203T03` is not a whole day (because of the hour) # `20200202T04 > 20200203T05` is a whole day x < as_naive_time(year_month_day(2020, 2, 2, 4)) y < as_naive_time(year_month_day(2020, 2, 3, c(3, 5))) time_point_count_between(x, y, "day") time_point_count_between(x, y, "hour") # Can compute negative counts (using the same example from above) time_point_count_between(y, x, "day") time_point_count_between(y, x, "hour") # Repeated computation at increasingly fine precisions x < as_naive_time(year_month_day( 2020, 2, 2, 4, 5, 6, 200, subsecond_precision = "microsecond" )) y < as_naive_time(year_month_day( 2020, 3, 1, 8, 9, 10, 100, subsecond_precision = "microsecond" )) days < time_point_count_between(x, y, "day") x < x + duration_days(days) hours < time_point_count_between(x, y, "hour") x < x + duration_hours(hours) minutes < time_point_count_between(x, y, "minute") x < x + duration_minutes(minutes) seconds < time_point_count_between(x, y, "second") x < x + duration_seconds(seconds) microseconds < time_point_count_between(x, y, "microsecond") x < x + duration_microseconds(microseconds) data.frame( days = days, hours = hours, minutes = minutes, seconds = seconds, microseconds = microseconds )
x < as_naive_time(year_month_day(2019, 2, 3)) y < as_naive_time(year_month_day(2019, 2, 10)) # Whole number of days or hours between two time points time_point_count_between(x, y, "day") time_point_count_between(x, y, "hour") # Whole number of 2day units time_point_count_between(x, y, "day", n = 2) # Leap years are taken into account x < as_naive_time(year_month_day(c(2020, 2021), 2, 28)) y < as_naive_time(year_month_day(c(2020, 2021), 3, 01)) time_point_count_between(x, y, "day") # Time of day is taken into account. # `20200202T04 > 20200203T03` is not a whole day (because of the hour) # `20200202T04 > 20200203T05` is a whole day x < as_naive_time(year_month_day(2020, 2, 2, 4)) y < as_naive_time(year_month_day(2020, 2, 3, c(3, 5))) time_point_count_between(x, y, "day") time_point_count_between(x, y, "hour") # Can compute negative counts (using the same example from above) time_point_count_between(y, x, "day") time_point_count_between(y, x, "hour") # Repeated computation at increasingly fine precisions x < as_naive_time(year_month_day( 2020, 2, 2, 4, 5, 6, 200, subsecond_precision = "microsecond" )) y < as_naive_time(year_month_day( 2020, 3, 1, 8, 9, 10, 100, subsecond_precision = "microsecond" )) days < time_point_count_between(x, y, "day") x < x + duration_days(days) hours < time_point_count_between(x, y, "hour") x < x + duration_hours(hours) minutes < time_point_count_between(x, y, "minute") x < x + duration_minutes(minutes) seconds < time_point_count_between(x, y, "second") x < x + duration_seconds(seconds) microseconds < time_point_count_between(x, y, "microsecond") x < x + duration_microseconds(microseconds) data.frame( days = days, hours = hours, minutes = minutes, seconds = seconds, microseconds = microseconds )
time_point_precision()
extracts the precision from a time point, such
as a systime or naivetime. It returns the precision as a single string.
time_point_precision(x)
time_point_precision(x)
x 
A time point. 
A single string holding the precision of the time point.
time_point_precision(sys_time_now()) time_point_precision(as_naive_time(duration_days(1)))
time_point_precision(sys_time_now()) time_point_precision(as_naive_time(duration_days(1)))
time_point_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 time_point_floor()
, but
this is slightly easier.
time_point_shift(x, target, ..., which = "next", boundary = "keep")
time_point_shift(x, target, ..., which = "next", boundary = "keep")
x 
A time point. 
target 
A weekday created from Generally this is length 1, but can also be the same length as 
... 
These dots are for future extensions and must be empty. 
which 
One of:

boundary 
One of:

x
shifted to the target
weekday.
x < as_naive_time(year_month_day(2019, 1, 1:2)) # A Tuesday and Wednesday as_weekday(x) monday < weekday(clock_weekdays$monday) # Shift to the next Monday time_point_shift(x, monday) # Shift to the previous Monday # This is an easy way to "floor by week" with a target weekday in mind time_point_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 time_point_shift(x, tuesday) # You can force it to `"advance"` time_point_shift(x, tuesday, boundary = "advance")
x < as_naive_time(year_month_day(2019, 1, 1:2)) # A Tuesday and Wednesday as_weekday(x) monday < weekday(clock_weekdays$monday) # Shift to the next Monday time_point_shift(x, monday) # Shift to the previous Monday # This is an easy way to "floor by week" with a target weekday in mind time_point_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 time_point_shift(x, tuesday) # You can force it to `"advance"` time_point_shift(x, tuesday, boundary = "advance")
time_point_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
.
time_point_spanning_seq(x)
time_point_spanning_seq(x)
x 
A time point vector. 
Missing values are automatically removed before the sequence is generated.
If you need more precise sequence generation, call range()
and seq()
directly.
A sequence along [min(x), max(x)]
.
x < as_naive_time(year_month_day(2019, c(1, 2, 1, 2), c(15, 4, 12, 2))) x time_point_spanning_seq(x) # The sequence is generated at the precision of `x` x < as_naive_time(c( year_month_day(2019, 1, 1, 5), year_month_day(2019, 1, 2, 10), year_month_day(2019, 1, 1, 3) )) time_point_spanning_seq(x)
x < as_naive_time(year_month_day(2019, c(1, 2, 1, 2), c(15, 4, 12, 2))) x time_point_spanning_seq(x) # The sequence is generated at the precision of `x` x < as_naive_time(c( year_month_day(2019, 1, 1, 5), year_month_day(2019, 1, 2, 10), year_month_day(2019, 1, 1, 3) )) time_point_spanning_seq(x)
These are naivetime and systime methods for the arithmetic generics.
add_weeks()
add_days()
add_hours()
add_minutes()
add_seconds()
add_milliseconds()
add_microseconds()
add_nanoseconds()
When working with zoned times, generally you convert to either systime or naivetime, add the duration, then convert back to zoned time. Typically, weeks and days are added in naivetime, and hours, minutes, seconds, and subseconds are added in systime.
If you aren't using zoned times, arithmetic on systimes and naivetime is equivalent.
If you need to add larger irregular units of time, such as months, quarters,
or years, convert to a calendar type with a converter like
as_year_month_day()
.
## S3 method for class 'clock_time_point' add_weeks(x, n, ...) ## S3 method for class 'clock_time_point' add_days(x, n, ...) ## S3 method for class 'clock_time_point' add_hours(x, n, ...) ## S3 method for class 'clock_time_point' add_minutes(x, n, ...) ## S3 method for class 'clock_time_point' add_seconds(x, n, ...) ## S3 method for class 'clock_time_point' add_milliseconds(x, n, ...) ## S3 method for class 'clock_time_point' add_microseconds(x, n, ...) ## S3 method for class 'clock_time_point' add_nanoseconds(x, n, ...)
## S3 method for class 'clock_time_point' add_weeks(x, n, ...) ## S3 method for class 'clock_time_point' add_days(x, n, ...) ## S3 method for class 'clock_time_point' add_hours(x, n, ...) ## S3 method for class 'clock_time_point' add_minutes(x, n, ...) ## S3 method for class 'clock_time_point' add_seconds(x, n, ...) ## S3 method for class 'clock_time_point' add_milliseconds(x, n, ...) ## S3 method for class 'clock_time_point' add_microseconds(x, n, ...) ## S3 method for class 'clock_time_point' add_nanoseconds(x, n, ...)
x 
A time point vector. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
x
and n
are recycled against each other using
tidyverse recycling rules.
x
after performing the arithmetic.
library(magrittr) # Say you started with this zoned time, and you want to add 1 day to it x < as_naive_time(year_month_day(1970, 04, 25, 02, 30, 00)) x < as_zoned_time(x, "America/New_York") x # Note that there was a daylight saving time gap on 19700426 where # we jumped from 01:59:59 > 03:00:00. # You can choose to add 1 day in "system time", by first converting to # systime (the equivalent UTC time), adding the day, then converting back to # zoned time. If you sat still for exactly 86,400 seconds, this is the # time that you would see after daylight saving time adjusted the clock # (note that the hour field is shifted forward by the size of the gap) as_sys_time(x) x %>% as_sys_time() %>% add_days(1) %>% as_zoned_time(zoned_time_zone(x)) # Alternatively, you can add 1 day in "naive time". Naive time represents # a clock time with a yettobespecified time zone. It tries to maintain # smaller units where possible, so adding 1 day would attempt to return # "19700426T02:30:00" in the America/New_York time zone, but... as_naive_time(x) try({ x %>% as_naive_time() %>% add_days(1) %>% as_zoned_time(zoned_time_zone(x)) }) # ...this time doesn't exist in that time zone! It is "nonexistent". # You can resolve nonexistent times by setting the `nonexistent` argument # when converting to zoned time. Let's roll forward to the next available # moment in time. x %>% as_naive_time() %>% add_days(1) %>% as_zoned_time(zoned_time_zone(x), nonexistent = "rollforward")
library(magrittr) # Say you started with this zoned time, and you want to add 1 day to it x < as_naive_time(year_month_day(1970, 04, 25, 02, 30, 00)) x < as_zoned_time(x, "America/New_York") x # Note that there was a daylight saving time gap on 19700426 where # we jumped from 01:59:59 > 03:00:00. # You can choose to add 1 day in "system time", by first converting to # systime (the equivalent UTC time), adding the day, then converting back to # zoned time. If you sat still for exactly 86,400 seconds, this is the # time that you would see after daylight saving time adjusted the clock # (note that the hour field is shifted forward by the size of the gap) as_sys_time(x) x %>% as_sys_time() %>% add_days(1) %>% as_zoned_time(zoned_time_zone(x)) # Alternatively, you can add 1 day in "naive time". Naive time represents # a clock time with a yettobespecified time zone. It tries to maintain # smaller units where possible, so adding 1 day would attempt to return # "19700426T02:30:00" in the America/New_York time zone, but... as_naive_time(x) try({ x %>% as_naive_time() %>% add_days(1) %>% as_zoned_time(zoned_time_zone(x)) }) # ...this time doesn't exist in that time zone! It is "nonexistent". # You can resolve nonexistent times by setting the `nonexistent` argument # when converting to zoned time. Let's roll forward to the next available # moment in time. x %>% as_naive_time() %>% add_days(1) %>% as_zoned_time(zoned_time_zone(x), nonexistent = "rollforward")
time_point_floor()
rounds a systime or naivetime down to a multiple of
the specified precision
.
time_point_ceiling()
rounds a systime or naivetime up to a multiple of
the specified precision
.
time_point_round()
rounds up or down depending on what is closer,
rounding up on ties.
Rounding time points is mainly useful for rounding subdaily time points up to daily time points.
It can also be useful for flooring by a set number of days (like 20) with respect to some origin. By default, the origin is 19700101 00:00:00.
If you want to group by components, such as "day of the month", rather than
by "n days", see calendar_group()
.
time_point_floor(x, precision, ..., n = 1L, origin = NULL) time_point_ceiling(x, precision, ..., n = 1L, origin = NULL) time_point_round(x, precision, ..., n = 1L, origin = NULL)
time_point_floor(x, precision, ..., n = 1L, origin = NULL) time_point_ceiling(x, precision, ..., n = 1L, origin = NULL) time_point_round(x, precision, ..., n = 1L, origin = NULL)
x 
A systime or naivetime. 
precision 
A time point precision. One of:

... 
These dots are for future extensions and must be empty. 
n 
A positive integer specifying the multiple of 
origin 
An origin to begin counting from. Mostly useful when If If The precision of If 
x
rounded to the new precision
.
To understand how flooring and ceiling work, you need to know how they create their intervals for rounding.
time_point_floor()
constructs intervals of [lower, upper)
that
bound each element of x
, then always chooses the lefthand side.
time_point_ceiling()
constructs intervals of (lower, upper]
that
bound each element of x
, then always chooses the righthand side.
As an easy example, consider 20200102 00:00:05.
To floor this to the nearest day, the following interval is constructed, and the lefthand side is returned at day precision:
[20200102 00:00:00, 20200103 00:00:00)
To ceiling this to the nearest day, the following interval is constructed, and the righthand side is returned at day precision:
(20200102 00:00:00, 20200103 00:00:00]
Here is another example, this time with a time point on a boundary, 20200102 00:00:00.
To floor this to the nearest day, the following interval is constructed, and the lefthand side is returned at day precision:
[20200102 00:00:00, 20200103 00:00:00)
To ceiling this to the nearest day, the following interval is constructed, and the righthand side is returned at day precision:
(20200101 00:00:00, 20200102 00:00:00]
Notice that, regardless of whether you are doing a floor or ceiling, if the input falls on a boundary then it will be returned as is.
library(magrittr) x < as_naive_time(year_month_day(2019, 01, 01)) x < add_days(x, 0:40) head(x) # Floor by sets of 20 days # The implicit origin to start the 20 day counter is 19700101 time_point_floor(x, "day", n = 20) # You can easily customize the origin by supplying a new one # as the `origin` argument origin < year_month_day(2019, 01, 01) %>% as_naive_time() time_point_floor(x, "day", n = 20, origin = origin) # For times on the boundary, floor and ceiling both return the input # at the new precision. Notice how the first element is on the boundary, # and the second is 1 second after the boundary. y < as_naive_time(year_month_day(2020, 01, 02, 00, 00, c(00, 01))) time_point_floor(y, "day") time_point_ceiling(y, "day")
library(magrittr) x < as_naive_time(year_month_day(2019, 01, 01)) x < add_days(x, 0:40) head(x) # Floor by sets of 20 days # The implicit origin to start the 20 day counter is 19700101 time_point_floor(x, "day", n = 20) # You can easily customize the origin by supplying a new one # as the `origin` argument origin < year_month_day(2019, 01, 01) %>% as_naive_time() time_point_floor(x, "day", n = 20, origin = origin) # For times on the boundary, floor and ceiling both return the input # at the new precision. Notice how the first element is on the boundary, # and the second is 1 second after the boundary. y < as_naive_time(year_month_day(2020, 01, 02, 00, 00, c(00, 01))) time_point_floor(y, "day") time_point_ceiling(y, "day")
Support for vctrs arithmetic
## S3 method for class 'clock_year_day' vec_arith(op, x, y, ...) ## S3 method for class 'clock_year_month_day' vec_arith(op, x, y, ...) ## S3 method for class 'clock_year_month_weekday' vec_arith(op, x, y, ...) ## S3 method for class 'clock_iso_year_week_day' vec_arith(op, x, y, ...) ## S3 method for class 'clock_naive_time' vec_arith(op, x, y, ...) ## S3 method for class 'clock_year_quarter_day' vec_arith(op, x, y, ...) ## S3 method for class 'clock_sys_time' vec_arith(op, x, y, ...) ## S3 method for class 'clock_year_week_day' vec_arith(op, x, y, ...) ## S3 method for class 'clock_weekday' vec_arith(op, x, y, ...)
## S3 method for class 'clock_year_day' vec_arith(op, x, y, ...) ## S3 method for class 'clock_year_month_day' vec_arith(op, x, y, ...) ## S3 method for class 'clock_year_month_weekday' vec_arith(op, x, y, ...) ## S3 method for class 'clock_iso_year_week_day' vec_arith(op, x, y, ...) ## S3 method for class 'clock_naive_time' vec_arith(op, x, y, ...) ## S3 method for class 'clock_year_quarter_day' vec_arith(op, x, y, ...) ## S3 method for class 'clock_sys_time' vec_arith(op, x, y, ...) ## S3 method for class 'clock_year_week_day' vec_arith(op, x, y, ...) ## S3 method for class 'clock_weekday' vec_arith(op, x, y, ...)
op 
An arithmetic operator as a string 
x , y

A pair of vectors. For 
... 
These dots are for future extensions and must be empty. 
The result of the arithmetic operation.
vctrs::vec_arith("+", year_month_day(2019), 1)
vctrs::vec_arith("+", year_month_day(2019), 1)
A weekday
is a simple type that represents a day of the week.
The most interesting thing about the weekday type is that it implements circular arithmetic, which makes determining the "next Monday" or "previous Tuesday" from a systime or naivetime easy to compute. See the examples.
weekday(code = integer(), ..., encoding = "western")
weekday(code = integer(), ..., encoding = "western")
code 
Integer codes between 
... 
These dots are for future extensions and must be empty. 
encoding 
One of:

A weekday vector.
x < as_naive_time(year_month_day(2019, 01, 05)) # This is a Saturday! as_weekday(x) # Adjust to the next Wednesday wednesday < weekday(clock_weekdays$wednesday) # This returns the number of days until the next Wednesday using # circular arithmetic # "Wednesday  Saturday = 4 days until next Wednesday" wednesday  as_weekday(x) # Advance to the next Wednesday x_next_wednesday < x + (wednesday  as_weekday(x)) as_weekday(x_next_wednesday) # What about the previous Tuesday? tuesday < weekday(clock_weekdays$tuesday) x  (as_weekday(x)  tuesday) # What about the next Saturday? # With an additional condition that if today is a Saturday, # then advance to the next one. saturday < weekday(clock_weekdays$saturday) x + 1L + (saturday  as_weekday(x + 1L)) # You can supply an ISO coding for `code` as well, where 1 == Monday. weekday(1:7, encoding = "western") weekday(1:7, encoding = "iso")
x < as_naive_time(year_month_day(2019, 01, 05)) # This is a Saturday! as_weekday(x) # Adjust to the next Wednesday wednesday < weekday(clock_weekdays$wednesday) # This returns the number of days until the next Wednesday using # circular arithmetic # "Wednesday  Saturday = 4 days until next Wednesday" wednesday  as_weekday(x) # Advance to the next Wednesday x_next_wednesday < x + (wednesday  as_weekday(x)) as_weekday(x_next_wednesday) # What about the previous Tuesday? tuesday < weekday(clock_weekdays$tuesday) x  (as_weekday(x)  tuesday) # What about the next Saturday? # With an additional condition that if today is a Saturday, # then advance to the next one. saturday < weekday(clock_weekdays$saturday) x + 1L + (saturday  as_weekday(x + 1L)) # You can supply an ISO coding for `code` as well, where 1 == Monday. weekday(1:7, encoding = "western") weekday(1:7, encoding = "iso")
weekday_code()
extracts out the integer code for the weekday.
weekday_code(x, ..., encoding = "western")
weekday_code(x, ..., encoding = "western")
x 
A weekday vector. 
... 
These dots are for future extensions and must be empty. 
encoding 
One of:

An integer vector of codes.
# Here we supply a western encoding to `weekday()` x < weekday(1:7) x # We can extract out the codes using different encodings weekday_code(x, encoding = "western") weekday_code(x, encoding = "iso")
# Here we supply a western encoding to `weekday()` x < weekday(1:7) x # We can extract out the codes using different encodings weekday_code(x, encoding = "western") weekday_code(x, encoding = "iso")
weekday_factor()
converts a weekday object to an ordered factor. This
can be useful in combination with ggplot2, or for modeling.
weekday_factor(x, ..., labels = "en", abbreviate = TRUE, encoding = "western")
weekday_factor(x, ..., labels = "en", abbreviate = TRUE, encoding = "western")
x 
A weekday vector. 
... 
These dots are for future extensions and must be empty. 
labels 
Character representations of localized weekday names, month names, and
AM/PM names. Either the language code as string (passed on to

abbreviate 
If If 
encoding 
One of:

An ordered factor representing the weekdays.
x < weekday(1:7) # Default to Sunday > Saturday weekday_factor(x) # ISO encoding is Monday > Sunday weekday_factor(x, encoding = "iso") # With full names weekday_factor(x, abbreviate = FALSE) # Or a different language weekday_factor(x, labels = "fr")
x < weekday(1:7) # Default to Sunday > Saturday weekday_factor(x) # ISO encoding is Monday > Sunday weekday_factor(x, encoding = "iso") # With full names weekday_factor(x, abbreviate = FALSE) # Or a different language weekday_factor(x, labels = "fr")
These are weekday methods for the arithmetic generics.
add_days()
Also check out the examples on the weekday()
page for more advanced
usage.
## S3 method for class 'clock_weekday' add_days(x, n, ...)
## S3 method for class 'clock_weekday' add_days(x, n, ...)
x 
A weekday vector. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
x
and n
are recycled against each other using
tidyverse recycling rules.
x
after performing the arithmetic.
saturday < weekday(clock_weekdays$saturday) saturday add_days(saturday, 1) add_days(saturday, 2)
saturday < weekday(clock_weekdays$saturday) saturday add_days(saturday, 1) add_days(saturday, 2)
year_day()
constructs a calendar vector from the Gregorian
year and day of the year.
year_day( year, day = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., subsecond_precision = NULL )
year_day( year, day = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., subsecond_precision = NULL )
year 
The year. Values 
day 
The day of the year. Values 
hour 
The hour. Values 
minute 
The minute. Values 
second 
The second. Values 
subsecond 
The subsecond. If specified, If using milliseconds, values If using microseconds, values If using nanoseconds, values 
... 
These dots are for future extensions and must be empty. 
subsecond_precision 
The precision to interpret 
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.
A yearday calendar vector.
# Just the year x < year_day(2019:2025) x year_day(2020, 1:10) # Last day of the year, accounting for leap years year_day(2019:2021, "last") # Precision can go all the way out to nanosecond year_day(2019, 100, 2, 40, 45, 200, subsecond_precision = "nanosecond")
# Just the year x < year_day(2019:2025) x year_day(2020, 1:10) # Last day of the year, accounting for leap years year_day(2019:2021, "last") # Precision can go all the way out to nanosecond year_day(2019, 100, 2, 40, 45, 200, subsecond_precision = "nanosecond")
year_month_day()
constructs the most common calendar type using the
Gregorian year, month, day, and time of day components.
year_month_day( year, month = NULL, day = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., subsecond_precision = NULL )
year_month_day( year, month = NULL, day = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., subsecond_precision = NULL )
year 
The year. Values 
month 
The month. Values 
day 
The day of the month. Values If 
hour 
The hour. Values 
minute 
The minute. Values 
second 
The second. Values 
subsecond 
The subsecond. If specified, If using milliseconds, values If using microseconds, values If using nanoseconds, values 
... 
These dots are for future extensions and must be empty. 
subsecond_precision 
The precision to interpret 
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.
A yearmonthday calendar vector.
# Just the year x < year_month_day(2019:2025) # Yearmonth type year_month_day(2020, 1:12) # The most common use case involves year, month, and day fields x < year_month_day(2020, clock_months$january, 1:5) x # Precision can go all the way out to nanosecond year_month_day(2019, 1, 2, 2, 40, 45, 200, subsecond_precision = "nanosecond")
# Just the year x < year_month_day(2019:2025) # Yearmonth type year_month_day(2020, 1:12) # The most common use case involves year, month, and day fields x < year_month_day(2020, clock_months$january, 1:5) x # Precision can go all the way out to nanosecond year_month_day(2019, 1, 2, 2, 40, 45, 200, subsecond_precision = "nanosecond")
year_month_day_parse()
parses strings into a yearmonthday.
The default options assume x
should be parsed at day precision, using a
format
string of "%Y%m%d"
.
If a more precise precision than day is used, then time components will also
be parsed. The default format separates date and time components by a "T"
and the time components by a ":"
. For example, setting the precision to
"second"
will use a default format of "%Y%m%dT%H:%M:%S"
. This is
aligned with the format()
method for yearmonthday, and with the RFC 3339
standard.
year_month_day_parse( x, ..., format = NULL, precision = "day", locale = clock_locale() )
year_month_day_parse( x, ..., format = NULL, precision = "day", locale = clock_locale() )
x 
A character vector to parse. 
... 
These dots are for future extensions and must be empty. 
format 
A format string. A combination of the following commands, or A vector of multiple format strings can be supplied. They will be tried in the order they are provided. Year
Month
Day
Day of the week
ISO 8601 weekbased year
Week of the year
Day of the year
Date
Time of day
Time zone
Miscellaneous

precision 
A precision for the resulting yearmonthday. One of:
Setting the 
locale 
A locale object created by 
year_month_day_parse()
completely ignores the %z
and %Z
commands.
A yearmonthday calendar vector. If a parsing fails, NA
is
returned.
It is highly recommended to parse all of the information in the datetime
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
subsecond 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.
x < "20190101" # Default parses at day precision year_month_day_parse(x) # Can parse at less precise precisions too year_month_day_parse(x, precision = "month") year_month_day_parse(x, precision = "year") # Even invalid dates can be roundtripped through format<>parse calls invalid < year_month_day(2019, 2, 30) year_month_day_parse(format(invalid)) # Can parse with time of day year_month_day_parse( "20190130T02:30:00.123456789", precision = "nanosecond" ) # Can parse using multiple format strings, which will be tried # in the order they are provided x < c("20190101", "20200101", "2021/2/3") formats < c("%Y%m%d", "%Y/%m/%d") year_month_day_parse(x, format = formats) # Can parse using other format tokens as well year_month_day_parse( "January, 2019", format = "%B, %Y", precision = "month" ) # Parsing a French yearmonthday year_month_day_parse( "octobre 1, 2000", format = "%B %d, %Y", locale = clock_locale("fr") )
x < "20190101" # Default parses at day precision year_month_day_parse(x) # Can parse at less precise precisions too year_month_day_parse(x, precision = "month") year_month_day_parse(x, precision = "year") # Even invalid dates can be roundtripped through format<>parse calls invalid < year_month_day(2019, 2, 30) year_month_day_parse(format(invalid)) # Can parse with time of day year_month_day_parse( "20190130T02:30:00.123456789", precision = "nanosecond" ) # Can parse using multiple format strings, which will be tried # in the order they are provided x < c("20190101", "20200101", "2021/2/3") formats < c("%Y%m%d", "%Y/%m/%d") year_month_day_parse(x, format = formats) # Can parse using other format tokens as well year_month_day_parse( "January, 2019", format = "%B, %Y", precision = "month" ) # Parsing a French yearmonthday year_month_day_parse( "octobre 1, 2000", format = "%B %d, %Y", locale = clock_locale("fr") )
year_month_weekday()
constructs a calendar vector from the Gregorian
year, month, weekday, and index specifying that this is the nth weekday
of the month.
year_month_weekday( year, month = NULL, day = NULL, index = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., subsecond_precision = NULL )
year_month_weekday( year, month = NULL, day = NULL, index = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., subsecond_precision = NULL )
year 
The year. Values 
month 
The month. Values 
day 
The weekday of the month. Values 
index 
The index specifying that If 
hour 
The hour. Values 
minute 
The minute. Values 
second 
The second. Values 
subsecond 
The subsecond. If specified, If using milliseconds, values If using microseconds, values If using nanoseconds, values 
... 
These dots are for future extensions and must be empty. 
subsecond_precision 
The precision to interpret 
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.
A yearmonthweekday calendar vector.
# All Fridays in January, 2019 # Note that there was no 5th Friday in January x < year_month_weekday( 2019, clock_months$january, clock_weekdays$friday, 1:5 ) x invalid_detect(x) # Resolve this invalid date by using the previous valid date invalid_resolve(x, invalid = "previous")
# All Fridays in January, 2019 # Note that there was no 5th Friday in January x < year_month_weekday( 2019, clock_months$january, clock_weekdays$friday, 1:5 ) x invalid_detect(x) # Resolve this invalid date by using the previous valid date invalid_resolve(x, invalid = "previous")
year_quarter_day()
constructs a calendar from the fiscal year, fiscal
quarter, and day of the quarter, along with a value determining which
month the fiscal year start
s in.
year_quarter_day( year, quarter = NULL, day = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., start = NULL, subsecond_precision = NULL )
year_quarter_day( year, quarter = NULL, day = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., start = NULL, subsecond_precision = NULL )
year 
The fiscal year. Values 
quarter 
The fiscal quarter. Values 
day 
The day of the quarter. Values If 
hour 
The hour. Values 
minute 
The minute. Values 
second 
The second. Values 
subsecond 
The subsecond. If specified, If using milliseconds, values If using microseconds, values If using nanoseconds, values 
... 
These dots are for future extensions and must be empty. 
start 
The month to start the fiscal year in. 1 = January and 12 = December. If 
subsecond_precision 
The precision to interpret 
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.
A yearquarterday calendar vector.
# Yearquarter type x < year_quarter_day(2019, 1:4) x add_quarters(x, 2) # Set the day to the last day of the quarter x < set_day(x, "last") x # Start the fiscal year in June june < 6L y < year_quarter_day(2019, 1:4, "last", start = june) # Compare the yearmonthday values that result from having different # fiscal year start months as_year_month_day(x) as_year_month_day(y)
# Yearquarter type x < year_quarter_day(2019, 1:4) x add_quarters(x, 2) # Set the day to the last day of the quarter x < set_day(x, "last") x # Start the fiscal year in June june < 6L y < year_quarter_day(2019, 1:4, "last", start = june) # Compare the yearmonthday values that result from having different # fiscal year start months as_year_month_day(x) as_year_month_day(y)
year_week_day()
constructs a calendar from the year, week number,
week day, and the start
of the week.
Using start = clock_weekdays$monday
represents the ISO week calendar and
is equivalent to using iso_year_week_day()
.
Using start = clock_weekdays$sunday
is how Epidemiologists encode their
weekbased data.
year_week_day( year, week = NULL, day = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., start = NULL, subsecond_precision = NULL )
year_week_day( year, week = NULL, day = NULL, hour = NULL, minute = NULL, second = NULL, subsecond = NULL, ..., start = NULL, subsecond_precision = NULL )
year 
The year. Values 
week 
The week. Values If 
day 
The day of the week. Values 
hour 
The hour. Values 
minute 
The minute. Values 
second 
The second. Values 
subsecond 
The subsecond. If specified, If using milliseconds, values If using microseconds, values If using nanoseconds, values 
... 
These dots are for future extensions and must be empty. 
start 
The day to consider the start of the week. 1 = Sunday and 7 = Saturday. Use clock_weekdays for a readable way to specify the start. If 
subsecond_precision 
The precision to interpret 
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.
A yearweekday calendar vector.
# Yearweek x < year_week_day(2019:2025, "last") x # Start the week on Monday y < year_week_day(2019:2025, "last", start = clock_weekdays$monday) y # Last days of the year as_year_month_day(set_day(x, 7)) as_year_month_day(set_day(y, 7))
# Yearweek x < year_week_day(2019:2025, "last") x # Start the week on Monday y < year_week_day(2019:2025, "last", start = clock_weekdays$monday) y # Last days of the year as_year_month_day(set_day(x, 7)) as_year_month_day(set_day(y, 7))
These are yearday methods for the arithmetic generics.
add_years()
Notably, you cannot add days to a yearday. For daybased arithmetic,
first convert to a time point with as_naive_time()
or as_sys_time()
.
## S3 method for class 'clock_year_day' add_years(x, n, ...)
## S3 method for class 'clock_year_day' add_years(x, n, ...)
x 
A yearday vector. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
x
and n
are recycled against each other using
tidyverse recycling rules.
x
after performing the arithmetic.
x < year_day(2019, 10) add_years(x, 1:5) # A valid day in a leap year y < year_day(2020, 366) y # Adding 1 year to `y` generates an invalid date y_plus < add_years(y, 1) y_plus # Invalid dates are fine, as long as they are eventually resolved # by either manually resolving, or by calling `invalid_resolve()` # Resolve by returning the previous / next valid moment in time invalid_resolve(y_plus, invalid = "previous") invalid_resolve(y_plus, invalid = "next") # Manually resolve by setting to the last day of the year invalid < invalid_detect(y_plus) y_plus[invalid] < set_day(y_plus[invalid], "last") y_plus
x < year_day(2019, 10) add_years(x, 1:5) # A valid day in a leap year y < year_day(2020, 366) y # Adding 1 year to `y` generates an invalid date y_plus < add_years(y, 1) y_plus # Invalid dates are fine, as long as they are eventually resolved # by either manually resolving, or by calling `invalid_resolve()` # Resolve by returning the previous / next valid moment in time invalid_resolve(y_plus, invalid = "previous") invalid_resolve(y_plus, invalid = "next") # Manually resolve by setting to the last day of the year invalid < invalid_detect(y_plus) y_plus[invalid] < set_day(y_plus[invalid], "last") y_plus
This is a yearday method for the calendar_start()
and
calendar_end()
generics. They adjust components of a calendar to the
start or end of a specified precision
.
## S3 method for class 'clock_year_day' calendar_start(x, precision) ## S3 method for class 'clock_year_day' calendar_end(x, precision)
## S3 method for class 'clock_year_day' calendar_start(x, precision) ## S3 method for class 'clock_year_day' calendar_end(x, precision)
x 
A yearday vector. 
precision 
One of:

x
at the same precision, but with some components altered to be
at the boundary value.
# Day precision x < year_day(2019:2020, 5) x # Compute the last day of the year calendar_end(x, "year")
# Day precision x < year_day(2019:2020, 5) x # Compute the last day of the year calendar_end(x, "year")
This is a yearday method for the calendar_count_between()
generic.
It counts the number of precision
units between start
and end
(i.e., the number of years).
## S3 method for class 'clock_year_day' calendar_count_between(start, end, precision, ..., n = 1L)
## S3 method for class 'clock_year_day' calendar_count_between(start, end, precision, ..., n = 1L)
start , end

A pair of yearday vectors. These will be recycled to their common size. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
An integer representing the number of precision
units between
start
and end
.
# Compute an individual's age in years x < year_day(2001, 100) y < year_day(2021, c(99, 101)) calendar_count_between(x, y, "year") # Or in a whole number multiple of years calendar_count_between(x, y, "year", n = 3)
# Compute an individual's age in years x < year_day(2001, 100) y < year_day(2021, c(99, 101)) calendar_count_between(x, y, "year") # Or in a whole number multiple of years calendar_count_between(x, y, "year", n = 3)
These are yearday methods for the getter generics.
get_year()
returns the Gregorian year.
get_day()
returns the day of the year.
There are subdaily getters for extracting more precise components.
## S3 method for class 'clock_year_day' get_year(x) ## S3 method for class 'clock_year_day' get_day(x) ## S3 method for class 'clock_year_day' get_hour(x) ## S3 method for class 'clock_year_day' get_minute(x) ## S3 method for class 'clock_year_day' get_second(x) ## S3 method for class 'clock_year_day' get_millisecond(x) ## S3 method for class 'clock_year_day' get_microsecond(x) ## S3 method for class 'clock_year_day' get_nanosecond(x)
## S3 method for class 'clock_year_day' get_year(x) ## S3 method for class 'clock_year_day' get_day(x) ## S3 method for class 'clock_year_day' get_hour(x) ## S3 method for class 'clock_year_day' get_minute(x) ## S3 method for class 'clock_year_day' get_second(x) ## S3 method for class 'clock_year_day' get_millisecond(x) ## S3 method for class 'clock_year_day' get_microsecond(x) ## S3 method for class 'clock_year_day' get_nanosecond(x)
x 
A yearday to get the component from. 
The component.
x < year_day(2019, 101:105, 1, 20, 30) get_day(x) get_second(x) # Cannot extract more precise components y < year_day(2019, 1) try(get_hour(y)) # Cannot extract components that don't exist for this calendar try(get_quarter(x))
x < year_day(2019, 101:105, 1, 20, 30) get_day(x) get_second(x) # Cannot extract more precise components y < year_day(2019, 1) try(get_hour(y)) # Cannot extract components that don't exist for this calendar try(get_quarter(x))
This is a yearday method for the calendar_group()
generic.
Grouping for a yearday object can be done at any precision, as
long as x
is at least as precise as precision
.
## S3 method for class 'clock_year_day' calendar_group(x, precision, ..., n = 1L)
## S3 method for class 'clock_year_day' calendar_group(x, precision, ..., n = 1L)
x 
A yearday vector. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
x
grouped at the specified precision
.
x < seq(as_naive_time(year_month_day(2019, 1, 1)), by = 5, length.out = 20) x < as_year_day(x) x # Group by day of the current year calendar_group(x, "day", n = 20)
x < seq(as_naive_time(year_month_day(2019, 1, 1)), by = 5, length.out = 20) x < as_year_day(x) x # Group by day of the current year calendar_group(x, "day", n = 20)
This is a yearday method for the calendar_narrow()
generic. It
narrows a yearday vector to the specified precision
.
## S3 method for class 'clock_year_day' calendar_narrow(x, precision)
## S3 method for class 'clock_year_day' calendar_narrow(x, precision)
x 
A yearday vector. 
precision 
One of:

x
narrowed to the supplied precision
.
# Hour precision x < year_day(2019, 3, 4) x # Narrowed to day precision calendar_narrow(x, "day") # Or year precision calendar_narrow(x, "year") # Subsecond precision can be narrowed to second precision milli < calendar_widen(x, "millisecond") micro < calendar_widen(x, "microsecond") milli micro calendar_narrow(milli, "second") calendar_narrow(micro, "second") # But once you have "locked in" a subsecond precision, it can't be # narrowed to another subsecond precision try(calendar_narrow(micro, "millisecond"))
# Hour precision x < year_day(2019, 3, 4) x # Narrowed to day precision calendar_narrow(x, "day") # Or year precision calendar_narrow(x, "year") # Subsecond precision can be narrowed to second precision milli < calendar_widen(x, "millisecond") micro < calendar_widen(x, "microsecond") milli micro calendar_narrow(milli, "second") calendar_narrow(micro, "second") # But once you have "locked in" a subsecond precision, it can't be # narrowed to another subsecond precision try(calendar_narrow(micro, "millisecond"))
These are yearday methods for the setter generics.
set_year()
sets the Gregorian year.
set_day()
sets the day of the year. Valid values are in the range
of [1, 366]
.
There are subdaily setters for setting more precise components.
## S3 method for class 'clock_year_day' set_year(x, value, ...) ## S3 method for class 'clock_year_day' set_day(x, value, ...) ## S3 method for class 'clock_year_day' set_hour(x, value, ...) ## S3 method for class 'clock_year_day' set_minute(x, value, ...) ## S3 method for class 'clock_year_day' set_second(x, value, ...) ## S3 method for class 'clock_year_day' set_millisecond(x, value, ...) ## S3 method for class 'clock_year_day' set_microsecond(x, value, ...) ## S3 method for class 'clock_year_day' set_nanosecond(x, value, ...)
## S3 method for class 'clock_year_day' set_year(x, value, ...) ## S3 method for class 'clock_year_day' set_day(x, value, ...) ## S3 method for class 'clock_year_day' set_hour(x, value, ...) ## S3 method for class 'clock_year_day' set_minute(x, value, ...) ## S3 method for class 'clock_year_day' set_second(x, value, ...) ## S3 method for class 'clock_year_day' set_millisecond(x, value, ...) ## S3 method for class 'clock_year_day' set_microsecond(x, value, ...) ## S3 method for class 'clock_year_day' set_nanosecond(x, value, ...)
x 
A yearday vector. 
value 
The value to set the component to. For 
... 
These dots are for future extensions and must be empty. 
x
with the component set.
x < year_day(2019) # Set the day set_day(x, 12:14) # Set to the "last" day of the year set_day(x, "last") # Set to an invalid day of the year invalid < set_day(x, 366) invalid # Then resolve the invalid day by choosing the next valid day invalid_resolve(invalid, invalid = "next") # Cannot set a component two levels more precise than where you currently are try(set_hour(x, 5))
x < year_day(2019) # Set the day set_day(x, 12:14) # Set to the "last" day of the year set_day(x, "last") # Set to an invalid day of the year invalid < set_day(x, 366) invalid # Then resolve the invalid day by choosing the next valid day invalid_resolve(invalid, invalid = "next") # Cannot set a component two levels more precise than where you currently are try(set_hour(x, 5))
This is a yearday method for the calendar_widen()
generic. It
widens a yearday vector to the specified precision
.
## S3 method for class 'clock_year_day' calendar_widen(x, precision)
## S3 method for class 'clock_year_day' calendar_widen(x, precision)
x 
A yearday vector. 
precision 
One of:

x
widened to the supplied precision
.
# Year precision x < year_day(2019) x # Widen to day precision calendar_widen(x, "day") # Or second precision sec < calendar_widen(x, "second") sec # Second precision can be widened to subsecond precision milli < calendar_widen(sec, "millisecond") micro < calendar_widen(sec, "microsecond") milli micro # But once you have "locked in" a subsecond precision, it can't # be widened again try(calendar_widen(milli, "microsecond"))
# Year precision x < year_day(2019) x # Widen to day precision calendar_widen(x, "day") # Or second precision sec < calendar_widen(x, "second") sec # Second precision can be widened to subsecond precision milli < calendar_widen(sec, "millisecond") micro < calendar_widen(sec, "microsecond") milli micro # But once you have "locked in" a subsecond precision, it can't # be widened again try(calendar_widen(milli, "microsecond"))
These are yearmonthday methods for the arithmetic generics.
add_years()
add_quarters()
add_months()
Notably, you cannot add days to a yearmonthday. For daybased arithmetic,
first convert to a time point with as_naive_time()
or as_sys_time()
.
## S3 method for class 'clock_year_month_day' add_years(x, n, ...) ## S3 method for class 'clock_year_month_day' add_quarters(x, n, ...) ## S3 method for class 'clock_year_month_day' add_months(x, n, ...)
## S3 method for class 'clock_year_month_day' add_years(x, n, ...) ## S3 method for class 'clock_year_month_day' add_quarters(x, n, ...) ## S3 method for class 'clock_year_month_day' add_months(x, n, ...)
x 
A yearmonthday vector. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
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.
x
after performing the arithmetic.
x < year_month_day(2019, 1, 1) add_years(x, 1:5) y < year_month_day(2019, 1, 31) # Adding 1 month to `y` generates an invalid date y_plus < add_months(y, 1:2) y_plus # Invalid dates are fine, as long as they are eventually resolved # by either manually resolving, or by calling `invalid_resolve()` # Resolve by returning the previous / next valid moment in time invalid_resolve(y_plus, invalid = "previous") invalid_resolve(y_plus, invalid = "next") # Manually resolve by setting to the last day of the month invalid < invalid_detect(y_plus) y_plus[invalid] < set_day(y_plus[invalid], "last") y_plus
x < year_month_day(2019, 1, 1) add_years(x, 1:5) y < year_month_day(2019, 1, 31) # Adding 1 month to `y` generates an invalid date y_plus < add_months(y, 1:2) y_plus # Invalid dates are fine, as long as they are eventually resolved # by either manually resolving, or by calling `invalid_resolve()` # Resolve by returning the previous / next valid moment in time invalid_resolve(y_plus, invalid = "previous") invalid_resolve(y_plus, invalid = "next") # Manually resolve by setting to the last day of the month invalid < invalid_detect(y_plus) y_plus[invalid] < set_day(y_plus[invalid], "last") y_plus
This is a yearmonthday method for the calendar_start()
and
calendar_end()
generics. They adjust components of a calendar to the
start or end of a specified precision
.
## S3 method for class 'clock_year_month_day' calendar_start(x, precision) ## S3 method for class 'clock_year_month_day' calendar_end(x, precision)
## S3 method for class 'clock_year_month_day' calendar_start(x, precision) ## S3 method for class 'clock_year_month_day' calendar_end(x, precision)
x 
A yearmonthday vector. 
precision 
One of:

x
at the same precision, but with some components altered to be
at the boundary value.
# 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") # Compare that with just setting the day of the month to `"last"`, which # doesn't adjust any other components set_day(x, "last") # You can't compute the start / end at a more precise precision than # the input is at try(calendar_start(x, "second"))
# 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") # Compare that with just setting the day of the month to `"last"`, which # doesn't adjust any other components set_day(x, "last") # You can't compute the start / end at a more precise precision than # the input is at try(calendar_start(x, "second"))
This is a yearmonthday method for the calendar_count_between()
generic.
It counts the number of precision
units between start
and end
(i.e., the number of years or months).
## S3 method for class 'clock_year_month_day' calendar_count_between(start, end, precision, ..., n = 1L)
## S3 method for class 'clock_year_month_day' calendar_count_between(start, end, precision, ..., n = 1L)
start , end

A pair of yearmonthday vectors. These will be recycled to their common size. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
"quarter"
is equivalent to "month"
precision with n
set to n * 3L
.
An integer representing the number of precision
units between
start
and end
.
# Compute an individual's age in years x < year_month_day(2001, 2, 4) today < year_month_day(2021, 11, 30) calendar_count_between(x, today, "year") # Compute the number of months between two dates, taking # into account the day of the month and time of day x < year_month_day(2000, 4, 2, 5) y < year_month_day(2000, 7, c(1, 2, 2), c(3, 4, 6)) calendar_count_between(x, y, "month")
# Compute an individual's age in years x < year_month_day(2001, 2, 4) today < year_month_day(2021, 11, 30) calendar_count_between(x, today, "year") # Compute the number of months between two dates, taking # into account the day of the month and time of day x < year_month_day(2000, 4, 2, 5) y < year_month_day(2000, 7, c(1, 2, 2), c(3, 4, 6)) calendar_count_between(x, y, "month")
These are yearmonthday 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 subdaily getters for extracting more precise components.
## S3 method for class 'clock_year_month_day' get_year(x) ## S3 method for class 'clock_year_month_day' get_month(x) ## S3 method for class 'clock_year_month_day' get_day(x) ## S3 method for class 'clock_year_month_day' get_hour(x) ## S3 method for class 'clock_year_month_day' get_minute(x) ## S3 method for class 'clock_year_month_day' get_second(x) ## S3 method for class 'clock_year_month_day' get_millisecond(x) ## S3 method for class 'clock_year_month_day' get_microsecond(x) ## S3 method for class 'clock_year_month_day' get_nanosecond(x)
## S3 method for class 'clock_year_month_day' get_year(x) ## S3 method for class 'clock_year_month_day' get_month(x) ## S3 method for class 'clock_year_month_day' get_day(x) ## S3 method for class 'clock_year_month_day' get_hour(x) ## S3 method for class 'clock_year_month_day' get_minute(x) ## S3 method for class 'clock_year_month_day' get_second(x) ## S3 method for class 'clock_year_month_day' get_millisecond(x) ## S3 method for class 'clock_year_month_day' get_microsecond(x) ## S3 method for class 'clock_year_month_day' get_nanosecond(x)
x 
A yearmonthday to get the component from. 
The component.
x < year_month_day(2019, 1:3, 5:7, 1, 20, 30) get_month(x) get_day(x) get_second(x) # Cannot extract more precise components y < year_month_day(2019, 1) try(get_day(y)) # Cannot extract components that don't exist for this calendar try(get_quarter(x))
x < year_month_day(2019, 1:3, 5:7, 1, 20, 30) get_month(x) get_day(x) get_second(x) # Cannot extract more precise components y < year_month_day(2019, 1) try(get_day(y)) # Cannot extract components that don't exist for this calendar try(get_quarter(x))
This is a yearmonthday method for the calendar_group()
generic.
Grouping for a yearmonthday object can be done at any precision, as
long as x
is at least as precise as precision
.
## S3 method for class 'clock_year_month_day' calendar_group(x, precision, ..., n = 1L)
## S3 method for class 'clock_year_month_day' calendar_group(x, precision, ..., n = 1L)
x 
A yearmonthday vector. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
x
grouped at the specified precision
.
steps < duration_days(seq(0, 100, by = 5)) x < year_month_day(2019, 1, 1) x < as_naive_time(x) + steps x < as_year_month_day(x) x # Group by a single month calendar_group(x, "month") # Or multiple months calendar_group(x, "month", n = 2) # Group 3 days of the month together y < year_month_day(2019, 1, 1:12) calendar_group(y, "day", n = 3) # Group by 5 nanosecond of the current second z < year_month_day( 2019, 1, 2, 1, 5, 20, 1:20, subsecond_precision = "nanosecond" ) calendar_group(z, "nanosecond", n = 5)
steps < duration_days(seq(0, 100, by = 5)) x < year_month_day(2019, 1, 1) x < as_naive_time(x) + steps x < as_year_month_day(x) x # Group by a single month calendar_group(x, "month") # Or multiple months calendar_group(x, "month", n = 2) # Group 3 days of the month together y < year_month_day(2019, 1, 1:12) calendar_group(y, "day", n = 3) # Group by 5 nanosecond of the current second z < year_month_day( 2019, 1, 2, 1, 5, 20, 1:20, subsecond_precision = "nanosecond" ) calendar_group(z, "nanosecond", n = 5)
This is a yearmonthday method for the calendar_narrow()
generic. It
narrows a yearmonthday vector to the specified precision
.
## S3 method for class 'clock_year_month_day' calendar_narrow(x, precision)
## S3 method for class 'clock_year_month_day' calendar_narrow(x, precision)
x 
A yearmonthday vector. 
precision 
One of:

x
narrowed to the supplied precision
.
# 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") # Subsecond precision can be narrowed to second precision milli < calendar_widen(x, "millisecond") micro < calendar_widen(x, "microsecond") milli micro calendar_narrow(milli, "second") calendar_narrow(micro, "second") # But once you have "locked in" a subsecond precision, it can't be # narrowed to another subsecond precision try(calendar_narrow(micro, "millisecond"))
# 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") # Subsecond precision can be narrowed to second precision milli < calendar_widen(x, "millisecond") micro < calendar_widen(x, "microsecond") milli micro calendar_narrow(milli, "second") calendar_narrow(micro, "second") # But once you have "locked in" a subsecond precision, it can't be # narrowed to another subsecond precision try(calendar_narrow(micro, "millisecond"))
These are yearmonthday methods for the setter generics.
set_year()
sets the Gregorian 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]
.
There are subdaily setters for setting more precise components.
## S3 method for class 'clock_year_month_day' set_year(x, value, ...) ## S3 method for class 'clock_year_month_day' set_month(x, value, ...) ## S3 method for class 'clock_year_month_day' set_day(x, value, ...) ## S3 method for class 'clock_year_month_day' set_hour(x, value, ...) ## S3 method for class 'clock_year_month_day' set_minute(x, value, ...) ## S3 method for class 'clock_year_month_day' set_second(x, value, ...) ## S3 method for class 'clock_year_month_day' set_millisecond(x, value, ...) ## S3 method for class 'clock_year_month_day' set_microsecond(x, value, ...) ## S3 method for class 'clock_year_month_day' set_nanosecond(x, value, ...)
## S3 method for class 'clock_year_month_day' set_year(x, value, ...) ## S3 method for class 'clock_year_month_day' set_month(x, value, ...) ## S3 method for class 'clock_year_month_day' set_day(x, value, ...) ## S3 method for class 'clock_year_month_day' set_hour(x, value, ...) ## S3 method for class 'clock_year_month_day' set_minute(x, value, ...) ## S3 method for class 'clock_year_month_day' set_second(x, value, ...) ## S3 method for class 'clock_year_month_day' set_millisecond(x, value, ...) ## S3 method for class 'clock_year_month_day' set_microsecond(x, value, ...) ## S3 method for class 'clock_year_month_day' set_nanosecond(x, value, ...)
x 
A yearmonthday vector. 
value 
The value to set the component to. For 
... 
These dots are for future extensions and must be empty. 
x
with the component set.
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") # Set to an invalid day of the month invalid < set_day(x, 31) invalid # Then resolve the invalid day by choosing the next valid day invalid_resolve(invalid, invalid = "next") # Cannot set a component two levels more precise than where you currently are try(set_hour(x, 5))
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") # Set to an invalid day of the month invalid < set_day(x, 31) invalid # Then resolve the invalid day by choosing the next valid day invalid_resolve(invalid, invalid = "next") # Cannot set a component two levels more precise than where you currently are try(set_hour(x, 5))
This is a yearmonthday method for the calendar_widen()
generic. It
widens a yearmonthday vector to the specified precision
.
## S3 method for class 'clock_year_month_day' calendar_widen(x, precision)
## S3 method for class 'clock_year_month_day' calendar_widen(x, precision)
x 
A yearmonthday vector. 
precision 
One of:

x
widened to the supplied precision
.
# Month precision x < year_month_day(2019, 1) x # Widen to day precision calendar_widen(x, "day") # Or second precision sec < calendar_widen(x, "second") sec # Second precision can be widened to subsecond precision milli < calendar_widen(sec, "millisecond") micro < calendar_widen(sec, "microsecond") milli micro # But once you have "locked in" a subsecond precision, it can't # be widened again try(calendar_widen(milli, "microsecond"))
# Month precision x < year_month_day(2019, 1) x # Widen to day precision calendar_widen(x, "day") # Or second precision sec < calendar_widen(x, "second") sec # Second precision can be widened to subsecond precision milli < calendar_widen(sec, "millisecond") micro < calendar_widen(sec, "microsecond") milli micro # But once you have "locked in" a subsecond precision, it can't # be widened again try(calendar_widen(milli, "microsecond"))
These are yearmonthweekday methods for the arithmetic generics.
add_years()
add_quarters()
add_months()
Notably, you cannot add days to a yearmonthweekday. For daybased
arithmetic, first convert to a time point with as_naive_time()
or
as_sys_time()
.
## S3 method for class 'clock_year_month_weekday' add_years(x, n, ...) ## S3 method for class 'clock_year_month_weekday' add_quarters(x, n, ...) ## S3 method for class 'clock_year_month_weekday' add_months(x, n, ...)
## S3 method for class 'clock_year_month_weekday' add_years(x, n, ...) ## S3 method for class 'clock_year_month_weekday' add_quarters(x, n, ...) ## S3 method for class 'clock_year_month_weekday' add_months(x, n, ...)
x 
A yearmonthweekday vector. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
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.
x
after performing the arithmetic.
# 2nd Friday in January, 2019 x < year_month_weekday(2019, 1, clock_weekdays$friday, 2) x add_months(x, 1:5) # These don't necessarily correspond to the same day of the month as_year_month_day(add_months(x, 1:5))
# 2nd Friday in January, 2019 x < year_month_weekday(2019, 1, clock_weekdays$friday, 2) x add_months(x, 1:5) # These don't necessarily correspond to the same day of the month as_year_month_day(add_months(x, 1:5))
This is a yearmonthweekday method for the calendar_start()
and
calendar_end()
generics. They adjust components of a calendar to the
start or end of a specified precision
.
This method is restricted to only "year"
and "month"
precision
s, and
x
can't be more precise than month precision. Computing the "start" of
a day precision yearmonthweekday object isn't defined because
a yearmonthweekday with day = 1, index = 1
doesn't necessarily occur
earlier (chronologically) than day = 2, index = 1
. Because of these
restrictions, this method isn't particularly useful, but is included for
completeness.
## S3 method for class 'clock_year_month_weekday' calendar_start(x, precision) ## S3 method for class 'clock_year_month_weekday' calendar_end(x, precision)
## S3 method for class 'clock_year_month_weekday' calendar_start(x, precision) ## S3 method for class 'clock_year_month_weekday' calendar_end(x, precision)
x 
A yearmonthweekday vector. 
precision 
One of:

x
at the same precision, but with some components altered to be
at the boundary value.
# Month precision x < year_month_weekday(2019, 1:5) x # Compute the last month of the year calendar_end(x, "year")
# Month precision x < year_month_weekday(2019, 1:5) x # Compute the last month of the year calendar_end(x, "year")
This is a yearmonthweekday method for the calendar_count_between()
generic. It counts the number of precision
units between start
and end
(i.e., the number of years or months).
## S3 method for class 'clock_year_month_weekday' calendar_count_between(start, end, precision, ..., n = 1L)
## S3 method for class 'clock_year_month_weekday' calendar_count_between(start, end, precision, ..., n = 1L)
start , end

A pair of yearmonthweekday vectors. These will be recycled to their common size. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
Remember that yearmonthweekday is not comparable when it is "day"
precision or finer, so this method is only defined for "year"
and
"month"
precision yearmonthweekday objects.
"quarter"
is equivalent to "month"
precision with n
set to n * 3L
.
An integer representing the number of precision
units between
start
and end
.
# Compute the number of months between two dates x < year_month_weekday(2001, 2) y < year_month_weekday(2021, c(1, 3)) calendar_count_between(x, y, "month") # Remember that day precision or finer yearmonthweekday objects # are not comparable, so this won't work x < year_month_weekday(2001, 2, 1, 1) try(calendar_count_between(x, x, "month"))
# Compute the number of months between two dates x < year_month_weekday(2001, 2) y < year_month_weekday(2021, c(1, 3)) calendar_count_between(x, y, "month") # Remember that day precision or finer yearmonthweekday objects # are not comparable, so this won't work x < year_month_weekday(2001, 2, 1, 1) try(calendar_count_between(x, x, "month"))
These are yearmonthweekday 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 week encoded from 17, where 1 = Sunday
and 7 = Saturday.
get_index()
returns a value from 15 indicating that the corresponding
weekday is the nth instance of that weekday in the current month.
There are subdaily getters for extracting more precise components.
## S3 method for class 'clock_year_month_weekday' get_year(x) ## S3 method for class 'clock_year_month_weekday' get_month(x) ## S3 method for class 'clock_year_month_weekday' get_day(x) ## S3 method for class 'clock_year_month_weekday' get_index(x) ## S3 method for class 'clock_year_month_weekday' get_hour(x) ## S3 method for class 'clock_year_month_weekday' get_minute(x) ## S3 method for class 'clock_year_month_weekday' get_second(x) ## S3 method for class 'clock_year_month_weekday' get_millisecond(x) ## S3 method for class 'clock_year_month_weekday' get_microsecond(x) ## S3 method for class 'clock_year_month_weekday' get_nanosecond(x)
## S3 method for class 'clock_year_month_weekday' get_year(x) ## S3 method for class 'clock_year_month_weekday' get_month(x) ## S3 method for class 'clock_year_month_weekday' get_day(x) ## S3 method for class 'clock_year_month_weekday' get_index(x) ## S3 method for class 'clock_year_month_weekday' get_hour(x) ## S3 method for class 'clock_year_month_weekday' get_minute(x) ## S3 method for class 'clock_year_month_weekday' get_second(x) ## S3 method for class 'clock_year_month_weekday' get_millisecond(x) ## S3 method for class 'clock_year_month_weekday' get_microsecond(x) ## S3 method for class 'clock_year_month_weekday' get_nanosecond(x)
x 
A yearmonthweekday to get the component from. 
The component.
monday < clock_weekdays$monday thursday < clock_weekdays$thursday x < year_month_weekday(2019, 1, monday:thursday, 1:4) x # Gets the weekday, 1 = Sunday, 7 = Saturday get_day(x) # Gets the index indicating which instance of that particular weekday # it is in the current month (i.e. the "1st Monday of January, 2019") get_index(x)
monday < clock_weekdays$monday thursday < clock_weekdays$thursday x < year_month_weekday(2019, 1, monday:thursday, 1:4) x # Gets the weekday, 1 = Sunday, 7 = Saturday get_day(x) # Gets the index indicating which instance of that particular weekday # it is in the current month (i.e. the "1st Monday of January, 2019") get_index(x)
This is a yearmonthweekday method for the calendar_group()
generic.
Grouping for a yearmonthweekday object can be done at any precision except
for "day"
, as long as x
is at least as precise as precision
.
## S3 method for class 'clock_year_month_weekday' calendar_group(x, precision, ..., n = 1L)
## S3 method for class 'clock_year_month_weekday' calendar_group(x, precision, ..., n = 1L)
x 
A yearmonthweekday vector. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
Grouping by "day"
is undefined for a yearmonthweekday because there are
two day fields, the weekday and the index, and there is no clear way to
define how to group by that.
x
grouped at the specified precision
.
x < year_month_weekday(2019, 1:12, clock_weekdays$sunday, 1, 00, 05, 05) x # Group by 3 months  drops more precise components! calendar_group(x, "month", n = 3)
x < year_month_weekday(2019, 1:12, clock_weekdays$sunday, 1, 00, 05, 05) x # Group by 3 months  drops more precise components! calendar_group(x, "month", n = 3)
This is a yearmonthweekday method for the calendar_narrow()
generic. It
narrows a yearmonthweekday vector to the specified precision
.
## S3 method for class 'clock_year_month_weekday' calendar_narrow(x, precision)
## S3 method for class 'clock_year_month_weekday' calendar_narrow(x, precision)
x 
A yearmonthweekday vector. 
precision 
One of:

x
narrowed to the supplied precision
.
# Day precision x < year_month_weekday(2019, 1, 1, 2) x # Narrowed to month precision calendar_narrow(x, "month")
# Day precision x < year_month_weekday(2019, 1, 1, 2) x # Narrowed to month precision calendar_narrow(x, "month")
These are yearmonthweekday methods for the setter generics.
set_year()
sets the Gregorian 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 week. Valid values are in the range of
[1, 7]
, with 1 = Sunday, and 7 = Saturday.
set_index()
sets the index indicating that the corresponding
weekday is the nth instance of that weekday in the current month. Valid
values are in the range of [1, 5]
.
There are subdaily setters for setting more precise components.
## S3 method for class 'clock_year_month_weekday' set_year(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_month(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_day(x, value, ..., index = NULL) ## S3 method for class 'clock_year_month_weekday' set_index(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_hour(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_minute(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_second(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_millisecond(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_microsecond(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_nanosecond(x, value, ...)
## S3 method for class 'clock_year_month_weekday' set_year(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_month(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_day(x, value, ..., index = NULL) ## S3 method for class 'clock_year_month_weekday' set_index(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_hour(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_minute(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_second(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_millisecond(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_microsecond(x, value, ...) ## S3 method for class 'clock_year_month_weekday' set_nanosecond(x, value, ...)
x 
A yearmonthweekday vector. 
value 
The value to set the component to. For 
... 
These dots are for future extensions and must be empty. 
index 
This argument is only used with If 
x
with the component set.
x < year_month_weekday(2019, 1:3) set_year(x, 2020:2022) # Setting the weekday on a month precision yearmonthweekday requires # also setting the `index` to fully specify the day information x < set_day(x, clock_weekdays$sunday, index = 1) x # Once you have at least day precision, you can set the weekday and # the index separately set_day(x, clock_weekdays$monday) set_index(x, 3) # Set to the "last" instance of the corresponding weekday in this month # (Note that some months have 4 Sundays, and others have 5) set_index(x, "last") # Set to an invalid index # January and February of 2019 don't have 5 Sundays! invalid < set_index(x, 5) invalid # Resolve the invalid dates by choosing the previous/next valid moment invalid_resolve(invalid, invalid = "previous") invalid_resolve(invalid, invalid = "next") # You can also "overflow" the index. This keeps the weekday, but resets # the index to 1 and increments the month value by 1. invalid_resolve(invalid, invalid = "overflow")
x < year_month_weekday(2019, 1:3) set_year(x, 2020:2022) # Setting the weekday on a month precision yearmonthweekday requires # also setting the `index` to fully specify the day information x < set_day(x, clock_weekdays$sunday, index = 1) x # Once you have at least day precision, you can set the weekday and # the index separately set_day(x, clock_weekdays$monday) set_index(x, 3) # Set to the "last" instance of the corresponding weekday in this month # (Note that some months have 4 Sundays, and others have 5) set_index(x, "last") # Set to an invalid index # January and February of 2019 don't have 5 Sundays! invalid < set_index(x, 5) invalid # Resolve the invalid dates by choosing the previous/next valid moment invalid_resolve(invalid, invalid = "previous") invalid_resolve(invalid, invalid = "next") # You can also "overflow" the index. This keeps the weekday, but resets # the index to 1 and increments the month value by 1. invalid_resolve(invalid, invalid = "overflow")
This is a yearmonthweekday method for the calendar_widen()
generic. It
widens a yearmonthweekday vector to the specified precision
.
## S3 method for class 'clock_year_month_weekday' calendar_widen(x, precision)
## S3 method for class 'clock_year_month_weekday' calendar_widen(x, precision)
x 
A yearmonthweekday vector. 
precision 
One of:

Widening a month precision yearmonthweekday to day precision will set
the day and the index to 1
. This sets the weekday components to the
first Sunday of the month.
x
widened to the supplied precision
.
# Month precision x < year_month_weekday(2019, 1) x # Widen to day precision # Note that this sets both the day and index to 1, # i.e. the first Sunday of the month. calendar_widen(x, "day") # Or second precision sec < calendar_widen(x, "second") sec
# Month precision x < year_month_weekday(2019, 1) x # Widen to day precision # Note that this sets both the day and index to 1, # i.e. the first Sunday of the month. calendar_widen(x, "day") # Or second precision sec < calendar_widen(x, "second") sec
These are yearquarterday methods for the arithmetic generics.
add_years()
add_quarters()
Notably, you cannot add days to a yearquarterday. For daybased
arithmetic, first convert to a time point with as_naive_time()
or
as_sys_time()
.
## S3 method for class 'clock_year_quarter_day' add_years(x, n, ...) ## S3 method for class 'clock_year_quarter_day' add_quarters(x, n, ...)
## S3 method for class 'clock_year_quarter_day' add_years(x, n, ...) ## S3 method for class 'clock_year_quarter_day' add_quarters(x, n, ...)
x 
A yearquarterday vector. 
n 
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. 
... 
These dots are for future extensions and must be empty. 
x
and n
are recycled against each other using
tidyverse recycling rules.
x
after performing the arithmetic.
x < year_quarter_day(2019, 1:3) x add_quarters(x, 2) # Make the fiscal year start in March y < year_quarter_day(2019, 1:2, 1, start = 3) y add_quarters(y, 1) # What yearmonthday does this correspond to? # Note that the fiscal year doesn't necessarily align with the Gregorian # year! as_year_month_day(add_quarters(y, 1))
x < year_quarter_day(2019, 1:3) x add_quarters(x, 2) # Make the fiscal year start in March y < year_quarter_day(2019, 1:2, 1, start = 3) y add_quarters(y, 1) # What yearmonthday does this correspond to? # Note that the fiscal year doesn't necessarily align with the Gregorian # year! as_year_month_day(add_quarters(y, 1))
This is a yearquarterday method for the calendar_start()
and
calendar_end()
generics. They adjust components of a calendar to the
start or end of a specified precision
.
## S3 method for class 'clock_year_quarter_day' calendar_start(x, precision) ## S3 method for class 'clock_year_quarter_day' calendar_end(x, precision)
## S3 method for class 'clock_year_quarter_day' calendar_start(x, precision) ## S3 method for class 'clock_year_quarter_day' calendar_end(x, precision)
x 
A yearquarterday vector. 
precision 
One of:

x
at the same precision, but with some components altered to be
at the boundary value.
x < year_quarter_day(2019:2020, 2:3, 5, 6, 7, 8, start = clock_months$march) x # Compute the last moment of the fiscal quarter calendar_end(x, "quarter") # Compare that to just setting the day to `"last"`, # which doesn't affect the other components set_day(x, "last") # Compute the start of the fiscal year calendar_start(x, "year") as_date(calendar_start(x, "year"))
x < year_quarter_day(2019:2020, 2:3, 5, 6, 7, 8, start = clock_months$march) x # Compute the last moment of the fiscal quarter calendar_end(x, "quarter") # Compare that to just setting the day to `"last"`, # which doesn't affect the other components set_day(x, "last") # Compute the start of the fiscal year calendar_start(x, "year") as_date(calendar_start(x, "year"))
This is a yearquarterday method for the calendar_count_between()
generic.
It counts the number of precision
units between start
and end
(i.e.,
the number of years or quarters).
## S3 method for class 'clock_year_quarter_day' calendar_count_between(start, end, precision, ..., n = 1L)
## S3 method for class 'clock_year_quarter_day' calendar_count_between(start, end, precision, ..., n = 1L)
start , end

A pair of yearquarterday vectors. These will be recycled to their common size. 
precision 
One of:

... 
These dots are for future extensions and must be empty. 
n 
A single positive integer specifying a multiple of 
An integer representing the number of precision
units between
start
and end
.
# Compute the number of whole quarters between two dates x < year_quarter_day(2020, 3, 91) y < year_quarter_day(2025, 4, c(90, 92)) calendar_count_between(x, y, "quarter") # Note that this is not always the same as the number of whole 3 month # periods between two dates x < as_year_month_day(x) y < as_year_month_day(y) calendar_count_between(x, y, "month", n = 3)
# Compute the number of whole quarters between two dates x < year_quarter_day(2020, 3, 91) y < year_quarter_day(2025, 4, c(90, 92)) calendar_count_between(x, y, "quarter") # Note that this is not always the same as the number of whole 3 month # periods between two dates x < as_year_month_day(x) y < as_year_month_day(y) calendar_count_between(x, y, "month", n = 3)
These are yearquarterday methods for the getter generics.
get_year()
returns the fiscal year. Note that this can differ from the
Gregorian year if start != 1L
.
get_quarter()
returns the fiscal quarter as a value between 14.
get_day()
returns the day of the fiscal quarter as a value between 192.
There are subdaily getters for extracting more precise components.
## S3 method for class 'clock_year_quarter_day' get_year(x) ## S3 method for class 'clock_year_quarter_day' get_quarter(x) ## S3 method for class 'clock_year_quarter_day' get_day(x) ## S3 method for class 'clock_year_quarter_day' get_hour(x) ## S3 method for class 'clock_year_quarter_day' get_minute(x) ## S3 method for class 'clock_year_quarter_day' get_second(x) ## S3 method for class 'clock_year_quarter_day' get_millisecond(x) ## S3 method for class 'clock_year_quarter_day' get_microsecond(x) ## S3 method for class 'clock_year_quarter_day' get_nanosecond(x)
## S3 method for class 'clock_year_quarter_day' get_year(x) ## S3 method for class 'clock_year_quarter_day' get_quarter(x) ## S3 method for class 'clock_year_quarter_day' get_day(x) ## S3 method for class 'clock_year_quarter_day' get_hour(x) ## S3 method for class 'clock_year_quarter_day' get_minute(x) ## S3 method for class 'clock_year_quarter_day' get_second(x) ## S3 method for class 'clock_year_quarter_day' get_millisecond(x) ## S3 method for class 'clock_year_quarter_day' get_microsecond(x) ## S3 method for class 'clock_year_quarter_day' get_nanosecond(x)
x 
A yearquarterday to get the component from. 
The component.
x < year_quarter_day(2020, 1:4) get_quarter(x) # Set and then get the last day of the quarter x < set_day(x, "last") get_day(x) # Start the fiscal year in November and choose the 50th day in # each quarter of 2020 november < 11 y < year_quarter_day(2020, 1:4, 50, start = 11) y get_day(y) # What does that map to in yearmonthday? as_year_month_day(y)
x < year_quarter_day(2020, 1:4) get_quarter(x) # Set and then get the last day of the quarter x < set_day(x, "last") get_day(x) # Start the fiscal year in November and choose the 50th day in # each quarter of 2020 november < 11 y < year_quarter_day(2020, 1:4, 50, start = 11) y get_day(y) # What does that map to in yearmonthday? as_year_month_day(y)
This is a yearquarterday method for the calendar_group()
generic.
Grouping for a yearquarterday object can be done at any precision, as
long as x
is at least as precise as precision
.
## S3 method for class 'clock_year_quarter_day' calendar_group(x, precision, ..., n = 1L)
## S3 method for class 'clock_year_quarter_day' calendar_group(x, precision, ..., n = 1L)
x 
A yearquarterday vector. 
precision 
One of:
