0
# kotlinx-datetime
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.kotlinx:kotlinx-datetime-iosx64
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: Add to your `build.gradle.kts`:
10
  ```kotlin
11
  dependencies {
12
      implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.7.0")
13
  }
14
  ```
15

16
## Core Imports
17

18
```kotlin
19
import kotlinx.datetime.*
20
import kotlinx.datetime.format.*
21
import kotlinx.datetime.serializers.*
22
import kotlin.time.Clock
23
import kotlin.time.Instant
24
```
25

26
## Basic Usage
27

28
```kotlin
29
import kotlinx.datetime.*
30
import kotlin.time.Clock
31

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

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

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

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

50
// Formatting and parsing
51
val formatted = date.format(LocalDate.Formats.ISO)
52
val parsed = LocalDate.parse("2023-12-25", LocalDate.Formats.ISO)
53
```
54

55
## Architecture
56

57
kotlinx-datetime is built around several key components:
58

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

67
## Capabilities
68

69
### Instant and Time Representation
70

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

73
```kotlin { .api }
74
// Primary time representation (from kotlin.time)
75
class Instant {
76
    val epochSeconds: Long
77
    val nanosecondsOfSecond: Int
78
    fun plus(duration: Duration): Instant
79
    fun minus(duration: Duration): Instant
80
    fun minus(other: Instant): Duration
81
}
82

83
// Extension functions for timezone-aware operations
84
fun Instant.toLocalDateTime(timeZone: TimeZone): LocalDateTime
85
fun Instant.toLocalDateTime(offset: UtcOffset): LocalDateTime
86
fun Instant.offsetIn(timeZone: TimeZone): UtcOffset
87
fun Instant.plus(period: DateTimePeriod, timeZone: TimeZone): Instant
88
fun Instant.minus(period: DateTimePeriod, timeZone: TimeZone): Instant
89
```
90

91
[Instant and Time Representation](./instant.md)
92

93
### Local Date and Time Types
94

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

97
```kotlin { .api }
98
expect class LocalDate {
99
    constructor(year: Int, month: Int, day: Int)
100
    constructor(year: Int, month: Month, day: Int)
101
    val year: Int
102
    val month: Month
103
    val day: Int
104
    val dayOfWeek: DayOfWeek
105
    val dayOfYear: Int
106
}
107

108
expect class LocalTime {
109
    constructor(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)
110
    val hour: Int
111
    val minute: Int
112
    val second: Int
113
    val nanosecond: Int
114
}
115

116
expect class LocalDateTime {
117
    constructor(year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)
118
    constructor(date: LocalDate, time: LocalTime)
119
    val year: Int
120
    val month: Month
121
    val day: Int
122
    val hour: Int
123
    val minute: Int
124
    val second: Int
125
    val nanosecond: Int
126
    val date: LocalDate
127
    val time: LocalTime
128
}
129
```
130

131
[Local Date and Time Types](./local-types.md)
132

133
### Time Zones and Offsets
134

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

137
```kotlin { .api }
138
expect open class TimeZone {
139
    val id: String
140
    companion object {
141
        fun of(zoneId: String): TimeZone
142
        fun currentSystemDefault(): TimeZone
143
        val UTC: FixedOffsetTimeZone
144
        val availableZoneIds: Set<String>
145
    }
146
}
147

148
expect class FixedOffsetTimeZone : TimeZone {
149
    constructor(offset: UtcOffset)
150
    val offset: UtcOffset
151
}
152

153
expect class UtcOffset {
154
    val totalSeconds: Int
155
    companion object {
156
        val ZERO: UtcOffset
157
    }
158
}
159
```
160

161
[Time Zones and Offsets](./timezones.md)
162

163
### Date/Time Arithmetic
164

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

