Repository files navigation

clock is an R package for working with date-times. It is packed withfeatures, including utilities for: parsing, formatting, arithmetic,rounding, and extraction/updating of individual components. In additionto these tools for manipulating date-times, clock provides entirely newdate-time types which are structured to reduce the agony of working withtime zones as much as possible. At a high-level, clock:

• Provides a new family of date-time classes (durations, time points,zoned-times, and calendars) that partition responsibilities so thatyou only have to think about time zones when you need them.

• Implements a high level API for R’s native date (Date) and date-time(POSIXct) classes that lets you get productive quickly without havingto learn the details of clock’s new date-time types.

• Requires explicit handling of invalid dates (e.g. what date is onemonth after January 31st?) and nonexistent or ambiguous times (causedby daylight saving time issues).

• Is built on the C++datelibrary, which provides a correct and high-performance backend.

There are four key classes in clock, inspired by the design of the C++date and chrono libraries. Some types are more efficient than others atparticular operations, and it is only when all 4 are taken as a whole doyou get a complete date time library.

• Aduration counts units of time, like “5 years” or “6 nanoseconds”.Bigger units are defined in terms of seconds, i.e. 1 day is 86400seconds and 1 year is 365.2425 days. Durations are important becausethey form the backbone of clock; it’s relatively rare to use themdirectly.

• Atime point records an instant in time, like “1:24pm January 1st2015”. It combines aduration with a “clock” that defines when tostart counting and what exactly to count. There are two importanttypes of time in clock: sys-time and naive-time. They’re equivalentuntil you start working with zoned-times.

• Azoned-time is a time point paired with a time zone. You can createthem from either a sys-time or a naive-time, depending on whether youwant to convert the time point from UTC (leaving the underlyingduration unchanged, but changing the printed time), or declare thatthe time point is in a specific time zone (leaving the printed timeunchanged, but changing the underlying duration). Zoned-times areprimarily needed for communication with humans.

• Acalendar represents a date using a combination of fields likeyear-month-day, year-month-weekday, year-quarter-day, year-day, oriso-year-week-day, along with hour/minute/second fields to representtime within a day (so they’re similar to R’s POSIXlt). Calendarobjects are extremely efficient at arithmetic involving irregularperiods such as months, quarters, and years and at getting and settingspecified components. A calendar can represent invalid dates (like2020-02-31) which only need to be resolved when converting back to atime point.

Install the released version fromCRANwith:

install.packages("clock")

Install the development version fromGitHub with:

# install.packages("pak")pak::pak("r-lib/clock")

With clock, there is a high-level API for manipulating R’s native dateand date-time types (Date, POSIXct, and POSIXlt), as well as a low-levelAPI for more advanced date-time manipulations. The high-level API shouldallow you to quickly get productive with clock without having to learnmany of the new types. An easy way to get an overview of this is bylooking at theHigh LevelAPIsection of the pkgdown reference page.

You’ll also want to take a look at clock’s vignettes:

• Getting Started

• Motivations forclock

• Examples and Recipes

• Frequently AskedQuestions

You can also watch this5 minute lightningtalk about clock:

The ideas used to build clock have come from a number of places:

• First and foremost, clock depends on and is inspired by thedate library by HowardHinnant, a variant of which has been voted in to C++20.

• The R “record” types that clock is built on come fromvctrs.

• Thenanotime package wasthe first to implement a nanosecond resolution time type for R.

• Thezoo package was thefirst to implement year-month and year-quarter types, and hasfunctioned as a very successful time series infrastructure package formany years.

Additionally, I’d like to thank my wife for being a power user of clock,and having a number of discussions with me around bugs and missingfeatures. You can thank her fordate_count_between().