⏱ Time

A Kotlin multiplatform library filling in the gaps of kotlinx-datetime with additional type-safe APIs for time periods, as equivalents to those found in the Swift library of the same name(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

val clock =Clock.Systemval now:Instant= clock.thisInstant()
val today:TimePeriod<TimeUnit.Day> = clock.today()
val month:TimePeriod<TimeUnit.Month> = clock.thisMonth()

Retrieving Components

Retrieve component values for a time period:

val today:TimePeriod<TimeUnit.Day> =Clock.System.today()
val year = today.year // Ex: 2022val month = today.month // Ex: APRILval day = today.day // Ex: 18

Retrieving TimePeriods

Retrieve larger less-precise time periods for a time period:

val today:TimePeriod<TimeUnit.Day> =Clock.System.today()
val month:TimePeriod<TimeUnit.Month> = today.monthPeriod
val year:TimePeriod<TimeUnit.Year> = today.yearPeriod

Retrieve smaller more-precise time periods for a time period:

val clock =Clock.Systemval firstDayOfMonth:TimePeriod<TimeUnit.Day> = clock.thisMonth().firstDay
val lastHourOfDay:TimePeriod<TimeUnit.Hour> = clock.today().lastHour
val firstDayOfYear:TimePeriod<TimeUnit.Day> = clock.thisYear().firstDay

Iterating Over TimePeriods

val clock =Clock.Systemval thisMonth:TimePeriod<TimeUnit.Month> = clock.thisMonth()
val daysInThisMonth = thisMonth.days
for (day in daysInThisMonth) {
// …
}
val thisHour:TimePeriod<TimeUnit.Hour> = clock.thisHour()
val minutesInThisHour = thisHour.minutes
for (minute in minutesInThisHour) {
// …
}

Determining The Relationship Between TimePeriods

val clock =Clock.Systemval dayA:TimePeriod<TimeUnit.Day> =...
val dayB:TimePeriod<TimeUnit.Day> =...
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

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 invalidval 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 file for details.