nanotime-class {nanotime} | R Documentation |
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.
as.integer64
conversion helper returning the underlying
integer64
representation
nanotime(x, ...) ## S4 method for signature 'character' nanotime(x, format = "", tz = "") nanotime.matrix(x) ## S4 method for signature 'POSIXct' nanotime(x) ## S4 method for signature 'POSIXlt' nanotime(x) ## S4 method for signature 'Date' nanotime(x) ## S4 method for signature 'nanotime' print(x, format = "", tz = "", ...) ## 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, ...) 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,ANY' Arith(e1, e2) ## S4 method for signature 'ANY,nanotime' Arith(e1, e2) ## S4 method for signature 'nanotime,ANY' Compare(e1, e2) ## S4 method for signature 'nanotime,nanotime' 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 replacement method for signature 'nanotime' 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)
x |
The object which want to convert to class |
... |
further arguments passed to or from methods. |
format |
A character string. Can also be set via |
tz |
Required for |
object |
argument for method |
e1 |
Operand of class |
e2 |
Operand of class |
digits |
Required for |
na.rm |
a logical indicating whether missing values should be removed. |
z |
Required for |
i |
index specifying elements to extract or replace. |
j |
Required for |
drop |
Required for |
value |
argument for |
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.
A nanotime object
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 (currently) only have time points,
but they are effectively also durations relative to the
epoch of January 1, 1970.
There are two external libraries doing two key components.
We rely on the bit64
package for integer64
types to represent nanoseconds relative to the epoch. This is
similar to POSIXct
which uses fractional seconds since the
epoch—so here we are essentially having the same values, but
multiplied by 10 to the power 9 and stored as integers. We need
to rely on the external package as we require 64-bit integers
whereas R itself only has 32-bit integers. The
bit64
package is clever about how it manages to
provide such an integer using only the 64-bit double type and very
clever (and efficient) transformations.
The other is the CCTZ library in C++, which we access via the
RcppCCTZ
package. CCTZ extends the C++11 standard
library type chrono
type in very useful ways for time zones and
localtime. We use its formating and parsing features.
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.
Dirk Eddelbuettel
x <- nanotime("1970-01-01T00:00:00.000000001+00:00") print(x) x <- x + 1 print(x) format(x) x <- x + 10 print(x) format(x) format(nanotime(Sys.time()) + 1:3) # three elements each 1 ns apart