167
```kotlin { .api }
168
sealed class DateTimeUnit {
169
    sealed class TimeBased(val nanoseconds: Long) : DateTimeUnit()
170
    sealed class DateBased : DateTimeUnit() {
171
        class DayBased(val days: Int) : DateBased()
172
        class MonthBased(val months: Int) : DateBased()
173
    }
174
}
175

176
sealed class DateTimePeriod {
177
    val years: Int
178
    val months: Int
179
    val days: Int
180
    val hours: Int
181
    val minutes: Int
182
    val seconds: Int
183
    val nanoseconds: Int
184
}
185

186
class DatePeriod : DateTimePeriod {
187
    constructor(years: Int = 0, months: Int = 0, days: Int = 0)
188
}
189
```
190

191
[Date/Time Arithmetic](./arithmetic.md)
192

193
### Formatting and Parsing
194

195
Comprehensive formatting system with predefined formats and custom format builders.
196

197
```kotlin { .api }
198
sealed interface DateTimeFormat<T> {
199
    fun format(value: T): String
200
    fun formatTo(appendable: Appendable, value: T): Appendable
201
    fun parse(input: CharSequence): T
202
    fun parseOrNull(input: CharSequence): T?
203
}
204

205
class DateTimeComponents {
206
    // Container for date/time components used in formatting
207
}
208
```
209

210
[Formatting and Parsing](./formatting.md)
211

212
### Ranges and Progressions
213

214
Date ranges and progressions for iterating over date sequences.
215

216
```kotlin { .api }
217
class LocalDateRange : LocalDateProgression {
218
    val start: LocalDate
219
    val endInclusive: LocalDate
220
    fun isEmpty(): Boolean
221
}
222

223
open class LocalDateProgression {
224
    val first: LocalDate
225
    val last: LocalDate
226
    val size: Int
227
    fun reversed(): LocalDateProgression
228
}
229
```
230

231
[Ranges and Progressions](./ranges.md)
232

233
### Serialization Support
234

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

237
```kotlin { .api }
238
// Default serializers (using toString/parse)
239
object InstantSerializer : KSerializer<Instant>
240
object LocalDateSerializer : KSerializer<LocalDate>
241
object LocalTimeSerializer : KSerializer<LocalTime>
242
object LocalDateTimeSerializer : KSerializer<LocalDateTime>
243

244
// ISO 8601 explicit serializers
245
object InstantIso8601Serializer : KSerializer<Instant>
246
object LocalDateIso8601Serializer : KSerializer<LocalDate>
247

248
// Component serializers (as structured objects)
249
object LocalDateComponentSerializer : KSerializer<LocalDate>
250
object LocalTimeComponentSerializer : KSerializer<LocalTime>
251
```
252

253
[Serialization Support](./serialization.md)
254

255
### Platform Integration
256

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

259
```kotlin { .api }
260
// Darwin (iOS/macOS) Integration
261
fun LocalDate.toNSDateComponents(): NSDateComponents
262
fun LocalDateTime.toNSDateComponents(): NSDateComponents
263
fun YearMonth.toNSDateComponents(): NSDateComponents
264
fun TimeZone.toNSTimeZone(): NSTimeZone
265
fun NSTimeZone.toKotlinTimeZone(): TimeZone
266
```
267

268
[Platform Integration](./platform.md)
269

270
## Types
271

272
### Enumeration Types
273

274
```kotlin { .api }
275
enum class Month {
276
    JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE,
277
    JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER;
278
    
279
    val number: Int
280
    companion object {
281
        operator fun invoke(number: Int): Month
282
    }
283
}
284

285
enum class DayOfWeek {
286
    MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY;
287
    
288
    val isoDayNumber: Int
289
    companion object {
290
        operator fun invoke(isoDayNumber: Int): DayOfWeek
291
    }
292
}
293
```
294

295
### Exception Types
296

297
```kotlin { .api }
298
class DateTimeArithmeticException : RuntimeException
299
class IllegalTimeZoneException : IllegalArgumentException
300
```
301

302
### Clock and Time Sources
303

304
```kotlin { .api }
305
// Primary clock interface (from kotlin.time)
306
interface Clock {
307
    fun now(): Instant
308
    companion object {
309
        val System: Clock
310
    }
311
}
312

313
// Extension functions
314
fun Clock.todayIn(timeZone: TimeZone): LocalDate
315
```