0
# Local Date and Time Types
1
2
Civil date and time types for representing calendar dates and clock times without timezone reference. These types represent "civil time" - the time you would see on a clock or calendar, independent of time zone.
3
4
## Capabilities
5
6
### LocalDate
7
8
Represents a date without time-of-day or time zone reference.
9
10
```kotlin { .api }
11
/**
12
* The date part of LocalDateTime without time zone reference
13
* Represents a date on the calendar (year, month, day)
14
*/
15
expect class LocalDate : Comparable<LocalDate> {
16
/** Create a date from year, month (1-12), and day */
17
constructor(year: Int, month: Int, day: Int)
18
19
/** Create a date from year, month enum, and day */
20
constructor(year: Int, month: Month, day: Int)
21
22
/** Year component (can be negative for BCE dates) */
23
val year: Int
24
25
/** Month as enum value */
26
val month: Month
27
28
/** Day of month (1-31) */
29
val day: Int
30
31
/** Day of week as enum value */
32
val dayOfWeek: DayOfWeek
33
34
/** Day of year (1-366) */
35
val dayOfYear: Int
36
37
/** Month as numeric value (1-12) */
38
val monthNumber: Int
39
40
/** Day of month (1-31) - alias for day */
41
val dayOfMonth: Int
42
}
43
```
44
45
**Factory Functions:**
46
47
```kotlin { .api }
48
/**
49
* Create LocalDate from epoch days (days since 1970-01-01)
50
* @param epochDays Number of days since epoch
51
* @returns LocalDate representing the date
52
*/
53
fun LocalDate.Companion.fromEpochDays(epochDays: Long): LocalDate
54
fun LocalDate.Companion.fromEpochDays(epochDays: Int): LocalDate
55
56
/**
57
* Parse LocalDate from string using specified format
58
* @param input String to parse
59
* @param format Format to use for parsing
60
* @returns Parsed LocalDate
61
* @throws IllegalArgumentException if parsing fails
62
*/
63
fun LocalDate.Companion.parse(input: CharSequence, format: DateTimeFormat<LocalDate>): LocalDate
64
65
/**
66
* Convenience constructors for LocalDate
67
*/
68
fun LocalDate(year: Int, monthNumber: Int, dayOfMonth: Int): LocalDate
69
fun LocalDate(year: Int, month: Month, dayOfMonth: Int): LocalDate
70
71
/**
72
* Parse LocalDate from string using ISO format
73
* @param input String in ISO format (YYYY-MM-DD)
74
* @returns Parsed LocalDate
75
*/
76
fun String.toLocalDate(): LocalDate
77
```
78
79
**Date Arithmetic:**
80
81
```kotlin { .api }
82
/**
83
* Add a date period to this date
84
* @param period Period containing years, months, and/or days
85
* @returns New LocalDate after adding the period
86
*/
87
fun LocalDate.plus(period: DatePeriod): LocalDate
88
89
/**
90
* Subtract a date period from this date
91
* @param period Period to subtract
92
* @returns New LocalDate after subtracting the period
93
*/
94
fun LocalDate.minus(period: DatePeriod): LocalDate
95
96
/**
97
* Add a value of the specified date-based unit
98
* @param value Amount to add
99
* @param unit Date-based unit (DAY, WEEK, MONTH, YEAR, etc.)
100
* @returns New LocalDate after adding the value
101
*/
102
fun LocalDate.plus(value: Int, unit: DateTimeUnit.DateBased): LocalDate
103
fun LocalDate.plus(value: Long, unit: DateTimeUnit.DateBased): LocalDate
104
105
/**
106
* Subtract a value of the specified date-based unit
107
* @param value Amount to subtract
108
* @param unit Date-based unit
109
* @returns New LocalDate after subtracting the value
110
*/
111
fun LocalDate.minus(value: Int, unit: DateTimeUnit.DateBased): LocalDate
112
fun LocalDate.minus(value: Long, unit: DateTimeUnit.DateBased): LocalDate
113
114
/**
115
* Add one unit of the specified date-based unit
116
* @param unit Date-based unit to add
117
* @returns New LocalDate after adding one unit
118
*/
119
fun LocalDate.plus(unit: DateTimeUnit.DateBased): LocalDate
120
121
/**
122
* Subtract one unit of the specified date-based unit
123
* @param unit Date-based unit to subtract
124
* @returns New LocalDate after subtracting one unit
125
*/
126
fun LocalDate.minus(unit: DateTimeUnit.DateBased): LocalDate
127
```
128
129
**Period Calculations:**
130
131
```kotlin { .api }
132
/**
133
* Calculate the number of whole units between this date and another
134
* @param other Target date
135
* @param unit Unit to measure in
136
* @returns Number of whole units between the dates
137
*/
138
fun LocalDate.until(other: LocalDate, unit: DateTimeUnit.DateBased): Long
139
140
/**
141
* Calculate number of days between this date and another
142
* @param other Target date
143
* @returns Number of days (can be negative if other is earlier)
144
*/
145
fun LocalDate.daysUntil(other: LocalDate): Int
146
147
/**
148
* Calculate number of months between this date and another
149
* @param other Target date
150
* @returns Number of months
151
*/
152
fun LocalDate.monthsUntil(other: LocalDate): Int
153
154
/**
155
* Calculate number of years between this date and another
156
* @param other Target date
157
* @returns Number of years
158
*/
159
fun LocalDate.yearsUntil(other: LocalDate): Int
160
161
/**
162
* Calculate the date period between this date and another
163
* @param other Target date
164
* @returns DatePeriod representing the difference
165
*/
166
fun LocalDate.periodUntil(other: LocalDate): DatePeriod
167
```
168
169
**Time Combination:**
170
171
```kotlin { .api }
172
/**
173
* Combine this date with time components to create LocalDateTime
174
* @param hour Hour (0-23)
175
* @param minute Minute (0-59)
176
* @param second Second (0-59), defaults to 0
177
* @param nanosecond Nanosecond (0-999,999,999), defaults to 0
178
* @returns LocalDateTime combining this date with the time
179
*/
180
fun LocalDate.atTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): LocalDateTime
181
182
/**
183
* Combine this date with a LocalTime to create LocalDateTime
184
* @param time The time component
185
* @returns LocalDateTime combining this date with the time
186
*/
187
fun LocalDate.atTime(time: LocalTime): LocalDateTime
188
189
/**
190
* Get the instant representing the start of this date in the given time zone
191
* @param timeZone Time zone to convert in
192
* @returns Instant representing midnight of this date in the time zone
193
*/
194
fun LocalDate.atStartOfDayIn(timeZone: TimeZone): Instant
195
```
196
197
**Conversions:**
198
199
```kotlin { .api }
200
/**
201
* Convert this date to epoch days (days since 1970-01-01)
202
* @returns Number of days since epoch
203
*/
204
fun LocalDate.toEpochDays(): Long
205
```
206
207
**Range Operations:**
208
209
```kotlin { .api }
210
/**
211
* Create an inclusive range from this date to another
212
* @param that End date (inclusive)
213
* @returns LocalDateRange from this date to that date
214
*/
215
fun LocalDate.rangeTo(that: LocalDate): LocalDateRange
216
217
/**
218
* Create a range from this date up to (but not including) another
219
* @param that End date (exclusive)
220
* @returns LocalDateRange from this date until that date
221
*/
222
fun LocalDate.rangeUntil(that: LocalDate): LocalDateRange
223
```
224
225
**Formatting:**
226
227
```kotlin { .api }
228
/**
229
* Format this date using the specified format
230
* @param format Format to use
231
* @returns Formatted string representation
232
*/
233
fun LocalDate.format(format: DateTimeFormat<LocalDate>): String
234
235
/**
236
* Convert to ISO 8601 string representation (YYYY-MM-DD)
237
* @returns ISO format string
238
*/
239
override fun LocalDate.toString(): String
240
```
241
242
**Usage Examples:**
243
244
```kotlin
245
import kotlinx.datetime.*
246
247
// Create dates
248
val date1 = LocalDate(2023, 12, 25)
249
val date2 = LocalDate(2023, Month.DECEMBER, 25)
250
val fromEpoch = LocalDate.fromEpochDays(19723) // 2024-01-01
251
252
// Date arithmetic
253
val tomorrow = date1.plus(DatePeriod(days = 1))
254
val nextMonth = date1.plus(1, DateTimeUnit.MONTH)
255
val nextYear = date1.plus(1, DateTimeUnit.YEAR)
256
257
// Calculate differences
258
val daysBetween = date1.daysUntil(tomorrow) // 1
259
val period = date1.periodUntil(nextYear) // DatePeriod(years=1)
260
261
// Combine with time
262
val dateTime = date1.atTime(14, 30, 15)
263
val withTime = date1.atTime(LocalTime(9, 0))
264
265
// Time zone conversion
266
val timeZone = TimeZone.of("America/New_York")
267
val instant = date1.atStartOfDayIn(timeZone)
268
269
// Ranges
270
val dateRange = date1..date1.plus(DatePeriod(days = 7))
271
for (day in dateRange) {
272
println(day)
273
}
274
```
275
276
### LocalTime
277
278
Represents time-of-day without date or time zone reference.
279
280
```kotlin { .api }
281
/**
282
* Time-of-day without date or time zone reference
283
* Represents clock time (hour, minute, second, nanosecond)
284
*/
285
expect class LocalTime : Comparable<LocalTime> {
286
/** Create time from components */
287
constructor(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)
288
289
/** Hour of day (0-23) */
290
val hour: Int
291
292
/** Minute of hour (0-59) */
293
val minute: Int
294
295
/** Second of minute (0-59) */
296
val second: Int
297
298
/** Nanosecond of second (0-999,999,999) */
299
val nanosecond: Int
300
}
301
```
302
303
**Factory Functions:**
304
305
```kotlin { .api }
306
/**
307
* Create LocalTime from second of day
308
* @param secondOfDay Seconds since midnight (0-86399)
309
* @returns LocalTime representing the time
310
*/
311
fun LocalTime.Companion.fromSecondOfDay(secondOfDay: Int): LocalTime
312
313
/**
314
* Create LocalTime from millisecond of day
315
* @param millisecondOfDay Milliseconds since midnight
316
* @returns LocalTime representing the time
317
*/
318
fun LocalTime.Companion.fromMillisecondOfDay(millisecondOfDay: Int): LocalTime
319
320
/**
321
* Create LocalTime from nanosecond of day
322
* @param nanosecondOfDay Nanoseconds since midnight
323
* @returns LocalTime representing the time
324
*/
325
fun LocalTime.Companion.fromNanosecondOfDay(nanosecondOfDay: Long): LocalTime
326
327
/**
328
* Parse LocalTime from string using specified format
329
* @param input String to parse
330
* @param format Format to use for parsing
331
* @returns Parsed LocalTime
332
*/
333
fun LocalTime.Companion.parse(input: CharSequence, format: DateTimeFormat<LocalTime>): LocalTime
334
335
/**
336
* Parse LocalTime from string using ISO format
337
* @param input String in ISO format (HH:MM:SS)
338
* @returns Parsed LocalTime
339
*/
340
fun String.toLocalTime(): LocalTime
341
```
342
343
**Conversions:**
344
345
```kotlin { .api }
346
/**
347
* Convert to seconds since midnight
348
* @returns Seconds since midnight (0-86399)
349
*/
350
fun LocalTime.toSecondOfDay(): Int
351
352
/**
353
* Convert to milliseconds since midnight
354
* @returns Milliseconds since midnight
355
*/
356
fun LocalTime.toMillisecondOfDay(): Int
357
358
/**
359
* Convert to nanoseconds since midnight
360
* @returns Nanoseconds since midnight
361
*/
362
fun LocalTime.toNanosecondOfDay(): Long
363
```
364
365
**Date Combination:**
366
367
```kotlin { .api }
368
/**
369
* Combine this time with date components to create LocalDateTime
370
* @param year Year
371
* @param month Month (1-12)
372
* @param day Day of month
373
* @returns LocalDateTime combining the date with this time
374
*/
375
fun LocalTime.atDate(year: Int, month: Int, day: Int): LocalDateTime
376
fun LocalTime.atDate(year: Int, month: Month, day: Int): LocalDateTime
377
378
/**
379
* Alternative overloads with explicit parameter names for disambiguation
380
*/
381
fun LocalTime.atDate(year: Int, monthNumber: Int, dayOfMonth: Int): LocalDateTime
382
fun LocalTime.atDate(year: Int, month: Month, dayOfMonth: Int): LocalDateTime
383
384
/**
385
* Combine this time with a LocalDate to create LocalDateTime
386
* @param date The date component
387
* @returns LocalDateTime combining the date with this time
388
*/
389
fun LocalTime.atDate(date: LocalDate): LocalDateTime
390
```
391
392
**Formatting:**
393
394
```kotlin { .api }
395
/**
396
* Format this time using the specified format
397
* @param format Format to use
398
* @returns Formatted string representation
399
*/
400
fun LocalTime.format(format: DateTimeFormat<LocalTime>): String
401
402
/**
403
* Convert to ISO 8601 string representation (HH:MM:SS or HH:MM:SS.sss)
404
* @returns ISO format string
405
*/
406
override fun LocalTime.toString(): String
407
```
408
409
**Usage Examples:**
410
411
```kotlin
412
import kotlinx.datetime.*
413
414
// Create times
415
val time1 = LocalTime(14, 30, 15)
416
val time2 = LocalTime(9, 0) // seconds and nanoseconds default to 0
417
val fromSeconds = LocalTime.fromSecondOfDay(52215) // 14:30:15
418
419
// Conversions
420
val secondsOfDay = time1.toSecondOfDay() // 52215
421
val millisOfDay = time1.toMillisecondOfDay()
422
val nanosOfDay = time1.toNanosecondOfDay()
423
424
// Combine with date
425
val date = LocalDate(2023, 12, 25)
426
val dateTime1 = time1.atDate(date)
427
val dateTime2 = time1.atDate(2023, 12, 25)
428
```
429
430
### LocalDateTime
431
432
Represents civil date and time without time zone reference.
433
434
```kotlin { .api }
435
/**
436
* Civil date and time without time zone reference
437
* Combines LocalDate and LocalTime into a single type
438
*/
439
expect class LocalDateTime : Comparable<LocalDateTime> {
440
/** Create from individual components */
441
constructor(year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)
442
constructor(year: Int, month: Month, day: Int, hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)
443
444
/** Create from date and time components */
445
constructor(date: LocalDate, time: LocalTime)
446
447
/** Year component */
448
val year: Int
449
450
/** Month as enum value */
451
val month: Month
452
453
/** Day of month (1-31) */
454
val day: Int
455
456
/** Day of week as enum value */
457
val dayOfWeek: DayOfWeek
458
459
/** Day of year (1-366) */
460
val dayOfYear: Int
461
462
/** Hour of day (0-23) */
463
val hour: Int
464
465
/** Minute of hour (0-59) */
466
val minute: Int
467
468
/** Second of minute (0-59) */
469
val second: Int
470
471
/** Nanosecond of second (0-999,999,999) */
472
val nanosecond: Int
473
474
/** Date part of this LocalDateTime */
475
val date: LocalDate
476
477
/** Time part of this LocalDateTime */
478
val time: LocalTime
479
}
480
```
481
482
**Factory Functions:**
483
484
```kotlin { .api }
485
/**
486
* Parse LocalDateTime from string using specified format
487
* @param input String to parse
488
* @param format Format to use for parsing
489
* @returns Parsed LocalDateTime
490
*/
491
fun LocalDateTime.Companion.parse(input: CharSequence, format: DateTimeFormat<LocalDateTime>): LocalDateTime
492
```
493
494
**Time Zone Conversions:**
495
496
```kotlin { .api }
497
/**
498
* Convert this LocalDateTime to an Instant in the specified time zone
499
* @param timeZone Time zone for conversion
500
* @returns Instant representing this LocalDateTime in the time zone
501
*/
502
fun LocalDateTime.toInstant(timeZone: TimeZone): Instant
503
504
/**
505
* Convert this LocalDateTime to an Instant using the specified offset
506
* @param offset UTC offset for conversion
507
* @returns Instant representing this LocalDateTime with the offset
508
*/
509
fun LocalDateTime.toInstant(offset: UtcOffset): Instant
510
```
511
512
**Formatting:**
513
514
```kotlin { .api }
515
/**
516
* Format this LocalDateTime using the specified format
517
* @param format Format to use
518
* @returns Formatted string representation
519
*/
520
fun LocalDateTime.format(format: DateTimeFormat<LocalDateTime>): String
521
522
/**
523
* Convert to ISO 8601 string representation (YYYY-MM-DDTHH:MM:SS)
524
* @returns ISO format string
525
*/
526
override fun LocalDateTime.toString(): String
527
```
528
529
**Usage Examples:**
530
531
```kotlin
532
import kotlinx.datetime.*
533
534
// Create LocalDateTime
535
val dateTime1 = LocalDateTime(2023, 12, 25, 14, 30, 15)
536
val dateTime2 = LocalDateTime(2023, Month.DECEMBER, 25, 14, 30, 15)
537
val date = LocalDate(2023, 12, 25)
538
val time = LocalTime(14, 30, 15)
539
val dateTime3 = LocalDateTime(date, time)
540
541
// Access components
542
println("Year: ${dateTime1.year}")
543
println("Month: ${dateTime1.month}")
544
println("Day: ${dateTime1.day}")
545
println("Hour: ${dateTime1.hour}")
546
println("Date part: ${dateTime1.date}")
547
println("Time part: ${dateTime1.time}")
548
549
// Convert to Instant
550
val timeZone = TimeZone.of("America/New_York")
551
val instant = dateTime1.toInstant(timeZone)
552
553
val offset = UtcOffset(hours = -5)
554
val instantWithOffset = dateTime1.toInstant(offset)
555
```
556
557
### YearMonth
558
559
Represents year-month part without day-of-month, useful for representing months or for month-based operations.
560
561
```kotlin { .api }
562
/**
563
* Year-month part without day-of-month
564
* Represents a specific month in a specific year
565
*/
566
expect class YearMonth : Comparable<YearMonth> {
567
/** Create from year and month number */
568
constructor(year: Int, month: Int)
569
570
/** Create from year and month enum */
571
constructor(year: Int, month: Month)
572
573
/** Year component */
574
val year: Int
575
576
/** Month as enum value */
577
val month: Month
578
579
/** First day of this month */
580
val firstDay: LocalDate
581
582
/** Last day of this month */
583
val lastDay: LocalDate
584
585
/** Number of days in this month */
586
val numberOfDays: Int
587
588
/** Range of all days in this month */
589
val days: LocalDateRange
590
}
591
```
592
593
**Factory Functions:**
594
595
```kotlin { .api }
596
/**
597
* Parse YearMonth from string using specified format
598
* @param input String to parse
599
* @param format Format to use for parsing
600
* @returns Parsed YearMonth
601
*/
602
fun YearMonth.Companion.parse(input: CharSequence, format: DateTimeFormat<YearMonth>): YearMonth
603
```
604
605
**Month Arithmetic:**
606
607
```kotlin { .api }
608
/**
609
* Add a value of the specified month-based unit
610
* @param value Amount to add
611
* @param unit Month-based unit (MONTH, QUARTER, YEAR, etc.)
612
* @returns New YearMonth after adding the value
613
*/
614
fun YearMonth.plus(value: Int, unit: DateTimeUnit.MonthBased): YearMonth
615
fun YearMonth.plus(value: Long, unit: DateTimeUnit.MonthBased): YearMonth
616
617
/**
618
* Subtract a value of the specified month-based unit
619
* @param value Amount to subtract
620
* @param unit Month-based unit
621
* @returns New YearMonth after subtracting the value
622
*/
623
fun YearMonth.minus(value: Int, unit: DateTimeUnit.MonthBased): YearMonth
624
fun YearMonth.minus(value: Long, unit: DateTimeUnit.MonthBased): YearMonth
625
```
626
627
**Period Calculations:**
628
629
```kotlin { .api }
630
/**
631
* Calculate the number of whole units between this YearMonth and another
632
* @param other Target YearMonth
633
* @param unit Unit to measure in
634
* @returns Number of whole units between the months
635
*/
636
fun YearMonth.until(other: YearMonth, unit: DateTimeUnit.MonthBased): Long
637
638
/**
639
* Calculate number of months between this YearMonth and another
640
* @param other Target YearMonth
641
* @returns Number of months
642
*/
643
fun YearMonth.monthsUntil(other: YearMonth): Int
644
645
/**
646
* Calculate number of years between this YearMonth and another
647
* @param other Target YearMonth
648
* @returns Number of years
649
*/
650
fun YearMonth.yearsUntil(other: YearMonth): Int
651
```
652
653
**Date Creation:**
654
655
```kotlin { .api }
656
/**
657
* Create a LocalDate by specifying the day of this month
658
* @param day Day of month (1 to numberOfDays)
659
* @returns LocalDate for the specified day of this month
660
*/
661
fun YearMonth.onDay(day: Int): LocalDate
662
```
663
664
**Convenience Functions:**
665
666
```kotlin { .api }
667
/**
668
* Add one year to this YearMonth
669
* @returns YearMonth representing next year, same month
670
*/
671
fun YearMonth.plusYear(): YearMonth
672
673
/**
674
* Subtract one year from this YearMonth
675
* @returns YearMonth representing previous year, same month
676
*/
677
fun YearMonth.minusYear(): YearMonth
678
679
/**
680
* Add one month to this YearMonth
681
* @returns YearMonth representing next month
682
*/
683
fun YearMonth.plusMonth(): YearMonth
684
685
/**
686
* Subtract one month from this YearMonth
687
* @returns YearMonth representing previous month
688
*/
689
fun YearMonth.minusMonth(): YearMonth
690
```
691
692
**Range Operations:**
693
694
```kotlin { .api }
695
/**
696
* Create an inclusive range from this YearMonth to another
697
* @param that End YearMonth (inclusive)
698
* @returns YearMonthRange from this month to that month
699
*/
700
fun YearMonth.rangeTo(that: YearMonth): YearMonthRange
701
702
/**
703
* Create a range from this YearMonth up to (but not including) another
704
* @param that End YearMonth (exclusive)
705
* @returns YearMonthRange from this month until that month
706
*/
707
fun YearMonth.rangeUntil(that: YearMonth): YearMonthRange
708
```
709
710
**Extension Properties:**
711
712
```kotlin { .api }
713
/**
714
* Get the YearMonth for this LocalDate
715
*/
716
val LocalDate.yearMonth: YearMonth
717
```
718
719
**Usage Examples:**
720
721
```kotlin
722
import kotlinx.datetime.*
723
724
// Create YearMonth
725
val ym1 = YearMonth(2023, 12)
726
val ym2 = YearMonth(2023, Month.DECEMBER)
727
728
// Access properties
729
println("Year: ${ym1.year}")
730
println("Month: ${ym1.month}")
731
println("First day: ${ym1.firstDay}") // 2023-12-01
732
println("Last day: ${ym1.lastDay}") // 2023-12-31
733
println("Days in month: ${ym1.numberOfDays}") // 31
734
735
// Create dates in this month
736
val christmas = ym1.onDay(25) // 2023-12-25
737
738
// Month arithmetic
739
val nextMonth = ym1.plusMonth() // 2024-01
740
val nextYear = ym1.plusYear() // 2024-12
741
val add6Months = ym1.plus(6, DateTimeUnit.MONTH) // 2024-06
742
743
// Iterate over days in month
744
for (day in ym1.days) {
745
println(day)
746
}
747
748
// Get YearMonth from LocalDate
749
val date = LocalDate(2023, 12, 25)
750
val yearMonth = date.yearMonth // 2023-12
751
```
752
753
## Predefined Formats
754
755
Each local type provides predefined formatting constants:
756
757
```kotlin { .api }
758
// LocalDate formats
759
object LocalDate.Formats {
760
val ISO: DateTimeFormat<LocalDate> // YYYY-MM-DD
761
val ISO_BASIC: DateTimeFormat<LocalDate> // YYYYMMDD
762
}
763
764
// LocalTime formats
765
object LocalTime.Formats {
766
val ISO: DateTimeFormat<LocalTime> // HH:MM:SS or HH:MM:SS.sss
767
}
768
769
// LocalDateTime formats
770
object LocalDateTime.Formats {
771
val ISO: DateTimeFormat<LocalDateTime> // YYYY-MM-DDTHH:MM:SS
772
}
773
774
// YearMonth formats
775
object YearMonth.Formats {
776
val ISO: DateTimeFormat<YearMonth> // YYYY-MM
777
}
778
```