or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-types.mdformatting.mdindex.mdjvm-interop.mdperiods-units.mdserialization.md
tile.json

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

A multiplatform Kotlin library for working with date and time with JVM target support.

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

To install, run

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

index.mddocs/

kotlinx-datetime

A multiplatform Kotlin library for working with date and time that provides types for representing date and time values with clear separation between physical time instants and civil time components. Based on ISO 8601 standards with comprehensive formatting, serialization, and JVM interoperability support.

Package Information

  • Package Name: org.jetbrains.kotlinx:kotlinx-datetime-jvm
  • Package Type: maven
  • Language: Kotlin
  • Installation: Add to your Gradle dependencies: 
    implementation("org.jetbrains.kotlinx:kotlinx-datetime-jvm:0.7.0")

Core Imports

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlinx.datetime.serializers.*
import kotlin.time.Duration

Basic Usage

import kotlinx.datetime.*
import kotlin.time.Duration.Companion.days
import kotlin.time.Duration.Companion.hours

// Get current instant and convert to local date-time
val now = Clock.System.now()
val localDateTime = now.toLocalDateTime(TimeZone.currentSystemDefault())

// Create specific dates and times
val date = LocalDate(2023, 12, 25) // Christmas 2023
val time = LocalTime(14, 30) // 2:30 PM
val dateTime = LocalDateTime(date, time)
val yearMonth = YearMonth(2024, 3) // March 2024

// Date arithmetic
val futureDate = date.plus(30, DateTimeUnit.DAY)
val daysBetween = date.daysUntil(futureDate)

// Convert to instant with timezone
val instant = dateTime.toInstant(TimeZone.of("America/New_York"))

// Format dates and times
val formattedDate = date.format(LocalDate.Formats.ISO) // "2023-12-25"
val formattedDateTime = dateTime.format(LocalDateTime.Formats.ISO) // "2023-12-25T14:30:00"

Architecture

kotlinx-datetime is built around several key concepts:

  • Physical Time: Instant represents a specific moment in time, independent of time zones
  • Civil Time: LocalDate, LocalTime, and LocalDateTime represent calendar concepts without time zone context
  • Time Zones: TimeZone provides conversion between physical and civil time with full timezone rules support
  • Periods & Units: Flexible arithmetic operations with DateTimePeriod, DatePeriod, and DateTimeUnit
  • Format System: Comprehensive parsing and formatting with builder DSL and predefined formats
  • Type Safety: Immutable value types with clear boundaries and compile-time guarantees
  • Interoperability: Seamless conversion to/from java.time types for JVM integration

Capabilities

Core Types & Operations

Essential date and time types with arithmetic operations, conversions, and timezone handling. Provides the foundation for all datetime operations.

// Physical time - specific moment in time
class Instant

// Civil time components - calendar concepts without timezone
data class LocalDate(val year: Int, val month: Month, val dayOfMonth: Int)
data class LocalTime(val hour: Int, val minute: Int, val second: Int = 0, val nanosecond: Int = 0)
data class LocalDateTime(val date: LocalDate, val time: LocalTime)
data class YearMonth(val year: Int, val month: Month)

// UTC offset and timezone handling
class UtcOffset(hours: Int, minutes: Int = 0)
abstract class TimeZone {
    val id: String
    companion object {
        val UTC: TimeZone
        fun of(zoneId: String): TimeZone
        fun currentSystemDefault(): TimeZone
        val availableZoneIds: Set<String>
    }
}

// Clock extensions
fun Clock.todayIn(timeZone: TimeZone): LocalDate

// Enumerations
enum class Month { JANUARY, FEBRUARY, /* ... */ DECEMBER }
enum class DayOfWeek { MONDAY, TUESDAY, /* ... */ SUNDAY }

Core Types & Operations

Periods & Units

Period representations and arithmetic units for flexible date and time calculations. Essential for adding/subtracting time intervals and measuring differences.

