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