or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arithmetic.mdformatting.mdindex.mdinstant.mdlocal-types.mdplatform.mdranges.mdserialization.mdtimezones.md
tile.json

tessl/maven-org-jetbrains-kotlinx--kotlinx-datetime-iosx64

A multiplatform Kotlin library for working with date and time, specifically the iOS x64 target variant

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlinx/kotlinx-datetime-iosx64@0.7.x

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlinx--kotlinx-datetime-iosx64@0.7.0

index.mddocs/

kotlinx-datetime

kotlinx-datetime is a multiplatform Kotlin library for working with date and time, specifically the iOS x64 target variant. It provides a pragmatic, focused approach to date/time problems with types like LocalDateTime, LocalDate, LocalTime, TimeZone, and various period/duration classes based on the ISO 8601 international standard.

Package Information

  • Package Name: org.jetbrains.kotlinx:kotlinx-datetime-iosx64
  • Package Type: maven
  • Language: Kotlin
  • Installation: Add to your build.gradle.kts: 
    dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.7.0")
}

Core Imports

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlinx.datetime.serializers.*
import kotlin.time.Clock
import kotlin.time.Instant

Basic Usage

import kotlinx.datetime.*
import kotlin.time.Clock

// Get current time
val now = Clock.System.now()
val today = Clock.System.todayIn(TimeZone.currentSystemDefault())

// Create dates and times
val date = LocalDate(2023, 12, 25)
val time = LocalTime(14, 30, 0)
val dateTime = LocalDateTime(date, time)

// Time zone conversions
val timeZone = TimeZone.of("America/New_York")
val instant = dateTime.toInstant(timeZone)
val localInTz = instant.toLocalDateTime(timeZone)

// Date arithmetic
val tomorrow = today.plus(DatePeriod(days = 1))
val nextWeek = today.plus(1, DateTimeUnit.WEEK)

// Formatting and parsing
val formatted = date.format(LocalDate.Formats.ISO)
val parsed = LocalDate.parse("2023-12-25", LocalDate.Formats.ISO)

Architecture

kotlinx-datetime is built around several key components:

  • Time Representation: Uses kotlin.time.Instant as the primary moment-in-time representation
  • Civil Time: LocalDate, LocalTime, LocalDateTime for time zone independent representations
  • Time Zones: TimeZone and FixedOffsetTimeZone for location-based time handling
  • Periods and Units: DateTimePeriod, DatePeriod, and DateTimeUnit for time arithmetic
  • Formatting System: Comprehensive formatting and parsing with custom format builders
  • Serialization: Full kotlinx.serialization support with multiple serializer variants
  • Platform Integration: Native conversions for iOS (NSDate, NSTimeZone, NSDateComponents)

Capabilities

Instant and Time Representation

Core time representation using kotlin.time.Instant as the primary moment-in-time type, with extensive extensions for timezone-aware operations.

// Primary time representation (from kotlin.time)
class Instant {
    val epochSeconds: Long
    val nanosecondsOfSecond: Int
    fun plus(duration: Duration): Instant
    fun minus(duration: Duration): Instant
    fun minus(other: Instant): Duration
}

// Extension functions for timezone-aware operations
fun Instant.toLocalDateTime(timeZone: TimeZone): LocalDateTime
fun Instant.toLocalDateTime(offset: UtcOffset): LocalDateTime
fun Instant.offsetIn(timeZone: TimeZone): UtcOffset
fun Instant.plus(period: DateTimePeriod, timeZone: TimeZone): Instant
fun Instant.minus(period: DateTimePeriod, timeZone: TimeZone): Instant

Instant and Time Representation

Local Date and Time Types

Civil date and time types for representing calendar dates and clock times without timezone reference.

expect class LocalDate {
    constructor(year: Int, month: Int, day: Int)
    constructor(year: Int, month: Month, day: Int)
    val year: Int
    val month: Month
    val day: Int
    val dayOfWeek: DayOfWeek
    val dayOfYear: Int
}

expect class LocalTime {
    constructor(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)
    val hour: Int
    val minute: Int
    val second: Int
    val nanosecond: Int
}

expect class LocalDateTime {
    constructor(year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)
    constructor(date: LocalDate, time: LocalTime)
    val year: Int
    val month: Month
    val day: Int
    val hour: Int
    val minute: Int
    val second: Int
    val nanosecond: Int
    val date: LocalDate
    val time: LocalTime
}

