Libraries

kotlinx-datetime 0.2.0 ist da

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!

Bitte beachten Sie, dass kotlinx-datetime 0.2.0 noch experimentell ist. Die API kann sich jederzeit ändern.

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:

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.

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.

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:

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

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).