Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sebj/time
⏱ Type-safe time periods for the Kotlinx-datetime multiplatform date/time library
https://github.com/sebj/time
android clock date datetime ios kmp kotlin kotlin-library kotlin-multiplatform kotlin-native time
Last synced: 6 days ago
JSON representation
⏱ Type-safe time periods for the Kotlinx-datetime multiplatform date/time library
- Host: GitHub
- URL: https://github.com/sebj/time
- Owner: sebj
- License: mit
- Created: 2022-04-17T22:26:16.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-24T20:33:00.000Z (15 days ago)
- Last Synced: 2024-10-26T07:51:21.065Z (14 days ago)
- Topics: android, clock, date, datetime, ios, kmp, kotlin, kotlin-library, kotlin-multiplatform, kotlin-native, time
- Language: Kotlin
- Homepage: https://sebj.github.io/time/time/[root]/index.html
- Size: 1.63 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-kotlin-multiplatform - time - Type-safe time periods for the Kotlinx-datetime multiplatform date/time library (Libraries / Utility)
README
# ⏱ Time
[](LICENSE)
[](https://github.com/sebj/time/releases)
[](https://github.com/sebj/time/actions/workflows/build-test-documentation.yaml)
[![Follow @[email protected]](https://img.shields.io/mastodon/follow/000921252?domain=https%3A%2F%2Fmastodon.social&style=plastic)](https://mastodon.social/@sebj)
A Kotlin multiplatform library filling in the gaps of [`kotlinx-datetime`](https://github.com/Kotlin/kotlinx-datetime) with additional type-safe APIs for time periods, as equivalents to those found in the Swift library of the same name([`time`](https://github.com/davedelong/time)).
Supported targets:
* Apple
* iOS
* macOS
* tvOS
* watchOS
* JVM
* Linux
Supported `TimePeriod` units:
* Year
* Month
* Day
* Hour
* Minute
* Second
* Nanosecond
## ⬇️ Installation
Add the dependency to your Gradle build file:
```
dependencies {
implementation("me.sebj:time:0.4.10")
}
```
## 💡 Usage Examples
### Fetching The Current Time Period
```kotlin
val clock = Clock.System
val now: Instant = clock.thisInstant()
val today: TimePeriod = clock.today()
val month: TimePeriod = clock.thisMonth()
```
### Retrieving Components
Retrieve component values for a time period:
```kotlin
val today: TimePeriod = Clock.System.today()
val year = today.year // Ex: 2022
val month = today.month // Ex: APRIL
val day = today.day // Ex: 18
```
### Retrieving TimePeriods
Retrieve larger less-precise time periods for a time period:
```kotlin
val today: TimePeriod = Clock.System.today()
val month: TimePeriod = today.monthPeriod
val year: TimePeriod = today.yearPeriod
```
Retrieve smaller more-precise time periods for a time period:
```kotlin
val clock = Clock.System
val firstDayOfMonth: TimePeriod = clock.thisMonth().firstDay
val lastHourOfDay: TimePeriod = clock.today().lastHour
val firstDayOfYear: TimePeriod = clock.thisYear().firstDay
```
### Iterating Over TimePeriods
```kotlin
val clock = Clock.System
val thisMonth: TimePeriod = clock.thisMonth()
val daysInThisMonth = thisMonth.days
for (day in daysInThisMonth) {
// …
}
val thisHour: TimePeriod = clock.thisHour()
val minutesInThisHour = thisHour.minutes
for (minute in minutesInThisHour) {
// …
}
```
### Determining The Relationship Between TimePeriods
```kotlin
val clock = Clock.System
val dayA: TimePeriod = ...
val dayB: TimePeriod = ...
val ..: Boolean = dayA.after(dayB)
// Also: `before`, `overlaps`, or compare specific relationship using `relation` (see Relations.kt)
val thisMonth = clock.thisMonth()
val ..: Boolean = dayA.during(thisMonth) // Equivalent to `thisMonth.contains(dayA)`
```
### Adjusting TimePeriods
```kotlin
val today = Clock.System.today()
val dayAfterTomorrow = today + TimeDifference.days(2)
_ = today + TimeDifference.hours(1) // Compiler error – not implemented, as this is invalid
_ = today + TimeDifference.minutes(1) // Compiler error – not implemented, as this is invalid
val thisMonth = today.monthPeriod
val monthBeforeLast = thisMonth - TimeDifference.months(2)
_ = today - TimeDifference.nanoseconds(1) // Compiler error – not implemented, as this is invalid
_ = today - TimeDifference.seconds(1) // Compiler error – not implemented, as this is invalid
```
## ⚖️ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.