kotlinx-datetime

When dealing with partial data (e.g., just month and day) or invalid/out-of-bounds values (e.g., 23:59:60), use DateTimeComponents. This allows you to parse the data, mutate it to a valid state, and then convert it to a standard type.

// Parsing partial data
val monthDay = DateTimeComponents.Format { monthNumber(); char('/'); day() }
    .parse("12/25")

// Handling out-of-bounds seconds
val time = DateTimeComponents.Format { time(LocalTime.Formats.ISO) }
    .parse("23:59:60").apply {
        if (second == 60) second = 59
    }.toLocalTime()

// Formatting complex data
val rfcString = DateTimeComponents.Formats.RFC_1123.format {
    setDate(LocalDate(2023, 1, 7))
    hour = 23
    minute = 59
    second = 60
    setOffset(UtcOffset(hours = 2))
}

The library maintains a mapping between IANA timezone names and Windows-specific registry names. If the mapping is outdated, you can update it using a Gradle task.

Steps to update:

1. Update your local master branch.
2. Run the download task: ./gradlew downloadWindowsZonesMapping.
3. If the task succeeds, the mappings are already up-to-date.
4. If the task fails with The new mappings were written to the filesystem., verify the changes with git diff.
5. Commit the changes to a new branch and follow the standard release and CI verification process.

# Update the master branch
git checkout master
git pull

# Run the mapping update task
./gradlew downloadWindowsZonesMapping

# If changes were written, commit them
git checkout -b update-windows-tz-names
git commit -a -m "Update the Windows/IANA timezone name mappings"
git push -u origin update-windows-tz-names

When using Maven, you must use the platform-specific -jvm artifact.

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-datetime-jvm</artifactId>
    <version>0.8.0</version>
</dependency>

To use kotlinx-datetime in your project, ensure mavenCentral() is in your repositories block.

For Multiplatform projects, add the dependency to the commonMain source set.

For Single-platform projects, add it to the standard dependencies block.

// Multiplatform project
kotlin {
    sourceSets {
        commonMain {
             dependencies {
                 implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.8.0")
             }
        }
    }
}

// Single-platform project
dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.8.0")
}

Use the following guidance to select the appropriate type for your use case:

For non-ISO 8601 formats, use the Format DSL. You can define custom patterns or use Unicode-style patterns.

Note: Using non-constant Unicode patterns requires the @OptIn(FormatStringsInDatetimeFormats::class) annotation.

// Custom DSL format
val dateFormat = LocalDate.Format {
    monthNumber(padding = Padding.SPACE)
    char('/')
    day()
    char(' ')
    year()
}
val date = dateFormat.parse("12/24 2023")

// Unicode pattern with OptIn
@OptIn(FormatStringsInDatetimeFormats::class)
val formatPattern = "yyyy-MM-dd'T'HH:mm:ss[.SSS]"
val dateTimeFormat = LocalDateTime.Format {
    byUnicodePattern(formatPattern)
}
val parsed = dateTimeFormat.parse("2023-12-24T23:59:59")

By default, Kotlin/Wasm WASI only provides the UTC time zone. To enable all time zones, add the kotlinx-datetime-zoneinfo dependency.

kotlin {
    sourceSets {
        val wasmWasiMain by getting {
            dependencies {
                implementation("kotlinx-datetime-zoneinfo", "2026c-spi.0.8.0")
            }
        }
    }
}

Wasm/JS follows the same pattern as Kotlin/JS. Add the @js-joda/timezone npm dependency and initialize the module.

// 1. Add npm dependency in Gradle
kotlin {
    sourceSets {
        val wasmJsMain by getting {
            dependencies {
                implementation(npm("@js-joda/timezone", "X.X.X"))
            }
        }
    }
}

// 2. Initialize in your code
@JsModule("@js-joda/timezone")
external object JsJodaTimeZoneModule

private val jsJodaTz = JsJodaTimeZoneModule

Arithmetic on LocalDateTime is intentionally omitted to prevent errors caused by Daylight Saving Time (DST) transitions (e.g., 'spring forward' gaps).

Best Practice: Perform all arithmetic on Instant values using a TimeZone, then convert the resulting Instant back to LocalDateTime for display.

val timeZone = TimeZone.of("Europe/Berlin")
val localDateTime = LocalDateTime.parse("2021-03-27T02:16:20")
val instant = localDateTime.toInstant(timeZone)

// Perform arithmetic on the Instant
val instantOneDayLater = instant.plus(1, DateTimeUnit.DAY, timeZone)

// Convert back to LocalDateTime
val localDateTimeOneDayLater = instantOneDayLater.toLocalDateTime(timeZone)