temporal: Temporal Classes with Selective Defaults

Description Usage Arguments Details Value Author(s) References See Also Examples

Description

timepoint is an abstract superclass of mTime, mDate, and mDateTime. These latter are convenience classes that store timepoint information as seconds since the start of 1970-01-01. They rely on POSIXlt and POSIXct, giving full access to the format constructs of strftime. However, the concepts of ‘origin’ and ‘timezone’ are deconstructed (fixed to 1970-01-01 and GMT). Default formats are suitably chosen for inputs (as.character methods) and outputs (format methods) and may be overridden. By default, format will append a ‘+’ symbol to timepoints with dangling seconds (not multiples of 60): seconds are not displayed by default but still operate (perhaps dangerously) in comparisons.

Usage

 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
as.mTime(x, ...)
## S3 method for class 'character'
as.mTime(x, format = '%H:%M',...)
## S3 method for class 'numeric'
as.mTime(x,...)
## S3 method for class 'mTime'
as.mTime(x, ...)
## S3 method for class 'times'
as.mTime(x, ...)
as.mDate(x, ...)
## S3 method for class 'character'
as.mDate(x, format = '%Y-%m-%d',...)
## S3 method for class 'numeric'
as.mDate(x,...)
## S3 method for class 'Date'
as.mDate(x,...)
## S3 method for class 'mDate'
as.mDate(x,...)
## S3 method for class 'dates'
as.mDate(x,...)
as.mDateTime(x, ...)
## S3 method for class 'character'
as.mDateTime(x, format = '%Y-%m-%d %H:%M',...)
## S3 method for class 'numeric'
as.mDateTime(x,...)
## S3 method for class 'mDate'
as.mDateTime(x, y = 0,...)
## S3 method for class 'mDateTime'
as.mDateTime(x, ...)
## S3 method for class 'POSIXct'
as.mDateTime(x, ...)
## S3 method for class 'POSIXlt'
as.mDateTime(x, ...)
## S3 method for class 'chron'
as.mDateTime(x, ...)
## S3 method for class 'mTime'
format(x, format = '%H:%M', mark=TRUE,...)
## S3 method for class 'mDate'
format(x, format = '%Y-%m-%d', mark=TRUE,...)
## S3 method for class 'mDateTime'
format(x, format = '%Y-%m-%d %H:%M', mark=TRUE,...)
## S3 method for class 'timepoint'
unique(x, incomparables=FALSE,...)
## S3 method for class 'timepoint'
Summary(..., na.rm=FALSE)
## S3 method for class 'timepoint'
xtfrm(x,...)

Arguments

x

character time as per format, numeric seconds since 1970-01-01, or timepoint subclass

...

other arguments, usually ignored

y

optional time for constructing mDateTime from mDate: anything coercible with as.second()

format

character, as per strftime

mark

boolean: mark times with dangling seconds using ‘+’

incomparables

passed to unique

na.rm

passed to Summary

Details

Creating a timepoint object with these methods ultimately calls one of the .numeric methods, each of which round their first argument to zero places. This means that all comparisons are based on whole numbers, and therefore not subject to rounding errors.

Seconds that are not multiples of 60 can be stored in mTime and mDateTime objects, but will not be displayed by default (see above). mDate can only store numbers of seconds that correspond to midnight. To add time, explicitly create an mDateTime object using as.mDateTime.mDate.

The timepoint classes are all subclasses of numeric, so numeric operations are generally available.

The timepoint classes support NA, Inf, -Inf, as.data.frame, seq, subset, element selection, element assignment, and interconversion.

The timepoint classes are also subclasses timeline, which exists to support addition and subtraction of durations and timepoints. See examples.

Value

format

character

as.mTime

object with class c('mTime','timepoint','numeric')

as.mDate

object with class c('mDate','timepoint','numeric')

as.mDateTime

object with class c('mDateTime','timepoint','numeric')

Author(s)

Tim Bergsma

References

http://metrumrg.googlecode.com

See Also

