nanotime: Nanosecond resolution datetime functionality

Description Usage Arguments Format Details Value Caveats Input and Output Format tz parameter usage in constructors Author(s) See Also Examples

View source: R/nanotime.R

Description

Functions to operate on nanosecond time resolution using integer64 bit representation. Conversion functions for several standard R types are provided, and more will be added as needed.

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
 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
nanotime(from, ...)

as.nanotime(from, ...)

## S4 method for signature 'character'
nanotime(from, format = "", tz = "")

## S4 method for signature 'character'
as.nanotime(from, format = "", tz = "")

nanotime.matrix(x)

## S4 method for signature 'POSIXct'
nanotime(from)

## S4 method for signature 'POSIXct'
as.nanotime(from)

## S4 method for signature 'POSIXlt'
nanotime(from)

## S4 method for signature 'POSIXlt'
as.nanotime(from)

## S4 method for signature 'Date'
nanotime(from)

## S4 method for signature 'Date'
as.nanotime(from)

## S4 method for signature 'nanotime'
print(x, format = "", tz = "", quote = FALSE, ...)

## S4 method for signature 'nanotime'
show(object)

## S3 method for class 'nanotime'
format(x, format = "", tz = "", ...)

## S3 method for class 'nanotime'
index2char(x, ...)

## S3 method for class 'nanotime'
as.POSIXct(x, tz = "", ...)

## S3 method for class 'nanotime'
as.POSIXlt(x, tz = "", ...)

## S3 method for class 'nanotime'
as.Date(x, ...)

## S3 method for class 'nanotime'
as.data.frame(x, ...)

## S3 method for class 'nanotime'
as.integer64(x, ...)

## S4 method for signature 'nanotime,character'
e1 - e2

## S4 method for signature 'nanotime,nanotime'
e1 - e2

## S4 method for signature 'nanotime,integer64'
e1 - e2

## S4 method for signature 'nanotime,numeric'
e1 - e2

## S4 method for signature 'ANY,nanotime'
e1 - e2

## S4 method for signature 'nanotime,ANY'
e1 - e2

## S4 method for signature 'nanotime,ANY'
e1 + e2

## S4 method for signature 'nanotime,integer64'
e1 + e2

## S4 method for signature 'nanotime,numeric'
e1 + e2

## S4 method for signature 'ANY,nanotime'
e1 + e2

## S4 method for signature 'integer64,nanotime'
e1 + e2

## S4 method for signature 'numeric,nanotime'
e1 + e2

## S4 method for signature 'nanotime,nanotime'
e1 + e2

## S4 method for signature 'nanotime,nanotime'
Arith(e1, e2)

## S4 method for signature 'nanotime,ANY'
Arith(e1, e2)

## S4 method for signature 'ANY,nanotime'
Arith(e1, e2)

## S4 method for signature 'nanotime,character'
Compare(e1, e2)

## S4 method for signature 'character,nanotime'
Compare(e1, e2)

## S4 method for signature 'nanotime,POSIXt'
Compare(e1, e2)

## S4 method for signature 'POSIXt,nanotime'
Compare(e1, e2)

## S4 method for signature 'nanotime,ANY'
Compare(e1, e2)

## S4 method for signature 'nanotime,ANY'
Logic(e1, e2)

## S4 method for signature 'ANY,nanotime'
Logic(e1, e2)

## S4 method for signature 'nanotime'
Math(x)

## S4 method for signature 'nanotime'
Math2(x, digits)

## S4 method for signature 'nanotime'
Summary(x, ..., na.rm = FALSE)

## S4 method for signature 'nanotime'
min(x, ..., na.rm = FALSE)

## S4 method for signature 'nanotime'
max(x, ..., na.rm = FALSE)

## S4 method for signature 'nanotime'
range(x, ..., na.rm = FALSE)

## S4 method for signature 'nanotime'
Complex(z)

## S4 method for signature 'nanotime'
x[[i, j, ..., drop = FALSE]]

## S4 method for signature 'nanotime,numeric'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'nanotime,logical'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'nanotime,character'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'nanotime,ANY'
x[i, j, ..., drop = FALSE]

