Getting Started

Add Datetime to your project and start working with dates, times, and timezones.

1. Add the dependency

In your build.gradle.kts:

dependencies {
    implementation("io.peekandpoke.ultra:datetime:0.117.0")
}

Find the latest version on Maven Central.

Datetime is a Kotlin Multiplatform library — it works in commonMain, jvmMain, jsMain, and nativeMain (linuxX64, linuxArm64, macosArm64, mingwX64).

2. Create dates and times

All types have factory methods and ISO-string parsing:

import io.peekandpoke.ultra.datetime.MpLocalDate
import io.peekandpoke.ultra.datetime.MpLocalTime
import io.peekandpoke.ultra.datetime.MpLocalDateTime
import io.peekandpoke.ultra.datetime.MpInstant
import io.peekandpoke.ultra.datetime.MpTimezone

// From components
val date = MpLocalDate.of(2025, 3, 15)
val time = MpLocalTime.of(14, 30, 0)
val dateTime = MpLocalDateTime.of(2025, 3, 15, 14, 30, 0)

// From ISO strings
val parsed = MpLocalDate.parse("2025-03-15")
val instant = MpInstant.parse("2025-03-15T14:30:00Z")

// Safe parsing
val maybe = MpLocalDate.tryParse("not-a-date")  // null

3. Arithmetic

Add and subtract days, months, years, and more:

val date = MpLocalDate.of(2025, 1, 31)

val nextMonth = date.plusMonths(1)    // 2025-02-28 (clamped)
val nextYear = date.plusYears(1)      // 2026-01-31
val lastWeek = date.minusDays(7)     // 2025-01-24

// Anchoring
val startOfMonth = date.atStartOfMonth()     // 2025-01-01
val startOfYear = date.atStartOfYear()       // 2025-01-01
val startOfQuarter = date.atStartOfQuarterOfYear()  // 2025-01-01

4. Timezones

Convert between absolute and local representations:

val instant = MpInstant.parse("2025-06-15T12:00:00Z")
val berlin = MpTimezone.of("Europe/Berlin")
val tokyo = MpTimezone.of("Asia/Tokyo")

val inBerlin = instant.atZone(berlin)
println(inBerlin.toLocalDateTime())  // 2025-06-15T14:00 (UTC+2 in summer)

val inTokyo = instant.atZone(tokyo)
println(inTokyo.toLocalDateTime())   // 2025-06-15T21:00 (UTC+9)

// Back to instant
val backToUtc = inBerlin.toInstant()
println(backToUtc == instant)  // true

5. Formatting

Format dates and times with pattern strings:

val zoned = instant.atZone(berlin)

println(zoned.format("dd MMM yyyy"))       // "15 Jun 2025"
println(zoned.format("yyyy-MM-dd HH:mm"))  // "2025-06-15 14:00"

// Convenience methods
println(date.formatDdMmmYyyy())  // "15 Jun 2025"
The formatter never throws — malformed patterns degrade gracefully. You'll get output, just maybe not what you expected.

6. JVM interop

On the JVM, convert seamlessly to and from java.time:

// Mp -> java.time
val javaInstant: java.time.Instant = mpInstant.jvm
val javaDate: java.time.LocalDate = mpDate.jvm
val javaZoned: java.time.ZonedDateTime = mpZoned.jvm

// java.time -> Mp
val mpInstant: MpInstant = javaInstant.mp
val mpDate: MpLocalDate = javaDate.mp
val mpZoned: MpZonedDateTime = javaZoned.mp

On every target, the same .kotlinx / .mp pair converts to and from kotlinx-datetime:

val instant: kotlin.time.Instant = mpInstant.kotlinx
val date: kotlinx.datetime.LocalDate = mpDate.kotlinx
val zone: kotlinx.datetime.TimeZone = mpTimezone.kotlinx

val mpDate: MpLocalDate = date.mp