Examples

  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
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
#numeric to timepoint
as.mTime(0)
# 00:00
as.mTime(1)
# 00:00+
as.mTime(-1)
# 23:59+
as.mTime(60)
# 00:01
as.mTime(-60)
# 23:59
as.mTime(86400)
# 00:00
as.mTime(86460)
# 00:01
as.mDate(0)
# 1970-01-01
as.mDate(1)
# 1970-01-01
as.mDate(-1)
# 1969-12-31
as.mDate(-86400)
# 1969-12-31
as.mDate(-86401)
# 1969-12-30
as.mDateTime(0)
# 1970-01-01 00:00
as.mDateTime(60)
# 1970-01-01 00:01 
as.mDateTime(61)
# 1970-01-01 00:01+
as.mDateTime(-1)
# 1969-12-31 23:59+

#character to timepoint
as.mTime('00:00')
# 00:00
as.mTime('23:59')
# 23:59
as.mTime('23:59:00')
# 23:59
as.mTime('23:59:01')
# 23:59
as.mTime('23:59:01',format='%H:%M:%S')
# 23:59+
as.mTime('24:00')
# 00:00
as.mDate('1970-01-02')
# 1970-01-02
as.mDate('01/02/1970',format='%m/%d/%Y')
# 1970-01-02
as.mDateTime('01/02/1970 12:30',format='%m/%d/%Y %H:%M')
# 1970-01-02 12:30
as.mDateTime('01/02/1970 12:30:15',format='%m/%d/%Y %H:%M:%S')
# 1970-01-02 12:30+

#timepoint to numeric
as.numeric(as.mTime(0))
# 0
as.numeric(as.mTime(1))
# 1
as.numeric(as.mTime(-1))
# 86399
as.numeric(as.mTime(60))
# 60
as.numeric(as.mTime(-60))
# 86340
as.numeric(as.mTime(86400))
# 0
as.numeric(as.mTime(86460))
# 60
as.numeric(as.mDate(0))
# 0
as.numeric(as.mDate(1))
# 0
as.numeric(as.mDate(-1))
# -86400
as.numeric(as.mDate(-86400))
# -86400
as.numeric(as.mDate(-86401))
# -172800
as.numeric(as.mDateTime(0))
# 0
as.numeric(as.mDateTime(60))
# 60 
as.numeric(as.mDateTime(61))
# 61
as.numeric(as.mDateTime(-1))
# -1
as.numeric(as.mTime('00:00'))
# 0
as.numeric(as.mTime('23:59'))
# 86340
as.numeric(as.mTime('23:59:00'))
# 86340
as.numeric(as.mTime('23:59:01'))
# 86340
as.numeric(as.mTime('23:59:01',format='%H:%M:%S'))
# 86341
as.numeric(as.mTime('24:00'))
# 0
as.numeric(as.mDate('1970-01-02'))
# 86400
as.numeric(as.mDate('01/02/1970',format='%m/%d/%Y'))
# 86400
as.numeric(as.mDateTime('01/02/1970 12:30',format='%m/%d/%Y %H:%M'))
# 131400
as.numeric(as.mDateTime('01/02/1970 12:30:15',format='%m/%d/%Y %H:%M:%S'))
# 131415

#timepoint to character
as.character(as.mTime(0))
# '00:00'
as.character(as.mDate(0))
# '1970-01-01'
as.character(as.mDateTime(0))
# '1970-01-01 00:00'

#non-default printout
format(as.mTime(30000),format='%H')
# '08'
format(as.mDate('1970-01-01'),format='%d%b%y')
# '01Jan70'
format(as.mDateTime('1970-01-02 23:30'),format='[%d/%m/%y %H:%M:%S]')
# '[02/01/70 23:30:00]'
format(as.mTime(1))
# '00:00+'
format(as.mTime(1),mark=FALSE)
# '00:00'

