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
```