Download PDF

Translations (PDF)

A **date-time** is a point on the timeline, stored as the number of seconds since 1970-01-01 00:00:00 UTC

A **date** is a day stored as the number of days since 1970-01-01

An hms is a **time** stored as the number of seconds since 00:00:00

Convert strings or numbers to date-times

Identify the order of the year (

**y**), month (**m**), day (**d**), hour (**h**), minute (**m**) and second (**s**) elements in your data.Use the function below whose name replicates the order. Each accepts a

`tz`

argument to set the time zone, e.g.`ymd(x, tz = "UTC")`

.

`ymd_hms()`

,`ymd_hm()`

,`ymd_h()`

`ydm_hms()`

,`ydm_hm()`

,`ydm_h()`

`mdy_hms()`

,`mdy_hm()`

,`mdy_h()`

`dmy_hms()`

,`dmy_hm()`

,`dmy_h()`

`ymd()`

,`ydm()`

`mdy()`

,`myd()`

`dmy()`

,`dym()`

`yq()`

: Q for quarter.`my()`

,`ym()`

`hms::hms()`

: Also`lubridate::hms()`

,`hm()`

, and`ms()`

, which return periods*.`date_decimal(decimal, tz = "UTC")`

`now(tzone = "")`

: Current time in tz (defaults to system tz).`today(tzone = "")`

: Current date in a tz (defaults to system tz).`fast_strptime()`

: Faster strptime.`parse_date_time()`

: Easier strptime.

Use an accessor function to get a component.

Assign into an accessor function to change a component in place.

`date(x)`

: Date component.`year(x)`

: Year.`isoyear(x)`

: The ISO 8601 year.`epiyear(x)`

: Epidemiological year.`month(x, label, abbr)`

: Month.`day(x)`

: Day of the month.`wday(x, label, abbr)`

: Day of week.`qday(x)`

: Day of quarter.`hour(x)`

: Hour.`minute(x)`

: Minutes.`second(x)`

: Seconds.`tz(x)`

: Time zone.`week(x)`

: Week of the year.`isoweek()`

: ISO 8601 week.`epiweek()`

: Epidemiological week.`quarter(x)`

: Quarter.`semester(x, with_year = FALSE)`

: Semester.`am(x)`

: Is it in the am?`pm(x)`

: Is it in the pm?`dst(x)`

: Is it daylight savings?`leap_year(x)`

: Is it a leap year?`update(object, ..., simple = FALSE)`

`floor_date(x, unit = "second")`

: Round down to nearest unit.`round_date(x, unit = "second")`

: Round to nearest unit.`ceiling_date(x, unit = "second")`

: Round up to the nearest unit.

Valid units are second, minute, hour, day, week, month, bimonth, quarter, season, halfyear and year.

`rollback(dates, roll_to_first = FALSE, preserve_hms = TRUE)`

: Roll back to last day of previous month. Also`rollforward()`

.

`stamp()`

: Derive a template from an example string and return a new function that will apply the template to date-times. Also `stamp_date()`

and `stamp_time()`

.

Derive a template, create a function

Apply the template to dates

**Tip: use a date with day > 12**

R recognizes ~600 time zones. Each encodes the time zone, Daylight Savings Time, and historical calendar variations for an area. R assigns *one* time zone per vector.

Use the `UTC`

time zone to avoid Daylight Savings.

`OlsonNames()`

: Returns a list of valid time zone names.`Sys.timezone()`

: Gets current time zone.`with_tz(time, tzone = "")`

: Get the**same date-time**in a new time zone (a new clock time). Also`local_time(dt, tz, units)`

. For example, 4:00 Pacific becomes 5:00 Mountain, or 6:00 Central, or 7:00 Eastern.`force_tz(time, tzone = "")`

: Get the**same clock time**in a new time zone (a new date-time). Also`force_tzs()`

. For example, 7:00 Pacific becomes 7:00 Mountain, or 7:00 Central, or 7:00 Eastern.

Lubridate provides three classes of timespans to facilitate math with dates and date-times.

Math with date-times relies on the **timeline**, which behaves inconsistently. Consider how the timeline behaves during:

- A normal day:

- The start of daylight savings (spring forward):

