nanotime (version 0.1.1)

nanotime: Nanosecond resolution datetime functionality

Description

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

Usage

nanotime(x)
"nanotime"(x)
"nanotime"(x)
"nanotime"(x)
"nanotime"(x)
"nanotime"(x)
"nanotime"(x)
"nanotime"(x)
"print"(x, ...)
"format"(x, justify = "right", digits = NULL, na.encode = FALSE, trim = TRUE, ...)
"index2char"(x, frequency = NULL, ...)
"as.POSIXct"(x, tz, ...)
"as.POSIXlt"(x, tz, ...)
"as.Date"(x, ...)
"as.data.frame"(x, ...)
"as.integer64"(x, ...)
"Ops"(e1, e2)

Arguments

x

The object which want to convert to class nanotime

...

Required for print method signature but ignored here

justify

Required for format method but ignored here

digits

Required for format method but ignored here

na.encode

Required for format method but ignored here

trim

Required for format method but ignored here

frequency

Required for index2char method but ignored here

tz

Required for as.POSIXct and as.POSIXlt, can be set via options("nanotimeFormat") and uses ‘UTC’ as a default and fallback

e1

Operand of class nanotime

e2

Operand of class nanotime

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 (currently) only have time points, but they are effectively also durations relative to the epoch of January 1, 1970.

Design

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 onky 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.

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.

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.

Examples

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