{"id":13536852,"url":"https://github.com/MrAsterisco/Time","last_synced_at":"2025-04-02T03:31:17.305Z","repository":{"id":83805044,"uuid":"393949177","full_name":"MrAsterisco/Time","owner":"MrAsterisco","description":"Type-safe time calculations in Kotlin, on any platform.","archived":false,"fork":false,"pushed_at":"2022-11-05T11:36:39.000Z","size":173,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T11:02:35.425Z","etag":null,"topics":["kotlin-multiplatform","kotlin-multiplatform-library","milliseconds","time"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","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/MrAsterisco.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2021-08-08T12:06:26.000Z","updated_at":"2024-11-22T19:03:23.000Z","dependencies_parsed_at":"2023-07-07T05:46:29.067Z","dependency_job_id":null,"html_url":"https://github.com/MrAsterisco/Time","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrAsterisco%2FTime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrAsterisco%2FTime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrAsterisco%2FTime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrAsterisco%2FTime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MrAsterisco","download_url":"https://codeload.github.com/MrAsterisco/Time/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246751125,"owners_count":20827836,"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":["kotlin-multiplatform","kotlin-multiplatform-library","milliseconds","time"],"created_at":"2024-08-01T09:00:50.566Z","updated_at":"2025-04-02T03:31:16.963Z","avatar_url":"https://github.com/MrAsterisco.png","language":"Kotlin","funding_links":[],"categories":["Libraries"],"sub_categories":["Utility"],"readme":"# Time\n\nThis is a Kotlin multiplatform implementation based upon the [Time](https://github.com/kizitonwose/Time) library for Android.\nThe library is made for you if you have ever written something like this: \n\n```kotlin\nval duration = 10 * 1000\n```\n\nto represent a duration of 10 seconds(in milliseconds) because most methods in Kotlin/Java take duration parameters in milliseconds.\n\n## Usage\n\n### Showcase\n\n```kotlin\nval tenSeconds = 10.seconds\nval fiveMinutes = 5.minutes\nval twoHours = 2.hours\nval threeDays = 3.days\nval tenMinutesFromNow = Calendar.getInstance() + 10.minutes\nval tenSecondsInMilliseconds = 10.seconds.inMilliseconds\n```\n\n### Basics\n\nThe main advantage of the library is that all time units are *strongly-typed*. So, for example:\n\n```kotlin\nval tenMinutes = 10.minutes\n```\n\nIn the example above,  `tenMinutes` will be of type `Interval\u003cMinute\u003e`. There are seven time units available, from nanoseconds to days:\n\n```kotlin\nval tenNanoseconds = 10.nanoseconds \n// type is Interval\u003cNanosecond\u003e\n```\n```kotlin\nval tenMicroseconds = 10.microseconds \n// type is Interval\u003cMicrosecond\u003e\n```\n```kotlin\nval tenMilliseconds = 10.milliseconds \n// type is Interval\u003cMillisecond\u003e\n```\n```kotlin\nval tenSeconds = 10.seconds \n// type is Interval\u003cSecond\u003e\n```\n```kotlin\nval tenMinutes = 10.minutes \n// type is Interval\u003cMinute\u003e\n```\n```kotlin\nval tenHours = 10.hours \n// type is Interval\u003cHour\u003e\n```\n```kotlin\nval tenDays = 10.days \n// type is Interval\u003cDay\u003e\n```\n\n### Operations\n\nYou can perform all basic arithmetic operations on time intervals, even of different units:\n\n```kotlin\nval duration = 10.minutes + 15.seconds - 3.minutes + 2.hours // Interval\u003cMinute\u003e\nval doubled = duration * 2\n\nval seconds = 10.seconds + 3.minutes // Interval\u003cSecond\u003e\n```\n\nYou can also use these operations with the `Calendar` class:\n\n```kotlin\nval twoHoursLater = Calendar.getInstance() + 2.hours\n```\n\n### Conversions\n\nTime intervals are easily convertible:\n\n```kotlin\nval twoMinutesInSeconds = 2.minutes.inSeconds // Interval\u003cSecond\u003e\nval fourDaysInHours = 4.days.inHours // Interval\u003cHour\u003e\n```\n\nYou can also use the `converted(TimeUnit)` method, although you would rarely need to:\n\n```kotlin\nval tenMinutesInSeconds: Interval\u003cSecond\u003e = 10.minutes.converted(Second())\n```\n\n### Comparison\n\nYou can compare different time units as well:\n\n```kotlin\n50.seconds \u003c 2.hours // true\n120.minutes == 2.hours // true\n100.milliseconds \u003e 2.seconds // false\n48.hours in 2.days // true\n```\n\n### Creating your own time units\n\nIf, for some reason, you need to create your own time unit, that's super easy to do:\n\n```kotlin\nclass Week : TimeUnit {\n    // number of seconds in one week\n    override val timeIntervalRatio = 604800.0\n}\n```\n\nNow you can use it like any other time unit:\n\n```kotlin\nval fiveWeeks = Interval\u003cWeek\u003e(5)\n```\n\nFor the sake of convenience, don't forget to write those handy extensions:\n\n```kotlin\nclass Week : TimeUnit {\n    override val timeIntervalRatio = 604800.0\n}\n\nval Number.weeks: Interval\u003cWeek\u003e\n    get() = Interval(this)\n\nval Interval\u003cTimeUnit\u003e.inWeeks: Interval\u003cWeek\u003e\n    get() = converted(Week())\n```\nNow you can write:\n\n```kotlin\nval fiveWeeks = 5.weeks // Interval\u003cWeek\u003e\n```\nYou can also easily convert to weeks:\n\n```kotlin\nval valueInWeeks = 14.days.inWeeks // Interval\u003cWeek\u003e\n```\n\n### Conversion safety everywhere\n\nFor time-related methods in other third-party libraries in your project, if such methods are frequently used, it's best to write extention functions that let you use the time units in this libary in those methods. This is mostly just one line of code. \n\nIf such methods aren't frequently used, you can still benefit from the conversion safety that comes with this library.\n\nAn example method in a third-party library that does something after a delay period in milliseconds:\n\n```kotlin\nclass Person {\n    fun doSomething(delayMillis: Long) {\n        // method body\n    }\n}\n```\n\nTo call the method above with a value of 5 minutes, one would usually write:\n\n```kotlin\nval person = Person()\nperson.doSomething(5 * 60 * 1000)\n```\n\nThe above line can be written in a safer and clearer way using this library:\n\n```kotlin\nval person = Person()\nperson.doSomething(5.minutes.inMilliseconds.longValue)\n```\n\nIf the method is frequently used, you can write an extension function:\n\n```kotlin\nfun Person.doSomething(delay: Interval\u003cTimeUnit\u003e) {\n    doSomething(delay.inMilliseconds.longValue)\n}\n```\nNow you can write:\n\n```kotlin\nval person = Person()\nperson.doSomething(5.minutes)\n```\n\n## Changes from the Android library\n\nDue to the current development status of the Kotlin multiplatform project, some APIs have been changed.\n\n### converted()\nIn the original library, the `converted` method uses Java reflection to instantiate \na new class of the required `TimeUnit` implementation. \nSince in Kotlin multiplatform, the reflection API is still in early stages (and not implemented on some platforms), \nI have added a required parameter that points to an instance of the to the expected `TimeUnit` implementation.\n\n### Android extensions\nThe content of the Android extensions provided by the original library have not been ported to this implementation.\n\n## Installation\n\nAdd the GitHub registry to your `build.gradle`:\n\n```kotlin\nallprojects {\n repositories {\n     maven {\n         url = uri(\"https://maven.pkg.github.com/mrasterisco/time\")\n         credentials {\n             username = \u003cYOUR GITHUB USERNAME\u003e\n             password = \u003cYOUR GITHUB PERSONAL ACCESS TOKEN\u003e\n         }\n     }\n }\n}\n```\n\nGitHub doesn't support accessing packages without authentication ([more info](https://github.community/t/download-from-github-package-registry-without-authentication/14407/96). You can generate a personal access token for your account [here](https://github.com/settings/tokens).\n\nSince version 1.6.2 (with Kotlin 1.4), Time can be imported as dependency by just referencing it in the `commonMain` module:\n\n```kotlin\nval commonMain by getting {\n    dependencies {\n        implementation(\"io.github.mrasterisco:time:\u003cversion\u003e\")\n    }\n}\n```\n\n### Compatibility\n\nTime is built with Kotlin 1.5 and Gradle 7.0.\n\nThe library implements only Kotlin common code and does not provide explicit implementations for any platform, hence it should work out-of-the-box everywhere. See the table below for further details:\n\n|                      | iOS         | macOS       | watchOS     | JVM         | nodeJS           | browserJS        | Windows | Linux   |\n|----------------------|-------------|-------------|-------------|-------------|------------------|------------------|---------|---------|\n| Assembled            | YES         | YES         | YES         | YES         | Removed in 1.6.0 | Removed in 1.6.0 | NO      | NO      |\n| Unit Tests           | YES, passed | YES, passed | YES, passed | YES, passed | Removed in 1.6.0 | Removed in 1.6.0 | Not built | Not built |\n| Published to GitHub Packages | YES         | YES         | YES         | YES         | Removed in 1.6.0 | Removed in 1.6.0 | NO      | NO      |\n| Used in Production   | YES         | NO          | NO          | YES         | NO               | NO               | NO      | NO      |\n\nIf you start using this library in a project different on other platforms than iOS, Android or the JVM, please make a PR to update this file, so that others know that it has been implemented successfully on there as well.\n\n## Contributing\nThe goal is for the library to be used wherever possible. If there are extension functions or features you think the library should have, feel free to add them and send a pull request or open an issue.\n\n## Inspiration\nThis library is heavily based on the [Time](https://github.com/kizitonwose/Time) for Android with a few changes in order to make it work in the Kotlin multiplatform environment.\nTime was inspired by a Swift library of the same name - [Time](https://github.com/dreymonde/Time).\n\n## License\nTime is distributed under the MIT license. [See LICENSE](https://github.com/MrAsterisco/Time/blob/master/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMrAsterisco%2FTime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMrAsterisco%2FTime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMrAsterisco%2FTime/lists"}