## S4 replacement method for signature 'nanotime,ANY,ANY,ANY'
x[i, j, ...] <- value

## S3 method for class 'nanotime'
c(...)

## S4 replacement method for signature 'nanotime'
names(x) <- value

## S4 method for signature 'nanotime'
is.na(x)

NA_nanotime_

## S3 method for class 'nanoduration'
as.data.frame(x, ...)

Arguments

...

further arguments passed to or from methods.

format

A character string. Can also be set via options("nanotimeFormat") and uses ‘%Y-%m-%dT%H:%M:%E9S%Ez’ as a default and fallback

tz

character specifying a timezone which is required for as.POSIXct, as.POSIXlt and can be specified for as.nanotime, format and print; it can also be set via options("nanotimeTz") and uses ‘UTC’ as a default and fallback

x, from

nanotime objects

quote

indicates if the output of print should be quoted

object

argument for method show

e1

Operand of class nanotime

e2

Operand of class nanotime

digits

Required for Math2 signature but ignored here

na.rm

a logical indicating whether missing values should be removed.

z

Required for Complex signature but ignored here

i

index specifying elements to extract or replace.

j

Required for [ signature but ignored here

drop

Required for [ signature but ignored here

value

argument for nanotime-class

Format

An object of class nanotime of length 1.

Details

Notice that the conversion from POSIXct explicitly sets the last three digits to zero. Nanosecond time stored in a 64-bit integer has nineteen digits precision where doubles (which are used internally for POSIXct as well) only have sixteen digits. So rather than showing three more (essentially random) digits it is constructed such that these three additional digits are zeros.

Value

A nanotime object

Caveats

Working with dates and times is difficult. One needs a representation of both time points and time duration. In R, think of Date or POSIXct objects for the former, and difftime for the later. Here we have time points nanotime, an interval type nanoival and two flavors of duration which are a simple count of nanoseconds nanoduration and a calendar duration that is able to track concepts such as months and days nanoperiod. Point in time and intervals are all based on durations relative to the epoch of January 1, 1970.

Input and Output Format

Formatting and character conversion for nanotime objects is done by functions from the RcppCCTZ package relying on code from its embedded CCTZ library. The default format is ISO3339 compliant: %Y-%m-%dT%H:%M:%E9S%Ez. It specifies a standard ISO 8601 part for date and time — as well as nine digits of precision for fractional seconds (down to nanoseconds) and on offset (typically zero as we default to UTC). It can be overriden by using options() with the key of nanotimeFormat and a suitable value. Similarly, nanotimeTz can be used to select a different timezone.

For input, some slack it cut, and various shortened formats are accepted by default such as 2020-03-10 or 2020-03-10 18:16:00, or 2020-03-10 18:16:00.001 (and the ‘T’ separator is optional.

tz parameter usage in constructors

The tz parameter is allowed only when constructing a nanotime from a character. This is because any numeric, Date and POSIXct is de facto considered an offset since the epoch. On the contrary, a character is considered interpretable and hence if it does not contain a timezone in its representation, it is possible to specify the tz argument to specify in which timezone it should be interpreted. This is useful in particular if one wants to convert a Date to be aligned to the beginning of the day in a specific timezone; in this case one should convert the Date to a character before calling the nanotime constructor with the desired timezone.

Author(s)

Dirk Eddelbuettel

Leonardo Silvestri

See Also

nanoival, nanoduration, nanoperiod, seq.nanotime

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
x <- nanotime(1)
print(x)
as.nanotime("1970-01-01T00:00:00.000000001+00:00")
as.nanotime("2020-03-10 Europe/Berlin")
as.nanotime("2020-03-10 18:31:23.001", tz="America/New_York")
x <- x + 1
print(x)
format(x)
x <- x + 10
print(x)
format(x)
nanotime(Sys.time()) + 1:3  # three elements each 1 ns apart
seq(x, by=as.nanoperiod("1d"), length.out=5, tz="Asia/Tokyo")

nanotime documentation built on Aug. 7, 2020, 1:06 a.m.