1% Generated by roxygen2: do not edit by hand 2% Please edit documentation in R/package.r 3\docType{package} 4\name{lubridate-package} 5\alias{lubridate} 6\alias{lubridate-package} 7\title{Dates and times made easy with lubridate} 8\description{ 9Lubridate provides tools that make it easier to parse and 10manipulate dates. These tools are grouped below by common 11purpose. More information about each function can be found in 12its help documentation. 13} 14\section{Parsing dates}{ 15 16 17Lubridate's parsing functions read strings into R as POSIXct 18date-time objects. Users should choose the function whose name 19models the order in which the year ('y'), month ('m') and day 20('d') elements appear the string to be parsed: 21\code{\link[=dmy]{dmy()}}, \code{\link[=myd]{myd()}}, \code{\link[=ymd]{ymd()}}, 22\code{\link[=ydm]{ydm()}}, \code{\link[=dym]{dym()}}, \code{\link[=mdy]{mdy()}}, 23\code{\link[=ymd_hms]{ymd_hms()}}). A very flexible and user friendly parser 24is provided by \code{\link[=parse_date_time]{parse_date_time()}}. 25 26Lubridate can also parse partial dates from strings into 27\linkS4class{Period} objects with the functions 28\code{\link[=hm]{hm()}}, \code{\link[=hms]{hms()}} and \code{\link[=ms]{ms()}}. 29 30Lubridate has an inbuilt very fast POSIX parser. Most of the \code{\link[=strptime]{strptime()}} 31formats and various extensions are supported for English locales. See 32\code{\link[=parse_date_time]{parse_date_time()}} for more details. 33} 34 35\section{Manipulating dates}{ 36 37 38Lubridate distinguishes between moments in time (known as 39\code{\link[=instants]{instants()}}) and spans of time (known as time spans, see 40\linkS4class{Timespan}). Time spans are further separated into 41\linkS4class{Duration}, \linkS4class{Period} and 42\linkS4class{Interval} objects. 43} 44 45\section{Instants}{ 46 47 48Instants are specific moments of time. Date, POSIXct, and 49POSIXlt are the three object classes Base R recognizes as 50instants. \code{\link[=is.Date]{is.Date()}} tests whether an object 51inherits from the Date class. \code{\link[=is.POSIXt]{is.POSIXt()}} tests 52whether an object inherits from the POSIXlt or POSIXct classes. 53\code{\link[=is.instant]{is.instant()}} tests whether an object inherits from 54any of the three classes. 55 56\code{\link[=now]{now()}} returns the current system time as a POSIXct 57object. \code{\link[=today]{today()}} returns the current system date. 58For convenience, 1970-01-01 00:00:00 is saved to 59\link{origin}. This is the instant from which POSIXct 60times are calculated. Try \code{unclass(now())} to see the numeric structure that 61underlies POSIXct objects. Each POSIXct object is saved as the number of seconds 62it occurred after 1970-01-01 00:00:00. 63 64Conceptually, instants are a combination of measurements on different units 65(i.e, years, months, days, etc.). The individual values for 66these units can be extracted from an instant and set with the 67accessor functions \code{\link[=second]{second()}}, \code{\link[=minute]{minute()}}, 68\code{\link[=hour]{hour()}}, \code{\link[=day]{day()}}, \code{\link[=yday]{yday()}}, 69\code{\link[=mday]{mday()}}, \code{\link[=wday]{wday()}}, \code{\link[=week]{week()}}, 70\code{\link[=month]{month()}}, \code{\link[=year]{year()}}, \code{\link[=tz]{tz()}}, 71and \code{\link[=dst]{dst()}}. 72Note: the accessor functions are named after the singular form 73of an element. They shouldn't be confused with the period 74helper functions that have the plural form of the units as a 75name (e.g, \code{\link[=seconds]{seconds()}}). 76} 77 78\section{Rounding dates}{ 79 80 81Instants can be rounded to a convenient unit using the 82functions \code{\link[=ceiling_date]{ceiling_date()}}, \code{\link[=floor_date]{floor_date()}} 83and \code{\link[=round_date]{round_date()}}. 84} 85 86\section{Time zones}{ 87 88 89Lubridate provides two helper functions for working with time 90zones. \code{\link[=with_tz]{with_tz()}} changes the time zone in which an 91instant is displayed. The clock time displayed for the instant 92changes, but the moment of time described remains the same. 93\code{\link[=force_tz]{force_tz()}} changes only the time zone element of an 94instant. The clock time displayed remains the same, but the 95resulting instant describes a new moment of time. 96} 97 98\section{Timespans}{ 99 100 101A timespan is a length of time that may or may not be connected to 102a particular instant. For example, three months is a timespan. So is an hour and 103a half. Base R uses difftime class objects to record timespans. 104However, people are not always consistent in how they expect time to behave. 105Sometimes the passage of time is a monotone progression of instants that should 106be as mathematically reliable as the number line. On other occasions time must 107follow complex conventions and rules so that the clock times we see reflect what 108we expect to observe in terms of daylight, season, and congruence with the 109atomic clock. To better navigate the nuances of time, \pkg{lubridate} creates three 110additional timespan classes, each with its own specific and consistent behavior: 111\linkS4class{Interval}, \linkS4class{Period} and 112\linkS4class{Duration}. 113 114\code{\link[=is.difftime]{is.difftime()}} tests whether an object 115inherits from the difftime class. \code{\link[=is.timespan]{is.timespan()}} 116tests whether an object inherits from any of the four timespan 117classes. 118} 119 120\section{Durations}{ 121 122 123Durations measure the exact amount of time that occurs between two 124instants. This can create unexpected results in relation to clock times if a 125leap second, leap year, or change in daylight savings time (DST) occurs in 126the interval. 127 128Functions for working with durations include \code{\link[=is.duration]{is.duration()}}, 129\code{\link[=as.duration]{as.duration()}} and \code{\link[=duration]{duration()}}. \code{\link[=dseconds]{dseconds()}}, 130\code{\link[=dminutes]{dminutes()}}, \code{\link[=dhours]{dhours()}}, \code{\link[=ddays]{ddays()}}, 131\code{\link[=dweeks]{dweeks()}} and \code{\link[=dyears]{dyears()}} convenient lengths. 132} 133 134\section{Periods}{ 135 136 137Periods measure the change in clock time that occurs between two 138instants. Periods provide robust predictions of clock time in the presence of 139leap seconds, leap years, and changes in DST. 140 141Functions for working with periods include 142\code{\link[=is.period]{is.period()}}, \code{\link[=as.period]{as.period()}} and 143\code{\link[=period]{period()}}. \code{\link[=seconds]{seconds()}}, 144\code{\link[=minutes]{minutes()}}, \code{\link[=hours]{hours()}}, \code{\link[=days]{days()}}, 145\code{\link[=weeks]{weeks()}}, \code{\link[=months]{months()}} and 146\code{\link[=years]{years()}} quickly create periods of convenient 147lengths. 148} 149 150\section{Intervals}{ 151 152 153Intervals are timespans that begin at a specific instant and 154end at a specific instant. Intervals retain complete information about a 155timespan. They provide the only reliable way to convert between 156periods and durations. 157 158Functions for working with intervals include 159\code{\link[=is.interval]{is.interval()}}, \code{\link[=as.interval]{as.interval()}}, 160\code{\link[=interval]{interval()}}, \code{\link[=int_shift]{int_shift()}}, 161\code{\link[=int_flip]{int_flip()}}, \code{\link[=int_aligns]{int_aligns()}}, 162\code{\link[=int_overlaps]{int_overlaps()}}, and 163\code{\link{\%within\%}}. Intervals can also be manipulated with 164intersect, union, and setdiff(). 165} 166 167\section{Miscellaneous}{ 168 169 170\code{\link[=decimal_date]{decimal_date()}} converts an instant to a decimal of 171its year. 172\code{\link[=leap_year]{leap_year()}} tests whether an instant occurs during 173a leap year. 174\code{\link[=pretty_dates]{pretty_dates()}} provides a method of making pretty 175breaks for date-times. 176\link{lakers} is a data set that contains information 177about the Los Angeles Lakers 2008-2009 basketball season. 178} 179 180\references{ 181Garrett Grolemund, Hadley Wickham (2011). Dates and Times Made 182Easy with lubridate. Journal of Statistical Software, 40(3), 1-25. 183\url{https://www.jstatsoft.org/v40/i03/}. 184} 185\seealso{ 186Useful links: 187\itemize{ 188 \item \url{https://lubridate.tidyverse.org} 189 \item \url{https://github.com/tidyverse/lubridate} 190 \item Report bugs at \url{https://github.com/tidyverse/lubridate/issues} 191} 192 193} 194\author{ 195\strong{Maintainer}: Vitalie Spinu \email{spinuvit@gmail.com} 196 197Authors: 198\itemize{ 199 \item Garrett Grolemund 200 \item Hadley Wickham 201} 202 203Other contributors: 204\itemize{ 205 \item Davis Vaughan [contributor] 206 \item Ian Lyttle [contributor] 207 \item Imanuel Costigan [contributor] 208 \item Jason Law [contributor] 209 \item Doug Mitarotonda [contributor] 210 \item Joseph Larmarange [contributor] 211 \item Jonathan Boiser [contributor] 212 \item Chel Hee Lee [contributor] 213 \item Google Inc. [contributor, copyright holder] 214} 215 216} 217\keyword{internal} 218