{"id":28829346,"url":"https://github.com/ballerina-platform/module-ballerina-time","last_synced_at":"2026-02-03T15:03:48.007Z","repository":{"id":37098875,"uuid":"288615439","full_name":"ballerina-platform/module-ballerina-time","owner":"ballerina-platform","description":"Ballerina time Module","archived":false,"fork":false,"pushed_at":"2025-05-19T18:27:59.000Z","size":1215,"stargazers_count":108,"open_issues_count":0,"forks_count":31,"subscribers_count":69,"default_branch":"master","last_synced_at":"2025-05-19T19:42:53.943Z","etag":null,"topics":["ballerina","hacktoberfest","integration","time","wso2"],"latest_commit_sha":null,"homepage":"","language":"Ballerina","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ballerina-platform.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-19T02:39:24.000Z","updated_at":"2025-05-19T18:28:03.000Z","dependencies_parsed_at":"2024-11-21T10:27:17.021Z","dependency_job_id":"07ae038e-1a18-4003-b59a-feeb07ba41f6","html_url":"https://github.com/ballerina-platform/module-ballerina-time","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/ballerina-platform/module-ballerina-time","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-time","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-time/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-time/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-time/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ballerina-platform","download_url":"https://codeload.github.com/ballerina-platform/module-ballerina-time/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ballerina-platform%2Fmodule-ballerina-time/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260690959,"owners_count":23047106,"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":["ballerina","hacktoberfest","integration","time","wso2"],"created_at":"2025-06-19T05:13:07.037Z","updated_at":"2026-02-03T15:03:47.993Z","avatar_url":"https://github.com/ballerina-platform.png","language":"Ballerina","funding_links":[],"categories":[],"sub_categories":[],"readme":"Ballerina Time Library\n===================\n\n  [![Build](https://github.com/ballerina-platform/module-ballerina-time/actions/workflows/build-timestamped-master.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-time/actions/workflows/build-timestamped-master.yml)\n  [![codecov](https://codecov.io/gh/ballerina-platform/module-ballerina-time/branch/master/graph/badge.svg)](https://codecov.io/gh/ballerina-platform/module-ballerina-time)\n  [![Trivy](https://github.com/ballerina-platform/module-ballerina-time/actions/workflows/trivy-scan.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-time/actions/workflows/trivy-scan.yml)\n  [![GraalVM Check](https://github.com/ballerina-platform/module-ballerina-time/actions/workflows/build-with-bal-test-graalvm.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerina-time/actions/workflows/build-with-bal-test-graalvm.yml)\n  [![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/module-ballerina-time.svg)](https://github.com/ballerina-platform/module-ballerina-time/commits/master)\n  [![Github issues](https://img.shields.io/github/issues/ballerina-platform/ballerina-standard-library/module/time.svg?label=Open%20Issues)](https://github.com/ballerina-platform/ballerina-standard-library/labels/module%2Ftime)\n\nThis library provides a set of APIs that have the capabilities to generate and manipulate UTC and localized time.\n\nIn cloud computing, the most essential type of time is UTC. Coordinated Universal Time (UTC) is the primary time standard on which the world agreed.\nUTC is independent of daylight saving time and provides a unique time value for the entire world.\nThe definition of UTC started from the epoc `1970-01-01T00:00:00Z`. Initially, humans divided a day into 86400 seconds.\nHowever, the Earth rotation does not adhere to this time duration as the Earth is slowing down and the day is getting longer.\nAs a result, a solar day in 2012 is longer than 86400 SI seconds.\nTo correct this incompatibility, additional seconds have been added to the UTC scale, which is known as leap-seconds.\n\nThe focus of this library is to give the most precise UTC with nanoseconds precision and also handle some complex use cases such as leap seconds and daylight time-saving.\n\n### UTC time\nThe `time:Utc` is the tuple representation of the UTC. The UTC represents the number of seconds from a\nspecified epoch. Here, the epoch is the UNIX epoch of 1970-01-01T00:00:00Z.\n\nUse the following API to get the current epoch time:\n```ballerina\ntime:Utc utc = time:utcNow();\n```\n\n### Monotonic time\nThe monotonic time represents the number of seconds from an unspecified epoch.\n\nUse the following API to get the monotonic time from an unspecified topic:\n```ballerina\ndecimal seconds = time:monotonicNow();\n```\n\n### Civil time\nThe localized time represents using the `time:Civil` record. It includes the following details:\n- date\n- time\n- timezone information\n- daylight time-saving information\n\n### Time zone\nThe time zone can be obtained using a given zone ID or load the system time zone.\n```ballerina\n// Obtain the time zone corresponding to a given time zone ID.\ntime:Zone? zone = time:getZone(\"Asia/Colombo\");\n\n// Obtain the system time zone.\ntime:Zone zone = check time:loadSystemZone();\n```\n\n### APIs\nParallel to the aforementioned time representations, this library includes a set of APIs to facilitate time conversions\nand manipulations using a set of high-level APIs. Those conversion APIs can be listed as follows.\n\n#### The string representations of UTC\n```ballerina\n// Converts from RFC 3339 timestamp to UTC.\ntime:Utc utc = check time:utcFromString(\"2007-12-03T10:15:30.00Z\");\n\n// Converts a given `time:Utc` time to a RFC 3339 timestamp.\nstring utcString = time:utcToString(utc);\n```\n\n#### The string representations of civil\n```ballerina\n// Converts from RFC 3339 timestamp to a civil record.\ntime:Civil civil2 = check time:civilFromString(\"2007-12-03T10:15:30.00Z\");\n\n// Converts a given `time:Civil` time to a RFC 3339 timestamp.\nstring civilString = check time:civilToString(civil);\n```\n\n#### UTC value manipulation\n```ballerina\n// Returns the UTC time that occurs seconds after the given UTC.\ntime:Utc utc = time:utcAddSeconds(time:utcNow(), 20.900);\n\n// Returns the difference in seconds between two given UTC time values.\ntime:Utc utc1 = time:utcNow();\ntime:Utc utc2 = check time:utcFromString(\"2021-04-12T23:20:50.520Z\");\ntime:Seconds seconds = time:utcDiffSeconds(utc1, utc2);\n```\n\n#### UTC vs civil\n```ballerina\n// Converts a given UTC to a Civil.\ntime:Civil civil = time:utcToCivil(utc);\n\n// Converts a given Civil to a UTC.\ntime:Utc utc = time:utcFromCivil(civil);\n```\n\n## Issues and projects \n\nIssues and Project tabs are disabled for this repository as this is part of the Ballerina Standard Library. To report bugs, request new features, start new discussions, view project boards, etc. please visit Ballerina Standard Library [parent repository](https://github.com/ballerina-platform/ballerina-standard-library). \n\nThis repository only contains the source code for the package.\n\n## Build from the source\n\n### Set up the prerequisites\n\n1. Download and install Java SE Development Kit (JDK) version 21 (from one of the following locations).\n   * [Oracle](https://www.oracle.com/java/technologies/downloads/)\n\n   * [OpenJDK](https://adoptium.net/)\n\n        \u003e **Note:** Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK.\n     \n### Build the source\n\nExecute the commands below to build from source.\n\n1. To build the library:\n   ```    \n   ./gradlew clean build\n   ```\n\n1. To run the integration tests:\n   ```\n   ./gradlew clean test\n   ```\n1. To build the module without the tests:\n   ```\n   ./gradlew clean build -x test\n   ```\n1. To debug module implementation:\n   ```\n   ./gradlew clean build -Pdebug=\u003cport\u003e\n   ./gradlew clean test -Pdebug=\u003cport\u003e\n   ```\n1. To debug the module with Ballerina language:\n   ```\n   ./gradlew clean build -PbalJavaDebug=\u003cport\u003e\n   ./gradlew clean test -PbalJavaDebug=\u003cport\u003e\n   ```\n1. Publish ZIP artifact to the local `.m2` repository:\n   ```\n   ./gradlew clean build publishToMavenLocal\n   ```\n1. Publish the generated artifacts to the local Ballerina central repository:\n   ```\n   ./gradlew clean build -PpublishToLocalCentral=true\n   ```\n1. Publish the generated artifacts to the Ballerina central repository:\n   ```\n   ./gradlew clean build -PpublishToCentral=true\n   ```      \n\n## Contribute to Ballerina\n\nAs an open source project, Ballerina welcomes contributions from the community.\n\nFor more information, go to the [contribution guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md).\n\n## Code of conduct\n\nAll contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct).\n\n## Useful links\n\n* Chat live with us via our [Discord server](https://discord.gg/ballerinalang).\n* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.\n* For more information go to [the Time Package](https://ballerina.io/learn/api-docs/ballerina/time/).\n* For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/learn/by-example/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fballerina-platform%2Fmodule-ballerina-time","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fballerina-platform%2Fmodule-ballerina-time","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fballerina-platform%2Fmodule-ballerina-time/lists"}