kotlinx-datetime 0.2.0 ist da

Sergiy Rogalin

Read this post in other languages:

• English
,
• 日本語
,
• 한국어
,
• Русский
,
• 简体中文

Heute stellen wir kotlinx-datetime 0.2.0 vor — eine neue Version unserer Multiplattform-Bibliothek für die Arbeit mit Daten und Zeiten, die zusammen mit Kotlin 1.5.0 veröffentlicht wurde. Wir haben die allererste Version der Bibliothek letzten Sommer veröffentlicht, und dies ist unser nächster Schritt auf dem Weg zu einem stabilen Release.

Wir haben kotlinx-datetime auf dem Kotlin 1.4 Online Event vorgestellt: Sie können sich diesen Vortrag von Ilya Gorbunov ansehen, um mehr über die Designprinzipien und Funktionen der Bibliothek zu erfahren. Sollten Sie Fragen zu kotlinx-datetime haben, empfehlen wir Ihnen, am kommenden Kotlin 1.5 Online-Event teilzunehmen und Ihre Fragen an das Kotlin-Team zu stellen.

Für Online-Event registrieren

Die Version 0.2.0 kommt mit zahlreichen Verbesserungen:

• Unterstützung von kotlinx.serialization
• Normalisierung von DateTimePeriod-Komponenten
• Parsing für Instant aus einem String mit einem UTC-Offset

Probieren Sie es aus! – Stellen Sie nur sicher, dass Sie Kotlin Version 1.5.0 installiert haben. Schauen wir uns die Funktionen genauer an!

Unterstützung von kotlinx.serialization

kotlinx-datetime bietet eigene Typen zur Darstellung von Datum und Uhrzeit: wie Instant, LocalDate, und TimeZone. Mit Version 0.2.0 sind nun alle diese Typen serialisierbar, da sie von der kotlinx.serialization-Bibliothek unterstützt werden. Wir stellen die Menge der Serialisierer im Paket kotlinx.datetime.serializers bereit, das Sie gebündelt in der Bibliothek finden.

Die meisten Typen haben nun den Standard-Serialisierer. Die Typen, die dies haben, sind Instant, LocalDate, LocalDateTime, DateTimePeriod, DatePeriod, TimeZone, und ZoneOffset. Sie können als Eigenschaften in Ihren serialisierbaren Klassen ohne explizite Annotationen verwendet werden:

import kotlinx.datetime.LocalDate
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.encodeToString

@Serializable
class Person(val name: String, val birthDate: LocalDate)

fun main() {
    val harry = Person("Harry", LocalDate(1980, 7, 31))
    println(Json.encodeToString(harry))
    // {"name":"Harry","birthDate":"1980-07-31"}
}

Der Standard-Serialisierer basiert auf einer ISO 8601-Stringdarstellung eines Typs und verwendet toString()/parse(), um Werte zu serialisieren und zu deserialisieren.

Einige der Typen verfügen über alternative Serialisierer, um die Verwendung unterschiedlicher Serialisierungsstrategien zu ermöglichen, die bei bestimmten Formaten effizienter als der Standard sein können. Zum Beispiel kann LocalDate komponentenweise mit LocalDateComponentSerializer serialisiert werden. Um einen Serialisierer explizit zu wählen, verwenden Sie die reguläre @Serializable(with = ...) Annotation. Sie können diese Wahl auch auf die Laufzeit verschieben, indem Sie den kontextbezogenen Serializer verwenden.

import kotlinx.datetime.LocalDate
import kotlinx.datetime.serializers.LocalDateComponentSerializer
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.encodeToString

@Serializable
class Person(
    val name: String,
    @Serializable(with = LocalDateComponentSerializer::class)
    val birthDate: LocalDate
)

fun main() {
    val harry = Person("Harry", LocalDate(1980, 7, 31))
    println(Json.encodeToString(harry))
    // {"name":"Harry","birthday":{"year":1980,"month":7,"day":31}}
}

Es gibt auch Typen, die keinen Serialisierer haben: DayOfWeek und Month werden von kotlinx.serialization als einfache Enums unterstützt.

Beachten Sie, dass kotlinx.serialization eine optionale Abhängigkeit von kotlinx-datetime ist. Um die Serialisierungsfunktionen zu nutzen, fügen Sie Ihrem Projekt neben kotlinx-datetime die Abhängigkeit kotlinx-serialization-core hinzu.

