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