// Period with date and time components
data class DateTimePeriod(
    val years: Int = 0,
    val months: Int = 0, 
    val days: Int = 0,
    val hours: Int = 0,
    val minutes: Int = 0,
    val seconds: Int = 0,
    val nanoseconds: Long = 0
)

// Period with only date components
data class DatePeriod(val years: Int = 0, val months: Int = 0, val days: Int = 0)

// Units for arithmetic operations
sealed class DateTimeUnit {
    sealed class TimeBased : DateTimeUnit()
    sealed class DateBased : DateTimeUnit()
    
    companion object {
        val NANOSECOND: TimeBased
        val SECOND: TimeBased
        val MINUTE: TimeBased
        val HOUR: TimeBased
        val DAY: DateBased
        val MONTH: DateBased
        val YEAR: DateBased
    }
}

Periods & Units

Formatting System

Comprehensive parsing and formatting system with builder DSL, predefined formats, and custom format creation. Supports all datetime types with locale-aware formatting.

// Base format interface
sealed interface DateTimeFormat<T> {
    fun format(value: T): String
    fun parse(input: CharSequence): T
    fun parseOrNull(input: CharSequence): T?
}

// Format builders for each type
fun LocalDate.Companion.Format(block: DateTimeFormatBuilder.WithDate.() -> Unit): DateTimeFormat<LocalDate>
fun LocalTime.Companion.Format(block: DateTimeFormatBuilder.WithTime.() -> Unit): DateTimeFormat<LocalTime>
fun LocalDateTime.Companion.Format(block: DateTimeFormatBuilder.WithDateTime.() -> Unit): DateTimeFormat<LocalDateTime>

// Predefined formats
object LocalDate.Formats {
    val ISO: DateTimeFormat<LocalDate>
}
object LocalDateTime.Formats {
    val ISO: DateTimeFormat<LocalDateTime>
}

Formatting System

Serialization Support

Complete serialization support for all datetime types with both ISO 8601 string format and component-based JSON object serialization. Integrates with kotlinx.serialization.

// ISO 8601 string serializers
object InstantIso8601Serializer : KSerializer<Instant>
object LocalDateIso8601Serializer : KSerializer<LocalDate>
object LocalTimeIso8601Serializer : KSerializer<LocalTime>
object LocalDateTimeIso8601Serializer : KSerializer<LocalDateTime>
object TimeZoneSerializer : KSerializer<TimeZone>

// Component serializers (JSON objects)
object LocalDateComponentSerializer : KSerializer<LocalDate>
object LocalTimeComponentSerializer : KSerializer<LocalTime>
object LocalDateTimeComponentSerializer : KSerializer<LocalDateTime>
object DateTimePeriodComponentSerializer : KSerializer<DateTimePeriod>

Serialization Support

JVM Interoperability

Bidirectional converter functions for seamless integration with existing Java codebases using java.time types. Provides zero-overhead conversion between kotlinx-datetime and java.time.

// LocalDate converters
fun LocalDate.toJavaLocalDate(): java.time.LocalDate
fun java.time.LocalDate.toKotlinLocalDate(): LocalDate

// LocalTime converters
fun LocalTime.toJavaLocalTime(): java.time.LocalTime
fun java.time.LocalTime.toKotlinLocalTime(): LocalTime

// LocalDateTime converters
fun LocalDateTime.toJavaLocalDateTime(): java.time.LocalDateTime
fun java.time.LocalDateTime.toKotlinLocalDateTime(): LocalDateTime

// Instant converters
fun Instant.toJavaInstant(): java.time.Instant
fun java.time.Instant.toKotlinInstant(): Instant

// TimeZone converters
fun TimeZone.toJavaZoneId(): java.time.ZoneId
fun java.time.ZoneId.toKotlinTimeZone(): TimeZone

JVM Interoperability

Exception Types

kotlinx-datetime defines specific exception types for different error conditions:

// Arithmetic overflow or bounds errors
class DateTimeArithmeticException : IllegalArgumentException

// Invalid timezone operations
class IllegalTimeZoneException : IllegalArgumentException