#sequence
seq(from=as.mTime('8:00'),to=as.mTime('12:00'))
# 08:00 09:00 10:00 11:00 12:00
seq(from=as.mDate('2008-01-01'),to=as.mDate('2008-01-04'))
# 2008-01-01 2008-01-02 2008-01-03 2008-01-04
seq(from=as.mDateTime('2008-01-01 12:00'),to=as.mDateTime('2008-01-04 12:30'))
# 2008-01-01 12:00 2008-01-02 12:00 2008-01-03 12:00 2008-01-04 12:00

#interconversion
as.mTime(as.mDate('2008-10-14'))
# 00:00
as.mTime(as.mDateTime('2008-10-14 08:00'))
# 08:00
as.mDate(as.mTime('23:59'))
# 1970-01-01
as.mDate(as.mDateTime('2008-10-14 08:00'))
# 2008-10-14
as.mDateTime(as.mTime(6000000))
# 1970-01-01 10:40
as.mDateTime(as.mDate('2008-10-14'))
# 2008-10-14 00:00
as.mDateTime(as.mDate('2008-10-14'),y=as.mTime('00:30'))
# 2008-10-14 00:30

#intercoversion from other systems
as.mDate(as.Date('1970-01-01'))
# 1970-01-01
as.mDateTime(as.POSIXct('1970-01-01',tz='GMT'))
# 1970-01-01 00:00
as.mDateTime(as.POSIXlt('1970-01-01',tz='GMT'))
# 1970-01-01 00:00
library(chron)
as.mTime(times('12:30:00'))
# 12:30
as.mDate(dates('01/01/1970'))
# 1970-01-01
as.mDateTime(chron(dates='01/01/1970',times='12:30:00'))
# 1970-01-01 12:30
as.mDate.sasdate(0)
# 1960-01-01
as.mTime(as.numeric(NA))
# <NA>

#infinity
as.mTime(Inf)
# Inf
as.mDate(Inf)
# Inf
as.mDateTime(Inf)
# Inf
as.mTime(-Inf)
# -Inf
as.mDateTime(Inf) + (Inf)
# Inf
as.mDateTime(Inf) + (-Inf)
# <NA>

#comparison
as.mTime('08:00') < as.mTime('09:00')
# TRUE
as.mDate('1970-01-01') > as.mDate('2008-01-01')
# FALSE
as.mDateTime('1970-01-01 08:00') > as.mDate('1970-01-01')
# TRUE

#summary
max(as.mDate(c('1970-01-01','1980-01-01','1975-01-01')))
# 1980-01-01

#operations
as.mDateTime(0) + as.second(60)
# 1970-01-01 00:01
as.second(60) + as.mDateTime(0)
# 1970-01-01 00:01
try(as.mDateTime(60) + as.mDateTime(60))
# Error in `+.timeline`(as.mDateTime(60), as.mDateTime(60)) : 
#   addition is undefined for two timepoints
as.mDateTime(0) + 60
# 1970-01-01 00:01
60 + as.mDateTime(0)
# 1970-01-01 00:01
as.minute(1) + as.mDateTime(0)
# 1970-01-01 00:01
as.mDateTime(0) - as.second(60)
# 1969-12-31 23:59
as.mDateTime(0) - 60
# 1969-12-31 23:59
as.mDateTime(60) - as.mDateTime(0)
# 60
try(as.second(60) - as.mDateTime(60))
# Error in `-.timeline`(as.second(60), as.mDateTime(60)) : 
#   subtracting a timepoint from non-timepoint is undefined
try(60 - as.mDateTime(60))
# Error in `-.timeline`(as.second(60), as.mDateTime(60)) : 
#   subtracting a timepoint from non-timepoint is undefined
as.second(10) * 6
# 60
as.mDateTime(0) * 2 #meaningless, but not prevented
# 1970-01-01 00:00

#unary operations
-as.mTime(1)
# 23:59+
+as.mTime(1)
# 00:00+

#sorting
sort(unique(as.mTime(c(180,120,60))))
# 00:01 00:02 00:03

metrumrg documentation built on May 2, 2019, 5:55 p.m.