Normalisierung von DateTimePeriod-Komponenten

Die Klasse DateTimePeriod repräsentiert den Zeitraum zwischen 2 Zeitpunkten als eine Kombination verschiedener Zeiteinheitstypen: Jahre, Monate, Tage, Stunden, Minuten, Sekunden und Nanosekunden. Für jeden dieser Zeiteinheitstypen hat die Klasse eine entsprechende Eigenschaft, die einen Wert vom Konstruktorparameter erhält, z.B.: DateTimePeriod(months = 14, minutes = 90).

Bisher waren die Komponenten unabhängig und hielten nur die an den Konstruktor übergebenen Werte. Dies konnte jedoch zu Fällen führen, in denen zwei Objekte mit unterschiedlichen Komponentenwerten nicht gleich waren, aber die gleiche ISO-Darstellung hatten. Die Serialisierung eines solchen Wertes und die anschließende Deserialisierung konnte zu einem anderen Wert als dem ursprünglichen führen.

In dieser Version haben wir die interne Darstellung von DateTimePeriod geändert und einen Schritt zur Normalisierung der Komponenten zu seinem Konstruktor hinzugefügt. Die Komponenten werden nun intern auf eine Kombination aus Nanosekunden, Tagen und Monaten normalisiert, was das anfängliche Problem löst und außerdem dafür sorgt, dass der vom Getter der Komponenteneigenschaft zurückgegebene Wert auch dann leicht zu lesen ist, wenn er groß ist.

val period1 = DateTimePeriod(months = 14, minutes = 90)
val period2 = DateTimePeriod(years = 1, months = 2, hours = 1, minutes = 30)
println(period1 == period2)  // true
println(period1)             // P1Y2MT1H30M // ISO-8601
println(period2)             // P1Y2MT1H30M // ISO-8601
println(period1.years)       // 1
println(period1.months)      // 2
println(period1.days)        // 0
println(period1.hours)       // 1
println(period1.minutes)     // 30
println(period1.seconds)     // 0
println(period1.nanoseconds) // 0

Parsing für Instant aus einem String mit einem UTC-Offset

Die Klasse Instant repräsentiert einen bestimmten Zeitpunkt. Die Bibliothek ermöglicht Parsing aus einem String mit Datums- und Zeitdarstellungen, die dem ISO 8601-Standard entsprechen.

Vor 0.2.0 haben wir nur das Format mit der Zeitzonenbezeichnung Z am Ende akzeptiert, wie z.B. in 2021-01-02T03:02:01Z, was bedeutet, dass die Zeit im UTC+0-Offset angegeben ist. Von nun an unterstützen wir auch UTC-Offsets ungleich Null:

val instant1 = Instant.parse("2021-01-02T03:02:01Z")
val instant2 = Instant.parse("2021-01-02T06:02:01+03:00")
println(instant1) // 2021-01-02T03:02:01Z
println(instant2) // 2021-01-02T03:02:01Z

Probieren Sie es aus

kotlinx-datetime 0.2.0 ist in der Maven Central verfügbar. Um es in Ihrem Projekt auszuprobieren:

• Überprüfen Sie, ob Sie Maven Central als Repository eingestellt haben.

repositories {
    mavenCentral()
}

• Fügen Sie kotlinx-datetime als Abhängigkeit hinzu (vergessen Sie nicht, eine Quellengruppe anzugeben, wenn Sie an einem Multiplattform-Projekt arbeiten).

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.2.0")
}

Eine detaillierte Anleitung zur Bibliothek finden Sie in unserer README.

Geben Sie uns Feedback

Die Bibliothek ist experimentell, und die API kann sich noch ändern. Wir sind auf dem Weg zu einem stabilen Release und würden uns sehr über Ihr Feedback freuen.

Probieren Sie kotlinx-datetime 0.2.0 aus und teilen Sie uns Ihre Erfahrungen mit! Melden Sie alle Probleme, auf die Sie stoßen, im Issue-Tracker des Projekts und stellen Sie alle Fragen, die Sie haben, in unserem Slack-Kanal (Sie können hier eine Einladung erhalten).

Subscribe to Kotlin Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!