MpTimezone

Wraps an IANA timezone identifier. The context required whenever you cross the boundary between local and absolute time.

When to use MpTimezone

• User timezone preferences ("this user is in Europe/Berlin")
• Converting between MpInstant and local types
• DST-aware calendar arithmetic on MpInstant
• Storing timezone choices in databases and APIs

Creating

import io.peekandpoke.ultra.datetime.MpTimezone

val berlin = MpTimezone.of("Europe/Berlin")
val newYork = MpTimezone.of("America/New_York")
val utc = MpTimezone.UTC
val system = MpTimezone.systemDefault

Querying offsets

Timezone offsets change with DST. Query the offset at a specific instant to get the correct value:

val berlin = MpTimezone.of("Europe/Berlin")

val summer = MpInstant.parse("2025-06-15T12:00:00Z")
val winter = MpInstant.parse("2025-12-15T12:00:00Z")

berlin.offsetAt(summer)          // +02:00 (CEST)
berlin.offsetAt(winter)          // +01:00 (CET)

berlin.offsetSecondsAt(summer)   // 7200
berlin.offsetMillisAt(summer)    // 7200000

Supported timezones

MpTimezone supports 600+ IANA timezone identifiers from the standard database, including:

• Africa — 76 zones (Africa/Cairo, Africa/Nairobi, ...)
• Americas — 150+ zones (America/New_York, America/Los_Angeles, America/Sao_Paulo, ...)
• Asia — 100+ zones (Asia/Tokyo, Asia/Shanghai, Asia/Kolkata, ...)
• Europe — 60+ zones (Europe/London, Europe/Berlin, Europe/Moscow, ...)
• Pacific/Atlantic/Indian/Antarctica — 50+ zones each
• UTC variants — UTC, Etc/GMT, Etc/GMT+1 through Etc/GMT-14

Query the full list at runtime:

val allIds: Set<String> = MpTimezone.supportedIds
println(allIds.size)  // 600+

kotlinx-datetime interop

import kotlinx.datetime.TimeZone

// MpTimezone -> kotlinx TimeZone
val kotlinxTz: TimeZone = mpTimezone.kotlinx

// kotlinx TimeZone -> MpTimezone
val mpTz: MpTimezone = kotlinxTimezone.mp

JVM interop

// MpTimezone -> java.time.ZoneId
val zoneId: java.time.ZoneId = java.time.ZoneId.of(mpTimezone.id)

// java.time.ZoneId -> MpTimezone
val mpTz = MpTimezone.of(zoneId.id)

Serialization

MpTimezone serializes as its string ID, making it trivial to store and transmit:

@Serializable
data class UserPreferences(
    val timezone: MpTimezone,
)

// Serialized as: {"timezone": "Europe/Berlin"}