Title: | Nanosecond-Resolution Time Support for R |
---|---|
Description: | Full 64-bit resolution date and time functionality with nanosecond granularity is provided, with easy transition to and from the standard 'POSIXct' type. Three additional classes offer interval, period and duration functionality for nanosecond-resolution timestamps. |
Authors: | Dirk Eddelbuettel [aut, cre] |
Maintainer: | Dirk Eddelbuettel <[email protected]> |
License: | GPL (>= 2) |
Version: | 0.3.9.1 |
Built: | 2024-08-31 17:13:41 UTC |
Source: | https://github.com/eddelbuettel/nanotime |
Compare target
and current
testing ‘near
equality’. If they are different, comparison is still made to
some extent, and a report of the differences is returned. Do not
use all.equal
directly in if
expressions—either
use isTRUE(all.equal(....))
or identical
if
appropriate.
## S3 method for class 'nanoduration' all.equal( target, current, tolerance = sqrt(.Machine$double.eps), scale = NULL, countEQ = FALSE, formatFUN = function(err, what) format(err), ..., check.attributes = TRUE ) ## S4 method for signature 'nanoduration' all.equal( target, current, tolerance = sqrt(.Machine$double.eps), scale = NULL, countEQ = FALSE, formatFUN = function(err, what) format(err), ..., check.attributes = TRUE )
## S3 method for class 'nanoduration' all.equal( target, current, tolerance = sqrt(.Machine$double.eps), scale = NULL, countEQ = FALSE, formatFUN = function(err, what) format(err), ..., check.attributes = TRUE ) ## S4 method for signature 'nanoduration' all.equal( target, current, tolerance = sqrt(.Machine$double.eps), scale = NULL, countEQ = FALSE, formatFUN = function(err, what) format(err), ..., check.attributes = TRUE )
target , current
|
|
tolerance |
numeric >= 0. Differences smaller than
|
scale |
|
countEQ |
logical indicating if the |
formatFUN |
a |
... |
further arguments for different methods |
check.attributes |
logical indicating if the |
identical
, isTRUE
,
==
, and all
for exact equality
testing.
Compare target
and current
testing ‘near
equality’. If they are different, comparison is still made to
some extent, and a report of the differences is returned. Do not
use all.equal
directly in if
expressions—either
use isTRUE(all.equal(....))
or identical
if
appropriate.
## S3 method for class 'nanoival' all.equal(target, current, ..., check.attributes = TRUE) ## S4 method for signature 'nanoival' all.equal(target, current, ..., check.attributes = TRUE)
## S3 method for class 'nanoival' all.equal(target, current, ..., check.attributes = TRUE) ## S4 method for signature 'nanoival' all.equal(target, current, ..., check.attributes = TRUE)
target , current
|
|
... |
further arguments for different methods |
check.attributes |
logical indicating if the
|
identical
, isTRUE
,
==
, and all
for exact equality
testing.
Compare target
and current
testing ‘near
equality’. If they are different, comparison is still made to
some extent, and a report of the differences is returned. Do not
use all.equal
directly in if
expressions—either
use isTRUE(all.equal(....))
or identical
if
appropriate.
## S3 method for class 'nanoperiod' all.equal(target, current, ..., check.attributes = TRUE) ## S4 method for signature 'nanoperiod' all.equal(target, current, ..., check.attributes = TRUE)
## S3 method for class 'nanoperiod' all.equal(target, current, ..., check.attributes = TRUE) ## S4 method for signature 'nanoperiod' all.equal(target, current, ..., check.attributes = TRUE)
target , current
|
|
... |
further arguments for different methods |
check.attributes |
logical indicating if the
|
identical
, isTRUE
,
==
, and all
for exact equality
testing.
Compare target
and current
testing ‘near
equality’. If they are different, comparison is still made to
some extent, and a report of the differences is returned. Do not
use all.equal
directly in if
expressions—either
use isTRUE(all.equal(....))
or identical
if
appropriate.
## S3 method for class 'nanotime' all.equal( target, current, tolerance = sqrt(.Machine$double.eps), scale = NULL, countEQ = FALSE, formatFUN = function(err, what) format(err), ..., check.attributes = TRUE ) ## S4 method for signature 'nanotime' all.equal( target, current, tolerance = sqrt(.Machine$double.eps), scale = NULL, countEQ = FALSE, formatFUN = function(err, what) format(err), ..., check.attributes = TRUE )
## S3 method for class 'nanotime' all.equal( target, current, tolerance = sqrt(.Machine$double.eps), scale = NULL, countEQ = FALSE, formatFUN = function(err, what) format(err), ..., check.attributes = TRUE ) ## S4 method for signature 'nanotime' all.equal( target, current, tolerance = sqrt(.Machine$double.eps), scale = NULL, countEQ = FALSE, formatFUN = function(err, what) format(err), ..., check.attributes = TRUE )
target , current
|
|
tolerance |
numeric >= 0. Differences smaller than
|
scale |
|
countEQ |
logical indicating if the |
formatFUN |
a |
... |
further arguments for different methods |
check.attributes |
logical indicating if the |
identical
, isTRUE
,
==
, and all
for exact equality
testing.
Performs set intersection, union and difference between vectors of
temporal types from the nanotime
package.
## S4 method for signature 'nanoival,nanoival' intersect(x, y) ## S4 method for signature 'nanoival,nanoival' union(x, y) ## S4 method for signature 'nanoival,nanoival' setdiff(x, y) ## S4 method for signature 'nanotime,nanoival' intersect.idx(x, y) ## S3 method for class 'nanotime' x %in% table ## S4 method for signature 'nanotime,nanoival' x %in% table ## S4 method for signature 'nanotime,nanoival' intersect(x, y) ## S4 method for signature 'nanotime,nanoival' setdiff(x, y) ## S4 method for signature 'nanotime,nanoival' setdiff.idx(x, y) ## S4 method for signature 'nanotime,nanotime' intersect(x, y) ## S4 method for signature 'nanotime,nanotime' union(x, y) ## S4 method for signature 'nanotime,nanotime' setdiff(x, y)
## S4 method for signature 'nanoival,nanoival' intersect(x, y) ## S4 method for signature 'nanoival,nanoival' union(x, y) ## S4 method for signature 'nanoival,nanoival' setdiff(x, y) ## S4 method for signature 'nanotime,nanoival' intersect.idx(x, y) ## S3 method for class 'nanotime' x %in% table ## S4 method for signature 'nanotime,nanoival' x %in% table ## S4 method for signature 'nanotime,nanoival' intersect(x, y) ## S4 method for signature 'nanotime,nanoival' setdiff(x, y) ## S4 method for signature 'nanotime,nanoival' setdiff.idx(x, y) ## S4 method for signature 'nanotime,nanotime' intersect(x, y) ## S4 method for signature 'nanotime,nanotime' union(x, y) ## S4 method for signature 'nanotime,nanotime' setdiff(x, y)
x , y
|
a temporal type |
table |
|
Set operations between nanoival
operands allow the
construction of complex interval vectors (i.e. a nanoival
vector can specify any number of inclusions and exclusions of
time). Set operations between nanotime
and nanoival
allow to subset time vectors with interval vectors. In addition to
the generic set functions, the function intersect.idx
is
defined which returns the indices of the intersection, and the
operator %in%
is overloaded for nanotime-nanoival
which returns a logical vector that indicates which elements
belong to the interval vector.
intersect
, union
, setdiff
return
temporal types that are the result of the intersection. For
instance, set operations on two nanoival
return a
nanoival
, whereas intersection between a
nanoival
and a nanotime
returns a
nanotime
. intersect.idx
return a list of vectors
representing the element indices that intersect and
setdiff.idx
returns a vector representing the element
indices to be removed.
## Not run: ## a vector of 'nanotime' can be subsetted by a 'nanoival' which is equivalent to 'intersect': one_second <- 1e9 a <- seq(nanotime("2012-12-12 12:12:12+00:00"), length.out=10, by=one_second) idx <- c(as.nanoival("-2012-12-12 12:12:10+00:00 -> 2012-12-12 12:12:14+00:00-"), as.nanoival("+2012-12-12 12:12:18+00:00 -> 2012-12-12 12:12:20+00:00+")) a[idx] intersect(a, idx) ## 'nanoival' also has the set operations 'union', 'intersect', 'setdiff': a <- seq(nanotime("2012-12-12 12:12:12+00:00"), length.out=10, by=one_second) i <- as.nanoival("-2012-12-12 12:12:14+00:00 -> 2012-12-12 12:12:18+00:00-") setdiff(a, i) i1 <- as.nanoival("+2012-12-12 12:12:14+00:00 -> 2012-12-12 12:12:17+00:00-") i2 <- as.nanoival("+2012-12-12 12:12:16+00:00 -> 2012-12-12 12:12:18+00:00-") union(i1, i2) ## 'intersect.idx' returns the indices of the intersection: a <- seq(nanotime("2012-12-12 12:12:12+00:00"), length.out=10, by=one_second) idx <- as.nanoival("+2012-12-12 12:12:14+00:00 -> 2012-12-12 12:12:19+00:00+") idx_intersect <- intersect.idx(a, idx) ## Intersection can be performed using these indices: a[idx_intersect$x] ## which is equivalent to: a[idx] ## The logical vector indicating intersection can be obtained like this: a %in% idx ## End(Not run)
## Not run: ## a vector of 'nanotime' can be subsetted by a 'nanoival' which is equivalent to 'intersect': one_second <- 1e9 a <- seq(nanotime("2012-12-12 12:12:12+00:00"), length.out=10, by=one_second) idx <- c(as.nanoival("-2012-12-12 12:12:10+00:00 -> 2012-12-12 12:12:14+00:00-"), as.nanoival("+2012-12-12 12:12:18+00:00 -> 2012-12-12 12:12:20+00:00+")) a[idx] intersect(a, idx) ## 'nanoival' also has the set operations 'union', 'intersect', 'setdiff': a <- seq(nanotime("2012-12-12 12:12:12+00:00"), length.out=10, by=one_second) i <- as.nanoival("-2012-12-12 12:12:14+00:00 -> 2012-12-12 12:12:18+00:00-") setdiff(a, i) i1 <- as.nanoival("+2012-12-12 12:12:14+00:00 -> 2012-12-12 12:12:17+00:00-") i2 <- as.nanoival("+2012-12-12 12:12:16+00:00 -> 2012-12-12 12:12:18+00:00-") union(i1, i2) ## 'intersect.idx' returns the indices of the intersection: a <- seq(nanotime("2012-12-12 12:12:12+00:00"), length.out=10, by=one_second) idx <- as.nanoival("+2012-12-12 12:12:14+00:00 -> 2012-12-12 12:12:19+00:00+") idx_intersect <- intersect.idx(a, idx) ## Intersection can be performed using these indices: a[idx_intersect$x] ## which is equivalent to: a[idx] ## The logical vector indicating intersection can be obtained like this: a %in% idx ## End(Not run)
nanoival
vector is Not SortedTest if an object is not sorted (in increasing order), without the cost of sorting it.
## S4 method for signature 'nanoival' is.unsorted(x, na.rm = FALSE, strictly = FALSE)
## S4 method for signature 'nanoival' is.unsorted(x, na.rm = FALSE, strictly = FALSE)
x |
a |
na.rm |
logical. Should missing values be removed before checking? |
strictly |
logical indicating if the check should be for _strictly_ increasing values. |
nanotime
typeThe functions nano_floor
and nano_ceiling
round down or up, respectively. Although
the underlying implementation of nanotime
has negative numbers for values before
1970-01-01 UTC, the rounding is always done backward in time for nano_floor
and forward
in time for nano_ceiling
. The functions take a nanotime
argument x
which is
the instance to round, together with a second argument precision
which indicates an
arbitrary precision to which the rounding should be performed. This argument can be either a
nanoduration
or or a nanoperiod
. In the latter case, the argument tz
must
also be specified in order to give the nanoperiod
a meaning. Finally, the nanotime
argument origin
can be optionally specified to fix the rounding to a specific point in
time.
nano_ceiling(x, precision, ...) nano_floor(x, precision, ...) ## S4 method for signature 'nanotime,nanoduration' nano_ceiling(x, precision, origin = nanotime()) ## S4 method for signature 'nanotime,nanoduration' nano_floor(x, precision, origin = nanotime()) ## S4 method for signature 'nanotime,nanoperiod' nano_ceiling(x, precision, origin = nanotime(), tz) ## S4 method for signature 'nanotime,nanoperiod' nano_floor(x, precision, origin = nanotime(), tz)
nano_ceiling(x, precision, ...) nano_floor(x, precision, ...) ## S4 method for signature 'nanotime,nanoduration' nano_ceiling(x, precision, origin = nanotime()) ## S4 method for signature 'nanotime,nanoduration' nano_floor(x, precision, origin = nanotime()) ## S4 method for signature 'nanotime,nanoperiod' nano_ceiling(x, precision, origin = nanotime(), tz) ## S4 method for signature 'nanotime,nanoperiod' nano_floor(x, precision, origin = nanotime(), tz)
x |
a |
precision |
a |
... |
for future additional arguments |
origin |
a |
tz |
a |
This flexible rounding must be understood in the context of a vector. The rounding precision can
then be considered as an interval that defines a grid over which the elements are either
assigned to the starting value of the interval to which they belong (nano_floor
) or the
ending value of the interval to which they belong (nano_ceiling
). This allows for a
grouping of a nanotime
vector on which a statistic may then be run. In the examples
below, such a use case is shown in the context of a data.table
object.
If "business" concepts such as month or days are needed, the argument
precision must be
of type period
. It is then mandatory to specify the timezone argument tz
as this
ensures timezone correctness of the intervals including for example for the rare hourly
transitions of some countries going from a timezone with a whole hour difference with UTC to one
with a fractional hour difference. In the case of a period
, the functions align the
rounding if the precision is an integer divisor of a larger quantity. For instance, if one
specifies a rounding of 6 hours, a divisor of a day, the hours are aligned on days and the
rounding is made to a grid at hours 0, 6, 12 and 18 in the specified timezone. If the precision
is not a divisor, the grid is aligned to the nearest hour before the first element of the vector
to round.
The argument origin
controls the reference point of the rounding, allowing arbitrary
specification of the reference point of the rounding.
## Not run: ## "classic" rounding: nano_floor(as.nanotime("2010-10-10 11:12:15 UTC"), as.nanoduration("01:00:00")) ## rounding with arbitrary precision: nano_floor(as.nanotime("2010-10-10 11:12:15 UTC"), as.nanoduration("06:00:00")) nano_floor(as.nanotime("2010-10-10 11:23:15 UTC"), as.nanoduration("00:15:00")) nano_ceiling(as.nanotime("2010-10-10 11:23:15 UTC"), as.nanoduration("01:15:23")) ## controlling the reference point via the 'origin' argument: nano_ceiling(as.nanotime("2010-10-10 11:23:15 UTC"), as.nanoduration("01:15:23"), origin=as.nanotime("2010-10-10 11:23:15 UTC")) ## using business concepts and rounding across a daylight saving change: v <- seq(as.nanotime("2020-03-08 America/New_York"), by=as.nanoperiod("06:00:00"), length.out=8, tz="America/New_York") print(nano_floor(v, as.nanoperiod("1d"), tz="America/New_York"), tz="America/New_York") ## using the concept in a 'data.table': library(data.table) n <- 3 * 24 idx <- seq(as.nanotime("2020-03-07 America/New_York"), by=as.nanoperiod("01:00:00"), length.out=n, tz="America/New_York") dt <- data.table(idx, a=1:n, b=2:(n+1)) dt_mean <- dt[, list(mean = mean(a)), by=nano_ceiling(idx, as.nanoperiod("1d"), tz="America/New_York")] ## End(Not run)
## Not run: ## "classic" rounding: nano_floor(as.nanotime("2010-10-10 11:12:15 UTC"), as.nanoduration("01:00:00")) ## rounding with arbitrary precision: nano_floor(as.nanotime("2010-10-10 11:12:15 UTC"), as.nanoduration("06:00:00")) nano_floor(as.nanotime("2010-10-10 11:23:15 UTC"), as.nanoduration("00:15:00")) nano_ceiling(as.nanotime("2010-10-10 11:23:15 UTC"), as.nanoduration("01:15:23")) ## controlling the reference point via the 'origin' argument: nano_ceiling(as.nanotime("2010-10-10 11:23:15 UTC"), as.nanoduration("01:15:23"), origin=as.nanotime("2010-10-10 11:23:15 UTC")) ## using business concepts and rounding across a daylight saving change: v <- seq(as.nanotime("2020-03-08 America/New_York"), by=as.nanoperiod("06:00:00"), length.out=8, tz="America/New_York") print(nano_floor(v, as.nanoperiod("1d"), tz="America/New_York"), tz="America/New_York") ## using the concept in a 'data.table': library(data.table) n <- 3 * 24 idx <- seq(as.nanotime("2020-03-07 America/New_York"), by=as.nanoperiod("01:00:00"), length.out=n, tz="America/New_York") dt <- data.table(idx, a=1:n, b=2:(n+1)) dt_mean <- dt[, list(mean = mean(a)), by=nano_ceiling(idx, as.nanoperiod("1d"), tz="America/New_York")] ## End(Not run)
Get a component of a date time. nano_wday
returns the
numeric position in a week, with Sunday == 0. nano_mday
returns the numeric day (i.e. a value from 1 to
31). nano_month
returns the month (i.e. a value from 1 to
12). nano_year
returns the year.
nano_wday(x, tz) nano_mday(x, tz) nano_month(x, tz) nano_year(x, tz)
nano_wday(x, tz) nano_mday(x, tz) nano_month(x, tz) nano_year(x, tz)
x |
a |
tz |
|
Note that the tz
parameter is mandatory because the day
boundary is different depending on the time zone and
nanotime
does not store the timezone as it is just an
offset in nanoseconds from the epoch.
## Not run: nano_wday(as.nanotime("2020-03-14 23:32:00-04:00"), "America/New_York") nano_wday(as.nanotime("2020-03-14 23:32:00 America/New_York"), "Europe/Paris") nano_mday(as.nanotime("2020-03-14 23:32:00-04:00"), "America/New_York") nano_mday(as.nanotime("2020-03-14 23:32:00 America/New_York"), "Europe/Paris") nano_month(as.nanotime("2020-12-31 23:32:00-04:00"), "America/New_York") nano_month(as.nanotime("2020-12-31 23:32:00 America/New_York"), "Europe/Paris") nano_year(as.nanotime("2020-12-31 23:32:00-04:00"), "America/New_York") nano_year(as.nanotime("2020-12-31 23:32:00 America/New_York"), "Europe/Paris") ## End(Not run)
## Not run: nano_wday(as.nanotime("2020-03-14 23:32:00-04:00"), "America/New_York") nano_wday(as.nanotime("2020-03-14 23:32:00 America/New_York"), "Europe/Paris") nano_mday(as.nanotime("2020-03-14 23:32:00-04:00"), "America/New_York") nano_mday(as.nanotime("2020-03-14 23:32:00 America/New_York"), "Europe/Paris") nano_month(as.nanotime("2020-12-31 23:32:00-04:00"), "America/New_York") nano_month(as.nanotime("2020-12-31 23:32:00 America/New_York"), "Europe/Paris") nano_year(as.nanotime("2020-12-31 23:32:00-04:00"), "America/New_York") nano_year(as.nanotime("2020-12-31 23:32:00 America/New_York"), "Europe/Paris") ## End(Not run)
The type nanoduration
is a length of time (implemented as
an S4 class) with nanosecond precision. It is a count of
nanoseconds and may be negative. The expected arithmetic
operations are provided, including sequence generation.
nanoduration(hours = 0L, minutes = 0L, seconds = 0L, nanoseconds = 0L) ## S4 method for signature 'character' as.nanoduration(x) ## S4 method for signature 'integer64' as.nanoduration(x) ## S4 method for signature 'numeric' as.nanoduration(x) ## S4 method for signature 'integer' as.nanoduration(x) ## S4 method for signature 'difftime' as.nanoduration(x) ## S4 method for signature ''NULL'' as.nanoduration(x) ## S4 method for signature 'missing' as.nanoduration(x) ## S4 method for signature 'nanoduration' show(object) ## S4 method for signature 'nanoduration' print(x, quote = FALSE, ...) ## S3 method for class 'nanoduration' format(x, ...) ## S3 method for class 'nanoduration' as.integer64(x, ...) ## S4 method for signature 'nanoduration' as.character(x) ## S4 method for signature 'nanoduration' is.na(x) ## S4 method for signature 'nanoduration,nanoduration' e1 - e2 ## S4 method for signature 'nanoduration,integer64' e1 - e2 ## S4 method for signature 'nanoduration,integer' e1 - e2 ## S4 method for signature 'nanoduration,numeric' e1 - e2 ## S4 method for signature 'nanoduration,difftime' e1 - e2 ## S4 method for signature 'nanoduration,ANY' e1 - e2 ## S4 method for signature 'nanotime,nanoduration' e1 - e2 ## S4 method for signature 'nanotime,difftime' e1 - e2 ## S4 method for signature 'integer64,nanoduration' e1 - e2 ## S4 method for signature 'integer,nanoduration' e1 - e2 ## S4 method for signature 'numeric,nanoduration' e1 - e2 ## S4 method for signature 'difftime,nanoduration' e1 - e2 ## S4 method for signature 'ANY,nanoduration' e1 - e2 ## S4 method for signature 'nanoduration,ANY' e1 + e2 ## S4 method for signature 'nanoduration,nanoduration' e1 + e2 ## S4 method for signature 'nanoduration,integer64' e1 + e2 ## S4 method for signature 'nanoduration,numeric' e1 + e2 ## S4 method for signature 'nanoduration,difftime' e1 + e2 ## S4 method for signature 'nanotime,nanoduration' e1 + e2 ## S4 method for signature 'nanotime,difftime' e1 + e2 ## S4 method for signature 'nanoduration,nanotime' e1 + e2 ## S4 method for signature 'difftime,nanotime' e1 + e2 ## S4 method for signature 'nanoival,nanoduration' e1 + e2 ## S4 method for signature 'nanoival,nanoduration' e1 - e2 ## S4 method for signature 'nanoduration,nanoival' e1 + e2 ## S4 method for signature 'nanoival,difftime' e1 + e2 ## S4 method for signature 'nanoival,difftime' e1 - e2 ## S4 method for signature 'difftime,nanoival' e1 + e2 ## S4 method for signature 'integer64,nanoduration' e1 + e2 ## S4 method for signature 'numeric,nanoduration' e1 + e2 ## S4 method for signature 'difftime,nanoduration' e1 + e2 ## S4 method for signature 'nanoduration,numeric' e1 * e2 ## S4 method for signature 'nanoduration,integer64' e1 * e2 ## S4 method for signature 'numeric,nanoduration' e1 * e2 ## S4 method for signature 'integer64,nanoduration' e1 * e2 ## S4 method for signature 'nanoduration,nanoduration' e1 / e2 ## S4 method for signature 'nanoduration,integer64' e1 / e2 ## S4 method for signature 'nanoduration,numeric' e1 / e2 ## S4 method for signature 'nanoduration,ANY' Arith(e1, e2) ## S4 method for signature 'nanoduration,character' Compare(e1, e2) ## S4 method for signature 'character,nanoduration' Compare(e1, e2) ## S4 method for signature 'nanoduration,ANY' Compare(e1, e2) ## S4 method for signature 'nanoduration' abs(x) ## S4 method for signature 'nanoduration' sign(x) ## S4 method for signature 'nanoduration' sum(x, ..., na.rm = FALSE) ## S4 method for signature 'nanoduration' min(x, ..., na.rm = FALSE) ## S4 method for signature 'nanoduration' max(x, ..., na.rm = FALSE) ## S4 method for signature 'nanoduration' range(x, ..., na.rm = FALSE) ## S4 method for signature 'nanoduration' x[[i, j, ..., drop = FALSE]] ## S4 method for signature 'nanoduration,numeric' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoduration,logical' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoduration,character' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoduration,ANY' x[i, j, ..., drop = FALSE] ## S4 replacement method for signature 'nanoduration,ANY,ANY,ANY' x[i, j, ...] <- value ## S3 method for class 'nanoduration' c(...) NA_nanoduration_
nanoduration(hours = 0L, minutes = 0L, seconds = 0L, nanoseconds = 0L) ## S4 method for signature 'character' as.nanoduration(x) ## S4 method for signature 'integer64' as.nanoduration(x) ## S4 method for signature 'numeric' as.nanoduration(x) ## S4 method for signature 'integer' as.nanoduration(x) ## S4 method for signature 'difftime' as.nanoduration(x) ## S4 method for signature ''NULL'' as.nanoduration(x) ## S4 method for signature 'missing' as.nanoduration(x) ## S4 method for signature 'nanoduration' show(object) ## S4 method for signature 'nanoduration' print(x, quote = FALSE, ...) ## S3 method for class 'nanoduration' format(x, ...) ## S3 method for class 'nanoduration' as.integer64(x, ...) ## S4 method for signature 'nanoduration' as.character(x) ## S4 method for signature 'nanoduration' is.na(x) ## S4 method for signature 'nanoduration,nanoduration' e1 - e2 ## S4 method for signature 'nanoduration,integer64' e1 - e2 ## S4 method for signature 'nanoduration,integer' e1 - e2 ## S4 method for signature 'nanoduration,numeric' e1 - e2 ## S4 method for signature 'nanoduration,difftime' e1 - e2 ## S4 method for signature 'nanoduration,ANY' e1 - e2 ## S4 method for signature 'nanotime,nanoduration' e1 - e2 ## S4 method for signature 'nanotime,difftime' e1 - e2 ## S4 method for signature 'integer64,nanoduration' e1 - e2 ## S4 method for signature 'integer,nanoduration' e1 - e2 ## S4 method for signature 'numeric,nanoduration' e1 - e2 ## S4 method for signature 'difftime,nanoduration' e1 - e2 ## S4 method for signature 'ANY,nanoduration' e1 - e2 ## S4 method for signature 'nanoduration,ANY' e1 + e2 ## S4 method for signature 'nanoduration,nanoduration' e1 + e2 ## S4 method for signature 'nanoduration,integer64' e1 + e2 ## S4 method for signature 'nanoduration,numeric' e1 + e2 ## S4 method for signature 'nanoduration,difftime' e1 + e2 ## S4 method for signature 'nanotime,nanoduration' e1 + e2 ## S4 method for signature 'nanotime,difftime' e1 + e2 ## S4 method for signature 'nanoduration,nanotime' e1 + e2 ## S4 method for signature 'difftime,nanotime' e1 + e2 ## S4 method for signature 'nanoival,nanoduration' e1 + e2 ## S4 method for signature 'nanoival,nanoduration' e1 - e2 ## S4 method for signature 'nanoduration,nanoival' e1 + e2 ## S4 method for signature 'nanoival,difftime' e1 + e2 ## S4 method for signature 'nanoival,difftime' e1 - e2 ## S4 method for signature 'difftime,nanoival' e1 + e2 ## S4 method for signature 'integer64,nanoduration' e1 + e2 ## S4 method for signature 'numeric,nanoduration' e1 + e2 ## S4 method for signature 'difftime,nanoduration' e1 + e2 ## S4 method for signature 'nanoduration,numeric' e1 * e2 ## S4 method for signature 'nanoduration,integer64' e1 * e2 ## S4 method for signature 'numeric,nanoduration' e1 * e2 ## S4 method for signature 'integer64,nanoduration' e1 * e2 ## S4 method for signature 'nanoduration,nanoduration' e1 / e2 ## S4 method for signature 'nanoduration,integer64' e1 / e2 ## S4 method for signature 'nanoduration,numeric' e1 / e2 ## S4 method for signature 'nanoduration,ANY' Arith(e1, e2) ## S4 method for signature 'nanoduration,character' Compare(e1, e2) ## S4 method for signature 'character,nanoduration' Compare(e1, e2) ## S4 method for signature 'nanoduration,ANY' Compare(e1, e2) ## S4 method for signature 'nanoduration' abs(x) ## S4 method for signature 'nanoduration' sign(x) ## S4 method for signature 'nanoduration' sum(x, ..., na.rm = FALSE) ## S4 method for signature 'nanoduration' min(x, ..., na.rm = FALSE) ## S4 method for signature 'nanoduration' max(x, ..., na.rm = FALSE) ## S4 method for signature 'nanoduration' range(x, ..., na.rm = FALSE) ## S4 method for signature 'nanoduration' x[[i, j, ..., drop = FALSE]] ## S4 method for signature 'nanoduration,numeric' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoduration,logical' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoduration,character' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoduration,ANY' x[i, j, ..., drop = FALSE] ## S4 replacement method for signature 'nanoduration,ANY,ANY,ANY' x[i, j, ...] <- value ## S3 method for class 'nanoduration' c(...) NA_nanoduration_
hours |
number of hours |
minutes |
number of minutes |
seconds |
number of seconds |
nanoseconds |
number of nanoseconds |
x |
a |
object |
argument for method |
quote |
indicates if the output of |
... |
further arguments passed to or from methods. |
e1 |
Operand of class |
e2 |
Operand of class |
na.rm |
if |
i |
index specifying elements to extract or replace. |
j |
Required for |
drop |
Required for |
value |
argument for |
An object of class nanoduration
of length 1.
A nanoduration
can be constructed with the function
as.nanoduration
which can take the types integer64
,
integer
and numeric
(all indicating the count in
nanosecond units) or the type character
.
It can also be constructed by specifying with individual arguments
the hours, minutes, seconds and nanoseconds with a call to
nanoduration
.
A nanoduration
is displayed as hours, minutes, seconds and
nanoseconds like this: 110:12:34.123_453_001
. The nanosecond
precision displayed is adjusted as necessary, so e.g. 1 second is
displayed as 00:00:01
.
A nanoduration object
Dirk Eddelbuettel
Leonardo Silvestri
## constructors: nanoduration(hours=10, minutes=3, seconds=2, nanoseconds=999999999) as.nanoduration("10:03:02.999_999_999") as.nanoduration(36182999999999) ## arithmetic: as.nanoduration(10e9) - as.nanoduration(9e9) as.nanoduration(10e9) + as.nanoduration(-9e9) as.nanoduration("24:00:00") / 2 as.nanoduration("24:00:00") / as.nanoduration("12:00:00") ## comparison: as.nanoduration("10:03:02.999_999_999") == 36182999999999 as.nanoduration("10:03:02.999_999_999") > as.nanoduration("10:03:02.999_999_998") as.nanoduration("10:03:02.999_999_998") < "10:03:02.999_999_999"
## constructors: nanoduration(hours=10, minutes=3, seconds=2, nanoseconds=999999999) as.nanoduration("10:03:02.999_999_999") as.nanoduration(36182999999999) ## arithmetic: as.nanoduration(10e9) - as.nanoduration(9e9) as.nanoduration(10e9) + as.nanoduration(-9e9) as.nanoduration("24:00:00") / 2 as.nanoduration("24:00:00") / as.nanoduration("12:00:00") ## comparison: as.nanoduration("10:03:02.999_999_999") == 36182999999999 as.nanoduration("10:03:02.999_999_999") > as.nanoduration("10:03:02.999_999_998") as.nanoduration("10:03:02.999_999_998") < "10:03:02.999_999_999"
nanoival
is a time interval type (an S4 class) with
nanosecond precision. One of its purposes is to allow quick
subsetting of a nanotime
vector. nanoival
is
composed of a nanotime
pair which defines the start and end
of the time interval. Additionally, it has a pair of logical
values which determine if the start and end of the time interval
are open (true) or closed (false).
nanoival(start, end, sopen = FALSE, eopen = TRUE) ## S4 method for signature 'nanoival' nanoival.start(x) ## S4 method for signature 'nanoival' nanoival.end(x) ## S4 method for signature 'nanoival' nanoival.sopen(x) ## S4 method for signature 'nanoival' nanoival.eopen(x) ## S3 method for class 'nanoival' format(x, ...) ## S4 method for signature 'nanoival' print(x, quote = FALSE, ...) ## S4 method for signature 'nanoival' show(object) ## S4 method for signature 'character' as.nanoival(from, format = "", tz = "") ## S4 method for signature ''NULL'' as.nanoival(from, format = "", tz = "") ## S4 method for signature 'missing' as.nanoival(from, format = "", tz = "") ## S4 method for signature 'nanoival' is.na(x) ## S4 replacement method for signature 'nanoival' is.na(x) <- value ## S4 method for signature 'nanoival,nanoival' e1 < e2 ## S4 method for signature 'nanoival,nanoival' e1 <= e2 ## S4 method for signature 'nanoival,nanoival' e1 > e2 ## S4 method for signature 'nanoival,nanoival' e1 >= e2 ## S4 method for signature 'nanoival,nanoival' e1 == e2 ## S4 method for signature 'nanoival,nanoival' e1 != e2 ## S4 method for signature 'nanoival,integer64' e1 - e2 ## S4 method for signature 'nanoival,numeric' e1 - e2 ## S4 method for signature 'nanoival,integer64' e1 + e2 ## S4 method for signature 'nanoival,numeric' e1 + e2 ## S4 method for signature 'integer64,nanoival' e1 + e2 ## S4 method for signature 'numeric,nanoival' e1 + e2 ## S4 method for signature 'nanoival' x[[i, j, ..., drop = FALSE]] ## S4 method for signature 'nanoival,logical' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoival,numeric' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoival,character' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoival,ANY' x[i, j, ..., drop = FALSE] ## S4 replacement method for signature 'nanoival,logical,ANY,nanoival' x[i, j, ...] <- value ## S3 method for class 'nanoival' c(...) ## S4 method for signature 'nanoival' t(x) ## S4 method for signature 'nanotime,nanoival' x[i, j, ..., drop = TRUE] NA_nanoival_ ## S3 method for class 'nanoival' as.character(x, ...)
nanoival(start, end, sopen = FALSE, eopen = TRUE) ## S4 method for signature 'nanoival' nanoival.start(x) ## S4 method for signature 'nanoival' nanoival.end(x) ## S4 method for signature 'nanoival' nanoival.sopen(x) ## S4 method for signature 'nanoival' nanoival.eopen(x) ## S3 method for class 'nanoival' format(x, ...) ## S4 method for signature 'nanoival' print(x, quote = FALSE, ...) ## S4 method for signature 'nanoival' show(object) ## S4 method for signature 'character' as.nanoival(from, format = "", tz = "") ## S4 method for signature ''NULL'' as.nanoival(from, format = "", tz = "") ## S4 method for signature 'missing' as.nanoival(from, format = "", tz = "") ## S4 method for signature 'nanoival' is.na(x) ## S4 replacement method for signature 'nanoival' is.na(x) <- value ## S4 method for signature 'nanoival,nanoival' e1 < e2 ## S4 method for signature 'nanoival,nanoival' e1 <= e2 ## S4 method for signature 'nanoival,nanoival' e1 > e2 ## S4 method for signature 'nanoival,nanoival' e1 >= e2 ## S4 method for signature 'nanoival,nanoival' e1 == e2 ## S4 method for signature 'nanoival,nanoival' e1 != e2 ## S4 method for signature 'nanoival,integer64' e1 - e2 ## S4 method for signature 'nanoival,numeric' e1 - e2 ## S4 method for signature 'nanoival,integer64' e1 + e2 ## S4 method for signature 'nanoival,numeric' e1 + e2 ## S4 method for signature 'integer64,nanoival' e1 + e2 ## S4 method for signature 'numeric,nanoival' e1 + e2 ## S4 method for signature 'nanoival' x[[i, j, ..., drop = FALSE]] ## S4 method for signature 'nanoival,logical' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoival,numeric' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoival,character' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoival,ANY' x[i, j, ..., drop = FALSE] ## S4 replacement method for signature 'nanoival,logical,ANY,nanoival' x[i, j, ...] <- value ## S3 method for class 'nanoival' c(...) ## S4 method for signature 'nanoival' t(x) ## S4 method for signature 'nanotime,nanoival' x[i, j, ..., drop = TRUE] NA_nanoival_ ## S3 method for class 'nanoival' as.character(x, ...)
start |
|
end |
|
sopen |
logical indicating if the start of the interval is open |
eopen |
logical indicating if the end of the interval is open |
x , from
|
a |
... |
further arguments passed to or from methods. |
quote |
indicates if the output of |
object |
argument for method |
format |
A character string. Can also be set via
|
tz |
|
value |
argument for |
e1 |
Operand of class |
e2 |
Operand of class |
i |
index specifying elements to extract or replace. |
j |
Required for |
drop |
Required for |
An object of class nanoival
of length 1.
An interval object can be constructed with the constructor
nanoival
which takes as arguments two nanotime
objects that define the start and the end of the interval,
together with two logical
arguments that define if the
start and the end of the interval are open (true) or closed
(false) (note that these objects can all be vector, and therefore
the interval object is not necessarily scalar). Alternatively, an
interval can be constructed with a character
: the format
follows that of nanotime
; the start time is preceeded by
either -
or +
indicating if the interval start is
open (-) or closed (+); the start and end times are separated by
an arrow ->
; the end is folloed by either -
or
+
which have the same semantics as the start time.
The most important set of methods defined for interval
are
set functions intersect
, union
and setdiff
.
Additionally, interval
allows the subsetting into a
nanotime
vector. Note that subsetting is allowed only if
the nanotime
vector is sorted.
Finally, accessors are provided to get the interval start
(start
), the end (end
), the open/close status of the
start (sopen
) and the open/close status of the end
(eopen
). The former return a nanotime
while the
latter return a logical
.
A nanoival object
Formatting and character conversion for nanoival
objects is
identical to nanotime
objects. 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
Leonardo Silvestri
## Not run: ## creating a \code{nanoival}, with the start time included ('+') and the end ## time excluded ('-') as.nanoival("+2012-03-01T21:21:00.000000001+00:00->2015-01-01T21:22:00.000000999+04:00-") ## a \code{nanoival} can also be created with a pair of \code{nanotime} objects, a start ## and an end, and optionally two logicals determining if the interval start(end) are open ## or closed; by default the start is closed and end is open: start <- nanotime("2012-03-01T21:21:00.000000001+00:00") end <- nanotime("2013-03-01T21:21:00.000000001+00:00") nanoival(start, end) ## a vector of 'nanotime' can be subsetted by a 'nanoival': one_second <- 1e9 a <- seq(nanotime("2012-12-12 12:12:12+00:00"), length.out=10, by=one_second) idx <- c(as.nanoival("-2012-12-12 12:12:10+00:00 -> 2012-12-12 12:12:14+00:00-"), as.nanoival("+2012-12-12 12:12:18+00:00 -> 2012-12-12 12:12:20+00:00+")) a[idx] ## End(Not run)
## Not run: ## creating a \code{nanoival}, with the start time included ('+') and the end ## time excluded ('-') as.nanoival("+2012-03-01T21:21:00.000000001+00:00->2015-01-01T21:22:00.000000999+04:00-") ## a \code{nanoival} can also be created with a pair of \code{nanotime} objects, a start ## and an end, and optionally two logicals determining if the interval start(end) are open ## or closed; by default the start is closed and end is open: start <- nanotime("2012-03-01T21:21:00.000000001+00:00") end <- nanotime("2013-03-01T21:21:00.000000001+00:00") nanoival(start, end) ## a vector of 'nanotime' can be subsetted by a 'nanoival': one_second <- 1e9 a <- seq(nanotime("2012-12-12 12:12:12+00:00"), length.out=10, by=one_second) idx <- c(as.nanoival("-2012-12-12 12:12:10+00:00 -> 2012-12-12 12:12:14+00:00-"), as.nanoival("+2012-12-12 12:12:18+00:00 -> 2012-12-12 12:12:20+00:00+")) a[idx] ## End(Not run)
nanoperiod
is a length of time type (implemented as an S4
class) with nanosecond precision. It differs from
nanoduration
because it is capable of representing calendar
months and days. It can thus represent years (12 months) and weeks
(7 days). A period is a somewhat abstract representation of time:
it is only when anchored to a point in time and in a specific time
zone that it is possible to convert it to a specific
duration. This means that many of the operations involving periods
need the additional argument tz
.
nanoperiod(months = 0, days = 0, duration = as.nanoduration(0)) ## S4 method for signature 'character' as.nanoperiod(x) ## S4 method for signature 'integer64' as.nanoperiod(x) ## S4 method for signature 'numeric' as.nanoperiod(x) ## S4 method for signature 'integer' as.nanoperiod(x) ## S4 method for signature 'nanoduration' as.nanoperiod(x) ## S4 method for signature ''NULL'' as.nanoperiod(x) ## S4 method for signature 'missing' as.nanoperiod(x) ## S4 method for signature 'nanoperiod' show(object) ## S4 method for signature 'nanoperiod' print(x, quote = FALSE, ...) ## S3 method for class 'nanoperiod' format(x, ...) ## S4 method for signature 'nanoperiod' as.character(x) ## S4 method for signature 'nanoperiod' is.na(x) ## S4 replacement method for signature 'nanoperiod' is.na(x) <- value ## S4 method for signature 'nanoperiod' x[[i, j, ..., drop = FALSE]] ## S4 method for signature 'nanoperiod,numeric' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoperiod,logical' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoperiod,character' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoperiod,ANY' x[i, j, ..., drop = FALSE] ## S4 replacement method for signature 'nanoperiod,ANY,ANY,ANY' x[i, j, ...] <- value ## S3 method for class 'nanoperiod' c(...) ## S4 method for signature 'nanoperiod' names(x) ## S4 replacement method for signature 'nanoperiod' names(x) <- value ## S4 method for signature 'nanoperiod,ANY' e1 - e2 ## S4 method for signature 'nanoperiod,nanoperiod' e1 - e2 ## S4 method for signature 'nanoperiod,nanoduration' e1 - e2 ## S4 method for signature 'nanoperiod,integer64' e1 - e2 ## S4 method for signature 'nanoperiod,numeric' e1 - e2 ## S4 method for signature 'nanoduration,nanoperiod' e1 - e2 ## S4 method for signature 'integer64,nanoperiod' e1 - e2 ## S4 method for signature 'numeric,nanoperiod' e1 - e2 ## S4 method for signature 'nanoperiod,ANY' e1 + e2 ## S4 method for signature 'nanoperiod,nanoperiod' e1 + e2 ## S4 method for signature 'nanoperiod,nanoduration' e1 + e2 ## S4 method for signature 'nanoperiod,integer64' e1 + e2 ## S4 method for signature 'nanoperiod,nanotime' e1 + e2 ## S4 method for signature 'nanoival,nanoperiod' e1 + e2 ## S4 method for signature 'nanoperiod,nanoival' e1 + e2 ## S4 method for signature 'nanotime,nanoperiod' e1 + e2 ## S4 method for signature 'nanoperiod,numeric' e1 + e2 ## S4 method for signature 'nanoduration,nanoperiod' e1 + e2 ## S4 method for signature 'integer64,nanoperiod' e1 + e2 ## S4 method for signature 'numeric,nanoperiod' e1 + e2 ## S4 method for signature 'nanoperiod,integer64' e1 * e2 ## S4 method for signature 'nanoperiod,numeric' e1 * e2 ## S4 method for signature 'integer64,nanoperiod' e1 * e2 ## S4 method for signature 'numeric,nanoperiod' e1 * e2 ## S4 method for signature 'nanoperiod,integer64' e1 / e2 ## S4 method for signature 'nanoperiod,numeric' e1 / e2 ## S4 method for signature 'nanoperiod,nanoperiod' e1 == e2 ## S4 method for signature 'nanoperiod,nanoperiod' e1 != e2 ## S4 method for signature 'nanotime,nanoperiod,character' plus(e1, e2, tz) ## S4 method for signature 'nanoperiod,nanotime,character' plus(e1, e2, tz) ## S4 method for signature 'nanotime,nanoperiod,character' minus(e1, e2, tz) ## S4 method for signature 'nanoperiod,nanotime,character' minus(e1, e2, tz) ## S4 method for signature 'nanoival,nanoperiod,character' plus(e1, e2, tz) ## S4 method for signature 'nanoperiod,nanoival,character' plus(e1, e2, tz) ## S4 method for signature 'nanoival,nanoperiod,character' minus(e1, e2, tz) NA_nanoperiod_
nanoperiod(months = 0, days = 0, duration = as.nanoduration(0)) ## S4 method for signature 'character' as.nanoperiod(x) ## S4 method for signature 'integer64' as.nanoperiod(x) ## S4 method for signature 'numeric' as.nanoperiod(x) ## S4 method for signature 'integer' as.nanoperiod(x) ## S4 method for signature 'nanoduration' as.nanoperiod(x) ## S4 method for signature ''NULL'' as.nanoperiod(x) ## S4 method for signature 'missing' as.nanoperiod(x) ## S4 method for signature 'nanoperiod' show(object) ## S4 method for signature 'nanoperiod' print(x, quote = FALSE, ...) ## S3 method for class 'nanoperiod' format(x, ...) ## S4 method for signature 'nanoperiod' as.character(x) ## S4 method for signature 'nanoperiod' is.na(x) ## S4 replacement method for signature 'nanoperiod' is.na(x) <- value ## S4 method for signature 'nanoperiod' x[[i, j, ..., drop = FALSE]] ## S4 method for signature 'nanoperiod,numeric' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoperiod,logical' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoperiod,character' x[i, j, ..., drop = FALSE] ## S4 method for signature 'nanoperiod,ANY' x[i, j, ..., drop = FALSE] ## S4 replacement method for signature 'nanoperiod,ANY,ANY,ANY' x[i, j, ...] <- value ## S3 method for class 'nanoperiod' c(...) ## S4 method for signature 'nanoperiod' names(x) ## S4 replacement method for signature 'nanoperiod' names(x) <- value ## S4 method for signature 'nanoperiod,ANY' e1 - e2 ## S4 method for signature 'nanoperiod,nanoperiod' e1 - e2 ## S4 method for signature 'nanoperiod,nanoduration' e1 - e2 ## S4 method for signature 'nanoperiod,integer64' e1 - e2 ## S4 method for signature 'nanoperiod,numeric' e1 - e2 ## S4 method for signature 'nanoduration,nanoperiod' e1 - e2 ## S4 method for signature 'integer64,nanoperiod' e1 - e2 ## S4 method for signature 'numeric,nanoperiod' e1 - e2 ## S4 method for signature 'nanoperiod,ANY' e1 + e2 ## S4 method for signature 'nanoperiod,nanoperiod' e1 + e2 ## S4 method for signature 'nanoperiod,nanoduration' e1 + e2 ## S4 method for signature 'nanoperiod,integer64' e1 + e2 ## S4 method for signature 'nanoperiod,nanotime' e1 + e2 ## S4 method for signature 'nanoival,nanoperiod' e1 + e2 ## S4 method for signature 'nanoperiod,nanoival' e1 + e2 ## S4 method for signature 'nanotime,nanoperiod' e1 + e2 ## S4 method for signature 'nanoperiod,numeric' e1 + e2 ## S4 method for signature 'nanoduration,nanoperiod' e1 + e2 ## S4 method for signature 'integer64,nanoperiod' e1 + e2 ## S4 method for signature 'numeric,nanoperiod' e1 + e2 ## S4 method for signature 'nanoperiod,integer64' e1 * e2 ## S4 method for signature 'nanoperiod,numeric' e1 * e2 ## S4 method for signature 'integer64,nanoperiod' e1 * e2 ## S4 method for signature 'numeric,nanoperiod' e1 * e2 ## S4 method for signature 'nanoperiod,integer64' e1 / e2 ## S4 method for signature 'nanoperiod,numeric' e1 / e2 ## S4 method for signature 'nanoperiod,nanoperiod' e1 == e2 ## S4 method for signature 'nanoperiod,nanoperiod' e1 != e2 ## S4 method for signature 'nanotime,nanoperiod,character' plus(e1, e2, tz) ## S4 method for signature 'nanoperiod,nanotime,character' plus(e1, e2, tz) ## S4 method for signature 'nanotime,nanoperiod,character' minus(e1, e2, tz) ## S4 method for signature 'nanoperiod,nanotime,character' minus(e1, e2, tz) ## S4 method for signature 'nanoival,nanoperiod,character' plus(e1, e2, tz) ## S4 method for signature 'nanoperiod,nanoival,character' plus(e1, e2, tz) ## S4 method for signature 'nanoival,nanoperiod,character' minus(e1, e2, tz) NA_nanoperiod_
months |
Used in the constructor to indicate the number of
months of the |
days |
Used in the constructor to indicate the number of
days of the |
duration |
Used in the constructor to indicate the duration
component of the |
x , value
|
An object of class |
object |
argument for method |
quote |
indicates if the output of |
... |
further arguments |
i |
index specifying elements to extract or replace. |
j |
Required for |
drop |
Required for |
e1 |
Operand of class |
e2 |
Operand of class |
tz |
|
An object of class nanoperiod
of length 1.
The true constructor is
A nanoperiod
is displayed as months, days, and nanoduration
like this: 10m2d/10:12:34.123_453_000
.
Adding or subtracting nanoperiod
and nanotime
require a timezone as third argument. For this reason it is not
possible to use the binary operator '+
'. Instead the
functions 'plus
' and 'minus
' are defined. These
functions attempt to keep the same offset within a day in the
specified timezone: this means for instance that adding a day when
that day crosses a time zone adjustment such as a daylight saving
time, results in a true time increment of less or more than 24
hours to preserve the offset. Preserving the offset works for
increments that are smaller than a day too, provided the increment
results in a datetime where the timezone adjustment is valid. When
this is not the case, adding a 'nanoperiod' behaves in the same
way as adding a 'nanoduration'.
Dirk Eddelbuettel
Leonardo Silvestri
nanotime
, nanoduration
,
nanoival
, nanoperiod.month,nanoperiod-method
## Not run: p <- nanoperiod(months=12, days=7, duration="01:00:00") print(p) # when adding a \code{nanoperiod} to a \code{nanotime} or to a # \code{nanoival}, a time zone must be specified: y <- nanotime("1970-01-01T00:00:00+00:00") plus(y, p, tz="America/Chicago") ## End(Not run)
## Not run: p <- nanoperiod(months=12, days=7, duration="01:00:00") print(p) # when adding a \code{nanoperiod} to a \code{nanotime} or to a # \code{nanoival}, a time zone must be specified: y <- nanotime("1970-01-01T00:00:00+00:00") plus(y, p, tz="America/Chicago") ## End(Not run)
These functions allow access to the components of a nanoperiod
## S4 method for signature 'nanoperiod' nanoperiod.month(x) ## S4 method for signature 'nanoperiod' nanoperiod.day(x) ## S4 method for signature 'nanoperiod' nanoperiod.nanoduration(x)
## S4 method for signature 'nanoperiod' nanoperiod.month(x) ## S4 method for signature 'nanoperiod' nanoperiod.day(x) ## S4 method for signature 'nanoperiod' nanoperiod.nanoduration(x)
x |
A |
nanoperiod.month
and nanoperiod.day
return
an integer64
whereas nanoperiod.nanoduration
returns a nanoduration
Dirk Eddelbuettel
Leonardo Silvestri
p <- as.nanoperiod("2y1m1d/12:00:00") nanoperiod.month(p) nanoperiod.day(p) nanoperiod.nanoduration(p)
p <- as.nanoperiod("2y1m1d/12:00:00") nanoperiod.month(p) nanoperiod.day(p) nanoperiod.nanoduration(p)
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.
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, accurate = TRUE) ## S4 method for signature 'POSIXct' as.nanotime(from, accurate = TRUE) ## 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 'nanotime' as.character(x, ...) ## S3 method for class 'nanoduration' as.data.frame(x, ...)
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, accurate = TRUE) ## S4 method for signature 'POSIXct' as.nanotime(from, accurate = TRUE) ## 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 'nanotime' as.character(x, ...) ## S3 method for class 'nanoduration' as.data.frame(x, ...)
... |
further arguments passed to or from methods. |
format |
A character string. Can also be set via
|
tz |
character specifying a timezone which is required for
|
x , from
|
|
accurate |
in the conversion from |
quote |
indicates if the output of |
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 |
An object of class nanotime
of length 1.
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 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.
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 constructorsThe 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.
Dirk Eddelbuettel
Leonardo Silvestri
nanoival
, nanoduration
,
nanoperiod
, seq.nanotime
as well as
the documentation in package RcppCCTZ.
## Not run: 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") as.nanotime("2020-03-10T040947190301440", format="%Y-%m-%dT%H%M%S%E*f") 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") ## End(Not run)
## Not run: 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") as.nanotime("2020-03-10T040947190301440", format="%Y-%m-%dT%H%M%S%E*f") 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") ## End(Not run)
Replicates the values in 'x' similarly to the default method.
## S4 method for signature 'nanoduration' rep(x, ...)
## S4 method for signature 'nanoduration' rep(x, ...)
x |
a vector of |
... |
further arguments: 'times' an integer-valued vector giving the (non-negative) number of times to repeat each element if of length 'length(x)', or to repeat the whole vector if of length 1. Negative or 'NA' values are an error. A 'double' vector is accepted, other inputs being coerced to an integer or double vector. 'length.out' non-negative integer. The desired length of the output vector. Other inputs will be coerced to a double vector and the first element taken. Ignored if 'NA' or invalid. 'each' non-negative integer. Each element of 'x' is repeated 'each' times. Other inputs will be coerced to an integer or double vector and the first element taken. Treated as '1' if 'NA' or invalid. |
Replicates the values in 'x' similarly to the default method.
## S4 method for signature 'nanoival' rep(x, ...)
## S4 method for signature 'nanoival' rep(x, ...)
x |
a vector of |
... |
further arguments: 'times' an integer-valued vector giving the (non-negative) number of times to repeat each element if of length 'length(x)', or to repeat the whole vector if of length 1. Negative or 'NA' values are an error. A 'double' vector is accepted, other inputs being coerced to an integer or double vector. 'length.out' non-negative integer. The desired length of the output vector. Other inputs will be coerced to a double vector and the first element taken. Ignored if 'NA' or invalid. 'each' non-negative integer. Each element of 'x' is repeated 'each' times. Other inputs will be coerced to an integer or double vector and the first element taken. Treated as '1' if 'NA' or invalid. |
Replicates the values in 'x' similarly to the default method.
## S4 method for signature 'nanoperiod' rep(x, ...)
## S4 method for signature 'nanoperiod' rep(x, ...)
x |
a vector of |
... |
further arguments: 'times' an integer-valued vector giving the (non-negative) number of times to repeat each element if of length 'length(x)', or to repeat the whole vector if of length 1. Negative or 'NA' values are an error. A 'double' vector is accepted, other inputs being coerced to an integer or double vector. 'length.out' non-negative integer. The desired length of the output vector. Other inputs will be coerced to a double vector and the first element taken. Ignored if 'NA' or invalid. 'each' non-negative integer. Each element of 'x' is repeated 'each' times. Other inputs will be coerced to an integer or double vector and the first element taken. Treated as '1' if 'NA' or invalid. |
Replicates the values in 'x' similarly to the default method.
## S4 method for signature 'nanotime' rep(x, ...)
## S4 method for signature 'nanotime' rep(x, ...)
x |
a vector of |
... |
further arguments: 'times' an integer-valued vector giving the (non-negative) number of times to repeat each element if of length 'length(x)', or to repeat the whole vector if of length 1. Negative or 'NA' values are an error. A 'double' vector is accepted, other inputs being coerced to an integer or double vector. 'length.out' non-negative integer. The desired length of the output vector. Other inputs will be coerced to a double vector and the first element taken. Ignored if 'NA' or invalid. 'each' non-negative integer. Each element of 'x' is repeated 'each' times. Other inputs will be coerced to an integer or double vector and the first element taken. Treated as '1' if 'NA' or invalid. |
Generate a sequence of nanoival
## S4 method for signature 'nanoival' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S4 method for signature 'nanoival' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from , to
|
the starting and (maximal) end values of the sequence |
by |
|
length.out |
an integer desired length of the sequence |
along.with |
take the length from the length of this argument. |
... |
arguments passed to or from methods; the only
interesting additional argument is |
## Not run: from <- as.nanoival("-2018-01-14T13:00:00+00:00 -> 2018-01-14T15:00:00+00:00+") seq(from, by=as.nanoperiod("1m"), length.out=5, tz="America/New_York") ## End(Not run)
## Not run: from <- as.nanoival("-2018-01-14T13:00:00+00:00 -> 2018-01-14T15:00:00+00:00+") seq(from, by=as.nanoperiod("1m"), length.out=5, tz="America/New_York") ## End(Not run)
Generate a sequence of nanoduration
## S3 method for class 'nanoduration' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S3 method for class 'nanoduration' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from , to
|
the starting and (maximal) end values of the sequence |
by |
the increment of the sequence |
length.out |
integer indicating the desired length of the sequence |
along.with |
take the length from the length of this argument. |
... |
arguments passed to or from methods |
seq(from=as.nanoduration(0), by=as.nanoduration("01:00:00"), length.out=10)
seq(from=as.nanoduration(0), by=as.nanoduration("01:00:00"), length.out=10)
Generate a sequence of nanotime
## S3 method for class 'nanotime' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...) ## S4 method for signature 'nanotime' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
## S3 method for class 'nanotime' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...) ## S4 method for signature 'nanotime' seq(from, to = NULL, by = NULL, length.out = NULL, along.with = NULL, ...)
from , to
|
the starting and (maximal) end values of the sequence |
by |
|
length.out |
integer indicating the desired length of the sequence |
along.with |
take the length from the length of this argument. |
... |
arguments passed to or from methods; the only
interesting additional argument is |
## Not run: from <- as.nanotime("2018-01-14T12:44:00+00:00") to <- as.nanotime("2019-01-14T12:44:00+00:00") seq(from, to, by=as.nanoperiod("1m"), tz="America/New_York") seq(from, by=as.nanoperiod("1y"), length.out=4, tz="Europe/London") ## End(Not run)
## Not run: from <- as.nanotime("2018-01-14T12:44:00+00:00") to <- as.nanotime("2019-01-14T12:44:00+00:00") seq(from, to, by=as.nanoperiod("1m"), tz="America/New_York") seq(from, by=as.nanoperiod("1y"), length.out=4, tz="Europe/London") ## End(Not run)
Sort (or _order_) a vector of nanoival
into ascending or
descending order
## S4 method for signature 'nanoival' sort(x, decreasing = FALSE)
## S4 method for signature 'nanoival' sort(x, decreasing = FALSE)
x |
a vector of |
decreasing |
logical. Should the sort be increasing or decreasing? |