Local Date and Time Types

Time Zones and Offsets

Time zone handling with support for named zones and fixed offsets.

expect open class TimeZone {
    val id: String
    companion object {
        fun of(zoneId: String): TimeZone
        fun currentSystemDefault(): TimeZone
        val UTC: FixedOffsetTimeZone
        val availableZoneIds: Set<String>
    }
}

expect class FixedOffsetTimeZone : TimeZone {
    constructor(offset: UtcOffset)
    val offset: UtcOffset
}

expect class UtcOffset {
    val totalSeconds: Int
    companion object {
        val ZERO: UtcOffset
    }
}

Time Zones and Offsets

Date/Time Arithmetic

Period and unit-based arithmetic operations for date and time calculations.

sealed class DateTimeUnit {
    sealed class TimeBased(val nanoseconds: Long) : DateTimeUnit()
    sealed class DateBased : DateTimeUnit() {
        class DayBased(val days: Int) : DateBased()
        class MonthBased(val months: Int) : DateBased()
    }
}

sealed class DateTimePeriod {
    val years: Int
    val months: Int
    val days: Int
    val hours: Int
    val minutes: Int
    val seconds: Int
    val nanoseconds: Int
}

class DatePeriod : DateTimePeriod {
    constructor(years: Int = 0, months: Int = 0, days: Int = 0)
}

Date/Time Arithmetic

Formatting and Parsing

Comprehensive formatting system with predefined formats and custom format builders.

sealed interface DateTimeFormat<T> {
    fun format(value: T): String
    fun formatTo(appendable: Appendable, value: T): Appendable
    fun parse(input: CharSequence): T
    fun parseOrNull(input: CharSequence): T?
}

class DateTimeComponents {
    // Container for date/time components used in formatting
}

Formatting and Parsing

Ranges and Progressions

Date ranges and progressions for iterating over date sequences.

class LocalDateRange : LocalDateProgression {
    val start: LocalDate
    val endInclusive: LocalDate
    fun isEmpty(): Boolean
}

open class LocalDateProgression {
    val first: LocalDate
    val last: LocalDate
    val size: Int
    fun reversed(): LocalDateProgression
}

Ranges and Progressions

Serialization Support

Comprehensive kotlinx.serialization support with multiple serializer variants for different use cases.

// Default serializers (using toString/parse)
object InstantSerializer : KSerializer<Instant>
object LocalDateSerializer : KSerializer<LocalDate>
object LocalTimeSerializer : KSerializer<LocalTime>
object LocalDateTimeSerializer : KSerializer<LocalDateTime>

// ISO 8601 explicit serializers
object InstantIso8601Serializer : KSerializer<Instant>
object LocalDateIso8601Serializer : KSerializer<LocalDate>

// Component serializers (as structured objects)
object LocalDateComponentSerializer : KSerializer<LocalDate>
object LocalTimeComponentSerializer : KSerializer<LocalTime>

Serialization Support

Platform Integration

iOS/macOS specific integration functions for working with Foundation date types.

// Darwin (iOS/macOS) Integration
fun LocalDate.toNSDateComponents(): NSDateComponents
fun LocalDateTime.toNSDateComponents(): NSDateComponents
fun YearMonth.toNSDateComponents(): NSDateComponents
fun TimeZone.toNSTimeZone(): NSTimeZone
fun NSTimeZone.toKotlinTimeZone(): TimeZone

Platform Integration

Types

Enumeration Types

enum class Month {
    JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE,
    JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER;
    
    val number: Int
    companion object {
        operator fun invoke(number: Int): Month
    }
}

enum class DayOfWeek {
    MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY;
    
    val isoDayNumber: Int
    companion object {
        operator fun invoke(isoDayNumber: Int): DayOfWeek
    }
}

Exception Types

class DateTimeArithmeticException : RuntimeException
class IllegalTimeZoneException : IllegalArgumentException

Clock and Time Sources

// Primary clock interface (from kotlin.time)
interface Clock {
    fun now(): Instant
    companion object {
        val System: Clock
    }
}

// Extension functions
fun Clock.todayIn(timeZone: TimeZone): LocalDate