{"id":16572081,"url":"https://github.com/eddelbuettel/nanotime","last_synced_at":"2025-03-21T20:10:07.184Z","repository":{"id":14172192,"uuid":"76090533","full_name":"eddelbuettel/nanotime","owner":"eddelbuettel","description":"Nanosecond Resolution Time Functionality for R","archived":false,"fork":false,"pushed_at":"2024-09-16T12:54:56.000Z","size":2716,"stargazers_count":52,"open_issues_count":1,"forks_count":6,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-12T21:26:15.512Z","etag":null,"topics":["cran","datetime","datetimes","nanosecond-resolution","nanoseconds","r","r-package"],"latest_commit_sha":null,"homepage":"https://eddelbuettel.github.io/nanotime","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eddelbuettel.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-10T04:31:34.000Z","updated_at":"2024-09-16T12:54:59.000Z","dependencies_parsed_at":"2024-06-16T20:31:36.683Z","dependency_job_id":"18346276-126d-4f0b-a6e1-9f53e6aa2a41","html_url":"https://github.com/eddelbuettel/nanotime","commit_stats":{"total_commits":284,"total_committers":7,"mean_commits":40.57142857142857,"dds":"0.28521126760563376","last_synced_commit":"0beec0c0975b24f085b16184756badbd41d6d74a"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddelbuettel%2Fnanotime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddelbuettel%2Fnanotime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddelbuettel%2Fnanotime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddelbuettel%2Fnanotime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eddelbuettel","download_url":"https://codeload.github.com/eddelbuettel/nanotime/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244860584,"owners_count":20522464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cran","datetime","datetimes","nanosecond-resolution","nanoseconds","r","r-package"],"created_at":"2024-10-11T21:26:17.355Z","updated_at":"2025-03-21T20:10:07.141Z","avatar_url":"https://github.com/eddelbuettel.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"## nanotime: Nanosecond-Resolution Time Objects for R\n\n[![CI](https://github.com/eddelbuettel/nanotime/workflows/ci/badge.svg)](https://github.com/eddelbuettel/nanotime/actions?query=workflow%3Aci)\n[![License](https://eddelbuettel.github.io/badges/GPL2+.svg)](https://www.gnu.org/licenses/gpl-2.0.html)\n[![CRAN](https://www.r-pkg.org/badges/version/nanotime)](https://cran.r-project.org/package=nanotime)\n[![r-universe](https://eddelbuettel.r-universe.dev/badges/nanotime)](https://eddelbuettel.r-universe.dev/nanotime)\n[![Dependencies](https://tinyverse.netlify.app/badge/nanotime)](https://cran.r-project.org/package=nanotime)\n[![Downloads](https://cranlogs.r-pkg.org/badges/nanotime?color=brightgreen)](https://www.r-pkg.org/pkg/nanotime)\n[![Code Coverage](https://codecov.io/gh/eddelbuettel/nanotime/graph/badge.svg)](https://app.codecov.io/gh/eddelbuettel/nanotime)\n[![Last Commit](https://img.shields.io/github/last-commit/eddelbuettel/nanotime)](https://github.com/eddelbuettel/nanotime)\n[![Documentation](https://img.shields.io/badge/documentation-is_here-blue)](https://eddelbuettel.github.io/nanotime/)\n\n### Motivation\n\nR has excellent tools for dates and times. The `Date` and `POSIXct` classes (as well as the 'wide'\nrepresentation in `POSIXlt`) are versatile, and a lot of useful tooling has been built around them.\n\nHowever, `POSIXct` is implemented as a `double` with fractional seconds since the epoch. Given the\n53 bits accuracy, it leaves just a bit less than _microsecond_ resolution. Furthermore, using\nfloating-point arithmetic for an integer concept opens the door to painful issues of error\naccumulation.\n\nMore and more performance measurements, latency statistics, etc., are now measured more finely, and we\nneed _nanosecond_ resolution for which commonly an `integer64` is used to represent nanoseconds\nsince the epoch.\n\nAnd while R does not have a _native_ type for this, the [bit64](https://cran.r-project.org/package=bit64)\npackage by [Jens Oehlschlägel](https://github.com/joehl) offers a performant one implemented as a\nlightweight S3 class. So this package uses the `integer64` class, along with multiple helper functions\nfor parsing and formatting at nano-second resolution from the [RcppCCTZ](https://dirk.eddelbuettel.com/code/rcpp.cctz.html)\npackage which wraps the [CCTZ library](https://github.com/google/cctz) from Google. CCTZ is a modern C++11 library\nextending the (C++11-native) `chrono` type.\n\nIn addition to the point-in-time type `nanotime`, this package also provides an interval type\n`nanoival` which may have open or closed start/end, a period type `nanoperiod` that is a human\nrepresentation of time, such as day, month, etc., and a duration type `nanoduration`. These types\nare similar to what the [lubridate](https://github.com/tidyverse/lubridate) package proposes.\n\nSet and arithmetic operations on these types are available. All functionality is designed to\ncorrectly handle instances across different time zones. Because these temporal types are based on R\nbuilt-in types, most functions have an efficient implementation and the types are suitable for use\nin `data.frame` and `data.table`. `nanotime` is also a better choice than the native `POSIXct` in\nmost of the cases where fractional seconds are needed because it avoids floating point issues.\n\n### Documentation\n\nPackage documentation, help pages, a vignette, and more is available\n[here](https://eddelbuettel.github.io/nanotime/).\n\n\n### Demo\n\nSee the included demo script [nanosecondDelayExample.R](https://github.com/eddelbuettel/nanotime/blob/master/demo/nanosecondDelayExample.R)\nfor a (completely simulated and hence made-up) study of network latency measured\nin nanoseconds resulting in the figure below\n\n![](https://eddelbuettel.github.io/nanotime/assets/nanotimeDelayDemo.png)\n\n### Examples\n\n#### Simple Parsing and Arithmetic\n\n```r\nR\u003e x \u003c- as.nanotime(\"1970-01-01T00:00:00.000000001+00:00\")\nR\u003e x\n[1] \"1970-01-01T00:00:00.000000001+00:00\"\nR\u003e x + 1e9\n[1] \"1970-01-01T00:00:01.000000001+00:00\"\nR\u003e as.nanotime(\"2020-03-21 Europe/London\")\n[1] 2020-03-21T00:00:00+00:00\n```\n\n#### Vectorised\n\n```r\nR\u003e options(\"width\"=60)\nR\u003e v \u003c- nanotime(Sys.time()) + 1:5\nR\u003e v\n[1] 2020-03-22T03:09:20.732122001+00:00\n[2] 2020-03-22T03:09:20.732122002+00:00\n[3] 2020-03-22T03:09:20.732122003+00:00\n[4] 2020-03-22T03:09:20.732122004+00:00\n[5] 2020-03-22T03:09:20.732122005+00:00\nR\u003e\n```\n\n#### Use with `zoo`\n\n```r\nR\u003e library(zoo)\nR\u003e z \u003c- zoo(cbind(A=1:5, B=5:1), v)\nR\u003e options(nanotimeFormat=\"%H:%M:%E*S\")  ## override default format\nR\u003e z\nR\u003e options(nanotimeFormat=NULL)  ## go back to default format\nR\u003e z\n```\n\n#### Use with data.table\n\n```r\nR\u003e library(data.table)\nR\u003e dt \u003c- data.table(v, cbind(A=1:5, B=5:1))\nR\u003e fwrite(dt, file=\"datatableTest.csv\")  # write out\nR\u003e dtcheck \u003c- fread(\"datatableTest.csv\") # read back\nR\u003e dtcheck\nR\u003e dtcheck[, v:=nanotime(v)]             # read as a string, need to re-class as nanotime\nR\u003e fread(\"../datatableTest.csv\", colClasses=c(\"nanotime\", \"integer\", \"integer\"))\n```\n\n#### Use with data.frame\n\nThis requires version 0.0.2 or later.\n\n```r\nR\u003e data.frame(cbind(A=1:5, B=5:1), v=v)\n```\n\n#### Intervals\n\n```r\nR\u003e ival \u003c- as.nanoival(\"+2009-01-01 13:12:00 America/New_York -\u003e 2009-02-01 15:11:03 America/New_York-\")\nR\u003e ival\n[1] +2009-01-01T18:12:00+00:00 -\u003e 2009-02-01T20:11:03+00:00-\n\nR\u003e start \u003c- nanotime(\"2009-01-01 13:12:00 America/New_York\")\nR\u003e end   \u003c- nanotime(\"2009-02-01 15:11:00 America/New_York\")\nR\u003e nanoival(start, end)                   # by default sopen=F,eopen=T\n[1] +2009-01-01T18:12:00+00:00 -\u003e 2009-02-01T20:11:00+00:00-\nR\u003e nanoival(start, end, sopen=FALSE, eopen=TRUE)\n[1] +2009-01-01T18:12:00+00:00 -\u003e 2009-02-01T20:11:00+00:00-\n\nR\u003e intersect(as.nanoival(\"+2019-03-01 UTC -\u003e 2020-03-01 UTC-\"),\n             as.nanoival(\"+2020-01-01 UTC -\u003e 2020-06-01 UTC-\"))\n[1] +2020-01-01T00:00:00+00:00 -\u003e 2020-03-01T00:00:00+00:00-\n\nR\u003e union(as.nanoival(\"+2019-03-01 UTC -\u003e 2020-03-01 UTC-\"),\n         as.nanoival(\"+2020-01-01 UTC -\u003e 2020-06-01 UTC-\"))\n[1] +2019-03-01T00:00:00+00:00 -\u003e 2020-06-01T00:00:00+00:00-\n\nR\u003e setdiff(as.nanoival(\"+2019-03-01 UTC -\u003e 2020-03-01 UTC-\"),\n           as.nanoival(\"+2020-01-01 UTC -\u003e 2020-06-01 UTC-\"))\n[1] +2019-03-01T00:00:00+00:00 -\u003e 2020-01-01T00:00:00+00:00-    \n```\n\n#### Periods\n\n```r\nR\u003e as.nanoperiod(\"1y1m1w1d/01:01:01.000_000_001\")\n[1] 13m8d/01:01:01.000_000_001\nR\u003e nanoperiod(months=13, days=-1, duration=\"01:00:00\")\n[1] 13m-1d/01:00:00\n\nR\u003e ones \u003c- as.nanoperiod(\"1y1m1w1d/01:01:01.000_000_001\")\nR\u003e nanoperiod.month(ones); nanoperiod.day(ones); nanoperiod.nanoduration(ones)\n[1] 13\n[1] 8\n[1] 01:01:01.000_000_001\n\nR\u003e plus(v, as.nanoperiod(\"1y1m\"), tz=\"UTC\")\n[1] 2021-04-22T03:09:20.732122001+00:00\n[2] 2021-04-22T03:09:20.732122002+00:00\n[3] 2021-04-22T03:09:20.732122003+00:00\n[4] 2021-04-22T03:09:20.732122004+00:00\n[5] 2021-04-22T03:09:20.732122005+00:00\n```\n\n#### Durations\n\n```{r}\nR\u003e nanoduration(hours=1, minutes=1, seconds=1, nanoseconds=1)\nR\u003e as.nanoduration(\"00:00:01\")\nR\u003e as.nanoduration(\"-00:00:01\")\nR\u003e as.nanoduration(\"100:00:00\")\nR\u003e as.nanoduration(\"00:00:00.000_000_001\")\n```\n\n#### Sequences\n\n``` {r}\nR\u003e from \u003c- as.nanotime(\"2018-09-14T12:44:00+00:00\")\nR\u003e seq(from, by=as.nanoperiod(\"1y\"), length.out=4, tz=\"Europe/London\")\n[1] 2018-09-14T12:44:00+00:00\n[2] 2019-09-14T12:44:00+00:00\n[3] 2020-09-14T12:44:00+00:00\n[4] 2021-09-14T12:44:00+00:00\n```\n\n### Technical Details\n\nThe [bit64](https://cran.r-project.org/package=bit64) package (by [Jens\nOehlschlägel](https://github.com/joehl)) supplies the `integer64` type used to store the nanosecond\nresolution time as (positive or negative) offsets to the epoch of January 1, 1970. The\n[RcppCCTZ](https://dirk.eddelbuettel.com/code/rcpp.cctz.html) package supplies the formatting and\nparsing routines based on the (modern C++) library [CCTZ](https://github.com/google/cctz) from\nGoogle, when the parsing cannot be done using a fast built-in parser. `integer64` is also used for\nthe type `nanoduration`, whereas `nanoival` and `nanoperiod` are stored in a `complex`, i.e. over\n128 bits.\n\n### Status\n\nThe package is by now fairly mature, has been rewritten once (to go from S3\nto S4) and has recently received a sizeable feature extension. There may\nstill be changes, though there should generally never be breaking ones. The\npackage also has an extensive test suite, and very good code coverage.\n\nSee the [issue tickets](https://github.com/eddelbuettel/nanotime/issues) for an up to date list of\npotentially desirable, possibly planned, or at least discussed items.\n\n### Installation\n\nThe package is on [CRAN](https://cran.r-project.org) and can be installed via a standard\n\n```r\ninstall.packages(\"nanotime\")\n```\n\nwhereas in order to install development versions a\n\n```r\nremotes::install_github(\"eddelbuettel/nanotime\")  # dev version\n```\n\nshould suffice.\n\n\n### Authors\n\nDirk Eddelbuettel and Leonardo Silvestri\n\n### License\n\nGPL (\u003e= 2)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddelbuettel%2Fnanotime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddelbuettel%2Fnanotime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddelbuettel%2Fnanotime/lists"}