kotlinx-datetime 0.2.0 リリース

Elizaveta Semakova

Read this post in other languages:

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

本日は日時処理用のマルチプラットフォームライブラリの新バージョンであり、Kotlin 1.5.0 と同時にリリースされた kotlinx-datetime 0.2.0 をご紹介します。 私たちはこのライブラリの最初のバージョンを昨年の夏にリリースしました。次のステップとしては安定版のリリースを目指しています。

また、kotlinx-datetime は Kotlin 1.4 オンラインイベントでも紹介しました。このライブラリの設計原理と機能の詳細は、Ilya Gorbunov によるこちらの講演をご覧ください。

バージョン 0.2.0 には多数の改善点が盛り込まれています。

• kotlinx.serialization のサポート
• DateTimePeriod コンポーネントの正規化
• UTC オフセットを含む文字列を Instant としてパースする機能

ぜひお試しください！ – ただし、Kotlin バージョン 1.5.0 を必ずインストールするようにしてください。 では、各機能を詳しく見てみましょう！

kotlinx.serialization のサポート

kotlinx-datetime は Instant、LocalDate、TimeZone など、日時表現に使用できる独自の型を提供します。 これらすべての型は kotlinx.serialization ライブラリがサポートしているため、バージョン 0.2.0 からシリアル化できるようになりました。 シリアライザーのセットは kotlinx.datetime.serializers パッケージに含まれており、ライブラリにバンドルする形で提供しています。

ほとんどの型にはデフォルトのシリアライザーがあります。 動作する型は Instant、LocalDate、LocalDateTime、DateTimePeriod、DatePeriod、TimeZone、ZoneOffset です。 これらは明示的なアノテーションを付けることなく Serializable クラスのプロパティとして使用できます。

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"}
}

デフォルトのシリアライザーは型の ISO 8601 文字列表記に基づいており、toString()/parse() を使用して値のシリアル化と逆シリアル化を行います。

一部の型には別のシリアル化戦略を使用できる代替のシリアライザーがあり、このようなシリアライザーは特定の形式においてデフォルトのシリアライザーよりも効率性に優れています。 例えば、LocalDate は LocalDateComponentSerializer を使用してコンポーネント単位でのシリアル化を行うことができます。 シリアライザーを明示的に選択するには、通常の @Serializable(with = ...) アノテーションを使用してください。 また、Contextual シリアライザーを使用し、この選択肢を実行時まで延期することもできます。

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}}
}

シリアライザーを持たない型もあります。DayOfWeek と Month は kotlinx.serialization によって通常の列挙型としてサポートされます。

kotlinx.serialization が kotlinx-datetime のオプションの依存関係であることは覚えておいてください。 シリアル化機能を使用するには、kotlinx-datetime に加えて kotlinx-serialization-core をプロジェクトの依存関係に追加する必要があります。

DateTimePeriod コンポーネントの正規化

DateTimePeriod は、ある 2 つの時点の間の時間をさまざまな時間単位 (年、月、日、時間、分、秒、ナノ秒) を組み合わせて表現します。 これらの時間単位は、それぞれのクラスにコンストラクターのパラメーターから値を受け取るための対応するプロパティを持っています。例えば、DateTimePeriod(months = 14, minutes = 90) があります。

従来、これらのコンポーネントは独立しており、コンストラクターに渡された値を保持しているだけでした。 しかし、これは異なるコンポーネント値を持ちながら同じ ISO 表現を持つ 2 つのオブジェクトが発生する原因となっていました。 そのような値をシリアル化してから逆シリアル化すると、元の値とは異なる値になる可能性がありました。

このバージョンでは DateTimePeriod の内部表現を変更し、そのコンストラクターにコンポーネントの正規化手順を追加しました。 これにより、コンポーネントが内部的にナノ秒、日、および月の組み合わせに正規化されました。その結果、最初の問題が解決され、コンポーネントプロパティの getter が返す値が大きい場合でも読みやすくなりました。

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

UTC オフセットを含む文字列を Instant としてパース

Instant クラスは、ある時点の時間を表します。 このライブラリを使用すると、ISO 8601 標準に準拠する日時表現を含む文字列をパースすることができます。

0.2.0 より前は、2021-01-02T03:02:01Z のように Z タイムゾーン指定子を最後に含む形式のみを受け付けていました。この場合、時間は UTC+0 のオフセットで指定されていました。 今後はゼロ以外の UTC オフセットもサポートされます。

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

ぜひお試しください！

kotlinx-datetime 0.2.0 は Maven Central から入手できます。 以下の手順に従い、ご自身のプロジェクトでお試しください。

• Maven Central がリポジトリに設定されていることを確認します。

repositories {
    mavenCentral()
}

• kotlinx-datetime を依存関係として追加します (マルチプラットフォームプロジェクトで作業している場合はソースセットの指定もお忘れなく)。

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

ライブラリの使用方法に関する詳細な説明は、README を参照してください。

ご意見をお寄せください

このライブラリは実験的なものであるため、今後も API が変更される可能性があります。 現在、私たちは安定版のリリースを目指しており、皆様からのフィードバックを参考にしたいと思っています。

kotlinx-datetime 0.2.0 をお試しのうえ、ご感想をお寄せください！ また、問題が発生した場合はこのプロジェクトの課題トラッカーにご報告ください。ご質問は JetBrains の Slack でお問い合わせください (こちらで招待を受けることができます)。

Subscribe to Kotlin Blog updates

Subscribe form

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

このフォームを送信することにより、私は JetBrains s.r.o.（以下「JetBrains」）が私宛のニュースレターの送信や営利目的の連絡などで私の名前、メールアドレス、および位置情報データを使用し、この目的のために私の個人データを処理することに同意します。私は、JetBrains がこの目的のために JetBrains プライバシーポリシーに従ってサードパーティのサービスを使用して当該データを処理する場合があることを承諾します。私は私のプロファイルでいつでも同意を取り消すことができることを理解しています。また、各メールには配信停止リンクが含まれています。

Submit

ありがとうございます。受け付けました！