{"id":19005906,"url":"https://github.com/rbeeli/timestamps64.jl","last_synced_at":"2026-02-07T00:32:12.876Z","repository":{"id":247331194,"uuid":"825480707","full_name":"rbeeli/Timestamps64.jl","owner":"rbeeli","description":"Julia Dates compatible UNIX timestamps with nanoseconds precision based on Int64 storage type.","archived":false,"fork":false,"pushed_at":"2025-12-25T16:49:07.000Z","size":425,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-27T03:02:56.196Z","etag":null,"topics":["chrono","datetime","epoch","high-resolution","julia","nanoseconds","precision","timestamp","unix"],"latest_commit_sha":null,"homepage":"https://rbeeli.github.io/Timestamps64.jl/","language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rbeeli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-07T22:32:41.000Z","updated_at":"2025-12-25T16:17:24.000Z","dependencies_parsed_at":"2024-07-09T03:31:05.503Z","dependency_job_id":"3a97a5b7-bceb-4055-bd8f-d77e752f7338","html_url":"https://github.com/rbeeli/Timestamps64.jl","commit_stats":null,"previous_names":["rbeeli/timestamp64.jl","rbeeli/timestamps64.jl"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/rbeeli/Timestamps64.jl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rbeeli%2FTimestamps64.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rbeeli%2FTimestamps64.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rbeeli%2FTimestamps64.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rbeeli%2FTimestamps64.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rbeeli","download_url":"https://codeload.github.com/rbeeli/Timestamps64.jl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rbeeli%2FTimestamps64.jl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29181843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T23:15:33.022Z","status":"ssl_error","status_checked_at":"2026-02-06T23:15:09.128Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["chrono","datetime","epoch","high-resolution","julia","nanoseconds","precision","timestamp","unix"],"created_at":"2024-11-08T18:29:35.650Z","updated_at":"2026-02-07T00:32:12.861Z","avatar_url":"https://github.com/rbeeli.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Timestamps64.jl\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/rbeeli/Timestamps64.jl/blob/main/LICENSE)\n[![CI](https://github.com/rbeeli/Timestamps64.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/rbeeli/Timestamps64.jl/actions/workflows/CI.yml)\n![Maintenance](https://img.shields.io/maintenance/yes/2025)\n[![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://rbeeli.github.io/Timestamps64.jl/stable/)\n\nThis package provides an efficient `Timestamp64` datetime type with nanosecond precision.\nIt is a wrapper around a single `Int64` value (8 bytes) that represents the number of nanoseconds since the UNIX epoch. Benchmarks show that common date/time operations are as fast as Julia's built-in `DateTime` type, or even significantly faster in some cases (see below).\n\n`Timestamp64` can store values ranging from `1970-01-01T00:00:00.000000000` to `2262-04-11 23:47:16.854775807`, which should be sufficient for most applications.\n\nThis package works with Julia's built-in `Dates` module, providing methods to convert between `Timestamp64` and `DateTime`, `Date`, and `Time` types.\nFurthermore, the common accessor functions for year, month, day, hour, minute, second, millisecond, microsecond, and nanosecond, among others, are provided.\n\nEvery function is unit-tested to ensure correctness, usually against the corresponding `Dates` function.\n\n\u003e [!NOTE]\n\u003e The default precision/unit of the difference of two `Timestamp64` objects is `Nanosecond`, while the default precision/unit of the difference of two `DateTime` objects is `Millisecond`.\n\n\u003e [!NOTE]\n\u003e Due to a different origin epoch (`1970-01-01T00:00:00.000000000` in `Timestamp64` vs. `0000-01-01T00:00:00` in `DateTime`), the rounding of `Timestamp64` with time periods smaller than `Day(1)` is not identical to the rounding of `DateTime`. This implementation corresponds to C++'s `chrono` rounding behavior.\n\n## Supported platforms\n\nThis package is supported on the following platforms (64-bit only):\n\n- Linux\n- macOS Sierra 10.12 and later (needs `clock_gettime` support)\n- Windows 10 / Windows Server 2016 and later (requires `GetSystemTimePreciseAsFileTime`)\n\n\u003e [!NOTE]\n\u003e Windows exposes the wall-clock in 100-nanosecond ticks via `GetSystemTimePreciseAsFileTime`, so while this package returns nanosecond values, the effective resolution on Windows is still 100 ns (or coarser on some hardware).\n\nExamples of not supported platforms:\n\n- Any 32-bit system\n- Windows versions earlier than 10 (e.g., Windows 8.1)\n- Older macOS versions before 10.12\n\n## Background\n\nThe reason this package was created is that the built-in `Dates.DateTime` type in Julia is not able to represent nanosecond precision.\nThe `Dates.DateTime` type has millisecond precision, which is insufficient for some specialized applications.\n\n## API documentation\n\n```julia\nusing Timestamps64\nusing Dates\n\n# Create a timestamp\nts = Timestamp64(2021, 12, 31, 23, 58, 59, nanoseconds=123456789)\n\n# Current timestamp in UTC with nanosecond precision\nnow(Timestamp64)\n\n# Current timestamp in UTC with nanosecond precision (explicit)\nnow(Timestamp64, UTC)\n\n# Today's timestamp in UTC at midnight\ntoday(Timestamp64)\n\n# Today's timestamp in UTC at midnight (explicit)\ntoday(Timestamp64, UTC)\n\n# Convert from various ISO 8601 string formats\nTimestamp64(\"2021-01-01T00:00:01\")\nTimestamp64(\"2021-01-01T00:00:01Z\")\nTimestamp64(\"2021-01-01T00:00:00.001\") # 1 millisecond\nTimestamp64(\"2021-01-01T00:00:00.001Z\") # 1 millisecond\nTimestamp64(\"2021-01-01T00:00:00.000001\") # 1 microsecond\nTimestamp64(\"2021-01-01T00:00:00.000001Z\") # 1 microsecond\nTimestamp64(\"2021-01-01T00:00:00.000000001\") # 1 nanosecond\nTimestamp64(\"2021-01-01T00:00:00.000000001Z\") # 1 nanosecond\n\n# Base.parse is also supported (only ISO 8601 / RFC 3339 up to nanoseconds formats)\nparse(Timestamp64, \"2021-01-01T00:00:00.000000001Z\", Dates.ISODateTimeFormat)\nparse(Timestamp64, \"2021-01-01T00:00:00\")\nparse(Timestamp64, \"2021-01-01T00:00:00.001\")\nparse(Timestamp64, \"2021-01-01T00:00:00.000000001Z\", ISOTimestamp64Format)\n\n\n## Dates conversion\n\n# Convert to DateTime, which only has millisecond precision\nDateTime(ts)\nconvert(DateTime, ts)\n\n# Convert to Date\nDate(ts)\nconvert(Date, ts)\n\n# Convert to Time\nTime(ts)\nconvert(Time, ts)\n\n# Create from DateTime (only with millisecond precision)\ndt = now()\nTimestamp64(dt)\n\n# Create from Date and Time (nanosecond precision)\nTimestamp64(Date(2021, 12, 31), Time(23, 58, 59, 123, 456, 789))\n\n\n## Accessor functions\nyear(ts)\nmonth(ts)\nday(ts)\nhour(ts)\nminute(ts)\nsecond(ts)\nnanosecond(ts)\nmillisecond(ts)\nmicrosecond(ts)\nnanosecond(ts)\nyearmonth(ts)\nyearmonthday(ts)\nmonthday(ts)\nmonthname(ts)\nisleapyear(ts)\ndayofweek(ts)\n\n\n## String conversions\n\n# Convert to string (ISO 8601 default)\nstring(ts)\n\n# Convert to ISO 8601 string explicitly\niso8601(ts)\n\n# Print string (ISO 8601 default)\nprintln(ts)\n\n# Dates.format is also supported\nDates.format(ts, Dates.ISODateTimeFormat)\nDates.format(ts, ISOTimestamp64Format)\n\n\n## Arithmetic\n\n# Add period\nts2 = ts + Millisecond(100)\nts2 - ts\n\n# Subtract period\nts2 = ts - Microsecond(1)\nts2 - ts\n\n# Difference of two timestamps\nts1 = Timestamp64(2022, 12, 31, 23, 58, 59)\nts2 = Timestamp64(2023, 1, 1, 23, 58, 59)\nts2 - ts1\nDay(ts2 - ts1)\n\n\n## Numeric operations\n\n# Type constants\neps(Timestamp64)\nzero(Timestamp64)\niszero(Timestamp64(0))\ntypemin(Timestamp64)\ntypemax(Timestamp64)\n\n# Compare timestamps\nts1 \u003c ts2\nts1 \u003e ts2\nts1 == ts2\n\n# Automatic type promotion\nTimestamp64(2020, 1, 1) \u003c DateTime(2020, 1, 2)\nTimestamp64(2020, 1, 1) \u003c Date(2020, 1, 2)\n\n\n## Rounding\n\n# Floor to nearest period value\nfloor(ts, Nanosecond(5))\nfloor(ts, Microsecond(5))\nfloor(ts, Millisecond(5))\nfloor(ts, Second(5))\nfloor(ts, Minute(5))\nfloor(ts, Hour(5))\nfloor(ts, Day(5))\nfloor(ts, Month(5))\nfloor(ts, Quarter(5))\nfloor(ts, Year(5))\n\n# Ceil to nearest period\nceil(ts, Nanosecond(5))\nceil(ts, Microsecond(5))\nceil(ts, Millisecond(5))\nceil(ts, Second(5))\nceil(ts, Minute(5))\nceil(ts, Hour(5))\nceil(ts, Day(5))\nceil(ts, Month(5))\nceil(ts, Quarter(5))\nceil(ts, Year(5))\n\n# Round to nearest period\nround(ts, Nanosecond(5))\nround(ts, Microsecond(5))\nround(ts, Millisecond(5))\nround(ts, Second(5))\nround(ts, Minute(5))\nround(ts, Hour(5))\nround(ts, Day(5))\nround(ts, Month(5))\nround(ts, Quarter(5))\nround(ts, Year(5))\n\n\n## Ranges\n\n# Create a range of timestamps using arbitrary periods\ncollect(Timestamp64(2020, 1, 1):Day(1):Timestamp64(2020, 1, 10))\ncollect(Timestamp64(2020, 1, 1):Week(1):Timestamp64(2020, 1, 31))\ncollect(Timestamp64(2020, 1, 1):Month(1):Timestamp64(2020, 12, 31))\ncollect(Timestamp64(2020, 1, 1):Quarter(1):Timestamp64(2020, 12, 31))\ncollect(Timestamp64(2020, 1, 1):Year(1):Timestamp64(2022, 1, 1))\n\n\n## UNIX timestamp conversions\n\n# create from UNIX timestamp in nanoseconds\nTimestamp64(1704412800000000000)\n\n# get UNIX timestamp in nanoseconds\nDates.value(ts)\nunix_nanos(ts)\nunix(Nanosecond, ts)\n\n# get UNIX timestamp in microseconds\nunix_micros(ts)\nunix(Microsecond, ts)\n\n# get UNIX timestamp in milliseconds\nunix_millis(ts)\nunix(Millisecond, ts)\n\n# get UNIX timestamp in seconds\nunix_secs(ts)\nunix(Second, ts)\n```\n\n## Performance\n\nThe `Timestamp64` implementation is very efficient and has a small memory footprint with only 8 bytes.\nCommon operations such as creating, parsing, converting, and formatting timestamps have been optimized and are as fast as Julia's built-in `DateTime` implementation, or even faster.\n\nThe following benchmark results have been obtained on an Intel(R) Core(TM) i9-12900K CPU on Ubuntu 22.04 using Julia 1.10.4.\n\n### Get object with current date/time in UTC\n\n```julia\nusing BenchmarkTools\nusing Timestamps64\nusing Dates\n\n@btime now(Timestamp64, UTC);\n@btime now(UTC);\n```\n\n#### Result\n\n```console\njulia\u003e @btime now(Timestamp64, UTC);\n  11.392 ns (0 allocations: 0 bytes)\n\njulia\u003e @btime now(UTC);\n  22.015 ns (0 allocations: 0 bytes)\n```\n\nThe `Timestamp64` type is almost **2 times faster** at getting the current UTC time compared to Julia's built-in `DateTime` type!\n\n### Construction from date parts\n\n```julia\nusing BenchmarkTools\nusing Timestamps64\nusing Dates\n\nconst year = 2021;\n\n@btime Timestamp64($year, 1, 1, 0, 0, 1, 123*1_000_000); # last parameter in nanoseconds!\n@btime DateTime($year, 1, 1, 0, 0, 1, 123);\n```\n\n#### Result\n\nThe `Timestamp64` type is **1.7 times faster** at constructing a datetime object from its parts compared to Julia's built-in `DateTime` type!\n\n```console\njulia\u003e @btime Timestamp64($year, 1, 1, 0, 0, 1, 123);\n  3.364 ns (0 allocations: 0 bytes)\n\njulia\u003e @btime DateTime($year, 1, 1, 0, 0, 1, 123);\n  5.644 ns (0 allocations: 0 bytes)\n```\n\n### Parsing ISO 8601 strings\n\n```julia\nusing BenchmarkTools\nusing Timestamps64\nusing Dates\n\n@btime Timestamp64(\"2021-01-01T00:00:01\");\n@btime DateTime(\"2021-01-01T00:00:01\");\n\n@btime Timestamp64(\"2021-01-01T00:00:01.001\");\n@btime DateTime(\"2021-01-01T00:00:01.001\");\n```\n\n#### Result\n\nThe `Timestamp64` type is almost **1.5 times faster** at parsing ISO 8601 strings compared to Julia's built-in `DateTime` type!\n\n```console\njulia\u003e @btime Timestamp64(\"2021-01-01T00:00:01\");\n  16.175 ns (0 allocations: 0 bytes)\n\njulia\u003e @btime DateTime(\"2021-01-01T00:00:01\");\n  23.312 ns (0 allocations: 0 bytes)\n\njulia\u003e @btime Timestamp64(\"2021-01-01T00:00:01.001\");\n  19.271 ns (0 allocations: 0 bytes)\n\njulia\u003e @btime DateTime(\"2021-01-01T00:00:01.001\");\n  27.942 ns (0 allocations: 0 bytes)\n```\n\n### Format to ISO 8601 strings\n\n```julia\nusing BenchmarkTools\nusing Timestamps64\nusing Dates\n\nts = Timestamp64(2021, 1, 1, 0, 0, 1) + Millisecond(123)\ndt = DateTime(2021, 1, 1, 0, 0, 1) + Millisecond(123)\n\n# ISO 8601 string formatting\n@btime Dates.format($ts, ISOTimestamp64Format);\n@btime Dates.format($dt, Dates.ISODateTimeFormat);\n```\n\n#### Result\n\nThe `Timestamp64` type is more than **6 times faster** at formatting to a ISO 8601 string compared to Julia's built-in `DateTime` type, and with fewer allocations!\n\n```console\njulia\u003e @btime Dates.format($ts, ISOTimestamp64Format);\n  46.626 ns (4 allocations: 200 bytes)\n\njulia\u003e @btime Dates.format($dt, Dates.ISODateTimeFormat);\n  286.392 ns (19 allocations: 928 bytes)\n```\n\n### Calculate difference\n\nNote that the `Timestamp64` type has nanosecond precision, while the `DateTime` type has millisecond precision, so the return type is correspondingly `Nanosecond` for `Timestamp64` and `Millisecond` for `DateTime`.\n\n```julia\nusing BenchmarkTools\nusing Timestamps64\nusing Dates\n\nts1 = Timestamp64(2021, 1, 1, 0, 0, 1);\nts2 = Timestamp64(2021, 1, 1, 0, 0, 2);\n\ndt1 = DateTime(2021, 1, 1, 0, 0, 1);\ndt2 = DateTime(2021, 1, 1, 0, 0, 2);\n\n@btime $ts2 - $ts1;\n@btime $dt2 - $dt1;\n```\n\n#### Result\n\nIdentical performance for both `Timestamp64` and `DateTime` types.\n\n```console\njulia\u003e @btime $ts2 - $ts1;\n  1.356 ns (0 allocations: 0 bytes)\n\njulia\u003e @btime $dt2 - $dt1;\n  1.358 ns (0 allocations: 0 bytes)\n```\n\n### Access UNIX timestamp in seconds\n\n```julia\nusing BenchmarkTools\nusing Timestamps64\nusing Dates\n\nts = Timestamp64(2021, 1, 1, 0, 0, 1) + Millisecond(123);\ndt = DateTime(2021, 1, 1, 0, 0, 1) + Millisecond(123);\n\n@btime unix_secs($ts);\n@btime trunc(Int64, datetime2unix($dt));\n```\n\n#### Result\n\nDue to the internal representation of the `Timestamp64` value as UNIX timestamp in nanoseconds, the conversion to a UNIX timestamp in seconds is trivial and therefore **2.3 times faster** compared to Julia's built-in `DateTime` type using the `datetime2unix` function.\n\n```console\njulia\u003e @btime unix_secs($ts);\n  1.571 ns (0 allocations: 0 bytes)\n\njulia\u003e @btime trunc(Int64, datetime2unix($dt));\n  3.654 ns (0 allocations: 0 bytes)\n```\n\n### Access UNIX timestamp in milliseconds\n\n```julia\nusing BenchmarkTools\nusing Timestamps64\nusing Dates\n\nts = Timestamp64(2021, 1, 1, 0, 0, 1) + Millisecond(123);\ndt = DateTime(2021, 1, 1, 0, 0, 1) + Millisecond(123);\n\n@btime unix_millis($ts);\n@btime trunc(Int64, datetime2unix($dt)*1000);\n```\n\n#### Result\n\nDue to the internal representation of the `Timestamp64` value as UNIX timestamp in nanoseconds, the conversion to a UNIX timestamp in seconds is trivial and therefore **2.6 times faster** compared to Julia's built-in `DateTime` type using the `datetime2unix` function.\n\n```console\njulia\u003e @btime unix_millis($ts);\n  1.729 ns (0 allocations: 0 bytes)\n\njulia\u003e @btime trunc(Int64, datetime2unix($dt)*1000);\n  4.420 ns (0 allocations: 0 bytes)\n```\n\n### Create object from UNIX timestamp in milliseconds\n\n```julia\nusing BenchmarkTools\nusing Timestamps64\nusing Dates\n\nunix_millis = 1609459201000; # 2021-01-01T00:00:01.000000000\n\n@btime Timestamp64($unix_millis * 1_000_000);\n@btime unix2datetime($unix_millis / 1000);\n```\n\n#### Result\n\nThe `Timestamp64` type is **3.3 times faster** at creating a timestamp from a UNIX timestamp in milliseconds compared to Julia's built-in `DateTime` type! This is partly due to the additional division operation required for the `DateTime` type.\n\n```console\njulia\u003e @btime Timestamp64($unix_millis * 1_000_000);\n  1.378 ns (0 allocations: 0 bytes)\n\njulia\u003e @btime unix2datetime($unix_millis / 1000);\n  4.507 ns (0 allocations: 0 bytes)\n```\n\n### Create object from UNIX timestamp in seconds\n\n```julia\nusing BenchmarkTools\nusing Timestamps64\nusing Dates\n\nunix_secs = 1609459201; # 2021-01-01T00:00:01.000000000\n\n@btime Timestamp64($unix_secs * 1_000_000_000);\n@btime unix2datetime($unix_secs);\n```\n\n#### Result\n\nAlmost identical performance for both `Timestamp64` and `DateTime` types.\n\n```console\njulia\u003e @btime Timestamp64($unix_secs * 1_000_000_000);\n  1.539 ns (0 allocations: 0 bytes)\n\njulia\u003e @btime unix2datetime($unix_secs);\n  1.570 ns (0 allocations: 0 bytes)\n```\n\n## Bug reports and feature requests\n\nPlease report any issues via the [GitHub issue tracker](https://github.com/rbeeli/Timestamps64.jl/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frbeeli%2Ftimestamps64.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frbeeli%2Ftimestamps64.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frbeeli%2Ftimestamps64.jl/lists"}