- The end of daylight savings (fall back):

- Leap years and leap seconds:

**Periods** track changes in clock times, which ignore time line irregularities.

**Durations** track the passage of physical time, which deviates from clock time when irregularities occur.

**Intervals** represent specific intervals of the timeline, bounded by start and end date-times.

Not all years are 365 days due to **leap days**. Not all minutes are 60 seconds due to **leap seconds**. It is possible to create an imaginary date by adding **months**, e.g. February 31st.

`%m+%`

and `%m-%`

will roll imaginary dates to the last day of the previous month.

`add_with_rollback(e1, e2, roll_to_first = TRUE)`

will roll imaginary dates to the first day of the new month.

Add or subtract periods to model events that happen a specific clock times, the the NYSE opening bell.

Make a period with the name of a time unit **pluralized**, e.g.

`[1] "3m 12d 0H 0M 0S"`

`years(x = 1)`

: x years.`months(x = 1)`

: x months.`weeks(x = 1)`

: x weeks.`days(x = 1)`

: x days.`hours(x = 1)`

: x hours.`minutes(x = 1)`

: x minutes.`seconds(x = 1)`

: x seconds.`milliseconds(x = 1)`

: x milliseconds.`microseconds(x = 1)`

: x microseconds.`nanoseconds(x = 1)`

: x nanoseconds.`picoseconds(x = 1)`

: x picoseconds.`period(num = NULL, units = "second", ...)`

: An automation friendly period constructor.`as.period(x, unit)`

: Coerce a timespan to a period, optionally in the specified units. Also`is.period()`

.`period_to_seconds(x)`

: Convert a period to the “standard” number of seconds implied by the period. Also`seconds_to_period()`

.

Add or subtract durations to model physical processes, like battery life. Durations are stored as seconds, the only time unit with a consistent length. **Difftimes** are a class of durations found in base R.

Make a duration with the name of a period prefixed with a *d*, e.g.

`[1] "1209600s (~2 weeks)"`

`dyears(x = 1)`

: 31536000x seconds.`dmonths(x = 1)`

: 2629800x seconds.`dweeks(x = 1)`

: 604800x seconds.`ddays(x = 1)`

: 86400x seconds.`dhours(x = 1)`

: 3600x seconds.`dminutes(x = 1)`

: 60x seconds.`dseconds(x = 1)`

: x seconds.`dmilliseconds(x = 1)`

: x * 10^{-3}seconds.`dmicroseconds(x = 1)`

: x * 10^{-6}seconds.`dnanoseconds(x = 1)`

: x * 10^{-9}seconds.`dpicoseconds(x = 1)`

: x * 10^{-12}seconds.`duration(num = NULL, units = "second", ...)`

: An automation friendly duration constructor.`as.duration(x, ...)`

: Coerce a timespan to a duration. Also`is.duration()`

,`is.difftime()`

.`make_difftime(x)`

: Make diffime with the specified number of units.

Divide an interval by a duration to determine its physical length, divide by an interval by a period to determine its implied length in clock time.

Make an interval with `interval()`

or `%--%`

, e.g.

`[1] 2017-01-01 UTC--2017-11-01 UTC`

```
# Shows the exact length in seconds, and the equivalent in common units
j <- d %--% ymd("2017-12-31")
j
```

`[1] 2017-11-01 UTC--2017-12-31 UTC`

`a %within% b`

: Does interval or dte0time`a`

fall within interval`b`

?`int_start(int)`

: Access/set the start date-time of an interval. Also`int_end()`

.`int_aligns(int1, int2)`

: Do two intervals share a boundary? Also`int_overlaps()`

.`int_diff(times)`

: Make the intervals that occur between the date-times in a vector.`int_flip(int)`

: Reverse the direction of an interval. Also`int_standardize()`

.`int_length(int)`

: Length in seconds.`int_shift(int, by)`

: Shifts an interval up or down the timeline by a timespan.`as.interval(x, start, ...)`

: Coerce a timespan to an interval with the start date-time. Also`is.interval()`

.

CC BY SA Posit Software, PBC • info@posit.co • posit.co

Learn more at lubridate.tidyverse.org.

Updated: 2023-06.