Skip to content

Commit

Permalink
Provide custom serializers based on DateTimeFormat
Browse files Browse the repository at this point in the history
The names of the serializers are still under discussion, but
it's already decided that the serializers are going to be abstract
classes.

Fixes #350
  • Loading branch information
dkhalanskyjb committed Jul 24, 2024
1 parent 29276fe commit 314121a
Show file tree
Hide file tree
Showing 10 changed files with 225 additions and 3 deletions.
38 changes: 38 additions & 0 deletions core/common/src/serializers/InstantSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@
package kotlinx.datetime.serializers

import kotlinx.datetime.Instant
import kotlinx.datetime.format
import kotlinx.datetime.format.DateTimeComponents
import kotlinx.datetime.format.DateTimeFormat
import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
Expand Down Expand Up @@ -75,3 +78,38 @@ public object InstantComponentSerializer : KSerializer<Instant> {
}

}

/**
* An abstract serializer for [Instant] values that uses
* a custom [DateTimeFormat] for serializing to and deserializing.
*
* [format] should be a format that includes enough components to unambiguously define a date, a time, and a UTC offset.
* See [Instant.parse] for details of how deserialization is performed.
*
* When serializing, the [Instant] value is formatted as a string using the specified [format]
* in the [ZERO][UtcOffset.ZERO] UTC offset.
*
* This serializer is abstract and must be subclassed to provide a concrete serializer.
* Example:
* ```
* object Rfc1123InstantSerializer : CustomInstantSerializer(DateTimeComponents.Formats.RFC_1123)
* ```
*
* Note that [Instant] is [kotlinx.serialization.Serializable] by default,
* so it is not necessary to create custom serializers when the format is not important.
* Additionally, [InstantIso8601Serializer] is provided for the ISO 8601 format.
*/
public abstract class CustomInstantSerializer(
private val format: DateTimeFormat<DateTimeComponents>,
) : KSerializer<Instant> {

override val descriptor: SerialDescriptor =
PrimitiveSerialDescriptor("kotlinx.datetime.Instant", PrimitiveKind.STRING)

override fun deserialize(decoder: Decoder): Instant =
Instant.parse(decoder.decodeString(), format)

override fun serialize(encoder: Encoder, value: Instant) {
encoder.encodeString(value.format(format))
}
}
31 changes: 31 additions & 0 deletions core/common/src/serializers/LocalDateSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
package kotlinx.datetime.serializers

import kotlinx.datetime.LocalDate
import kotlinx.datetime.format.DateTimeFormat
import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
Expand Down Expand Up @@ -76,3 +77,33 @@ public object LocalDateComponentSerializer: KSerializer<LocalDate> {
}

}

/**
* An abstract serializer for [LocalDate] values that uses
* a custom [DateTimeFormat] to serialize and deserialize the value.
*
* This serializer is abstract and must be subclassed to provide a concrete serializer.
* Example:
* ```
* object IsoBasicLocalDateSerializer : CustomLocalDateSerializer(LocalDate.Formats.ISO_BASIC)
* ```
*
* Note that [LocalDate] is [kotlinx.serialization.Serializable] by default,
* so it is not necessary to create custom serializers when the format is not important.
* Additionally, [LocalDateIso8601Serializer] is provided for the ISO 8601 format.
*/
public abstract class CustomLocalDateSerializer(
format: DateTimeFormat<LocalDate>,
) : KSerializer<LocalDate> by format.asKSerializer("kotlinx.datetime.LocalDate")

internal fun <T> DateTimeFormat<T>.asKSerializer(classFqn: String): KSerializer<T> =
object : KSerializer<T> {
override val descriptor: SerialDescriptor =
PrimitiveSerialDescriptor(classFqn, PrimitiveKind.STRING)

override fun deserialize(decoder: Decoder): T = parse(decoder.decodeString())

override fun serialize(encoder: Encoder, value: T) {
encoder.encodeString(format(value))
}
}
23 changes: 23 additions & 0 deletions core/common/src/serializers/LocalDateTimeSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
package kotlinx.datetime.serializers

import kotlinx.datetime.*
import kotlinx.datetime.format.DateTimeFormat
import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
Expand Down Expand Up @@ -98,3 +99,25 @@ public object LocalDateTimeComponentSerializer: KSerializer<LocalDateTime> {
}

}

/**
* An abstract serializer for [LocalDateTime] values that uses
* a custom [DateTimeFormat] to serialize and deserialize the value.
*
* This serializer is abstract and must be subclassed to provide a concrete serializer.
* Example:
* ```
* object PythonDateTimeSerializer : CustomLocalDateTimeSerializer(LocalDateTime.Format {
* date(LocalDate.Formats.ISO)
* char(' ')
* time(LocalTime.Formats.ISO)
* })
* ```
*
* Note that [LocalDateTime] is [kotlinx.serialization.Serializable] by default,
* so it is not necessary to create custom serializers when the format is not important.
* Additionally, [LocalDateTimeIso8601Serializer] is provided for the ISO 8601 format.
*/
public abstract class CustomLocalDateTimeSerializer(
format: DateTimeFormat<LocalDateTime>,
) : KSerializer<LocalDateTime> by format.asKSerializer("kotlinx.datetime.LocalDateTime")
21 changes: 21 additions & 0 deletions core/common/src/serializers/LocalTimeSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
package kotlinx.datetime.serializers

import kotlinx.datetime.*
import kotlinx.datetime.format.DateTimeFormat
import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
Expand Down Expand Up @@ -81,3 +82,23 @@ public object LocalTimeComponentSerializer : KSerializer<LocalTime> {
}
}
}

/**
* An abstract serializer for [LocalTime] values that uses
* a custom [DateTimeFormat] to serialize and deserialize the value.
*
* This serializer is abstract and must be subclassed to provide a concrete serializer.
* Example:
* ```
* object FixedWidthTimeSerializer : CustomLocalTimeSerializer(LocalTime.Format {
* hour(); char(':'); minute(); char(':'); second(); char('.'); secondFraction(3)
* })
* ```
*
* Note that [LocalTime] is [kotlinx.serialization.Serializable] by default,
* so it is not necessary to create custom serializers when the format is not important.
* Additionally, [LocalTimeIso8601Serializer] is provided for the ISO 8601 format.
*/
public abstract class CustomLocalTimeSerializer(
format: DateTimeFormat<LocalTime>,
) : KSerializer<LocalTime> by format.asKSerializer("kotlinx.datetime.LocalTime")
23 changes: 20 additions & 3 deletions core/common/src/serializers/TimeZoneSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,8 @@

package kotlinx.datetime.serializers

import kotlinx.datetime.FixedOffsetTimeZone
import kotlinx.datetime.TimeZone
import kotlinx.datetime.UtcOffset
import kotlinx.datetime.*
import kotlinx.datetime.format.DateTimeFormat
import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
Expand Down Expand Up @@ -74,3 +73,21 @@ public object UtcOffsetSerializer: KSerializer<UtcOffset> {
}

}

/**
* An abstract serializer for [UtcOffset] values that uses
* a custom [DateTimeFormat] to serialize and deserialize the value.
*
* This serializer is abstract and must be subclassed to provide a concrete serializer.
* Example:
* ```
* object FourDigitOffsetSerializer : CustomUtcOffsetSerializer(UtcOffset.Formats.FOUR_DIGITS)
* ```
*
* Note that [UtcOffset] is [kotlinx.serialization.Serializable] by default,
* so it is not necessary to create custom serializers when the format is not important.
* Additionally, [UtcOffsetSerializer] is provided for the ISO 8601 format.
*/
public abstract class CustomUtcOffsetSerializer(
format: DateTimeFormat<UtcOffset>,
) : KSerializer<UtcOffset> by format.asKSerializer("kotlinx.datetime.UtcOffset")
22 changes: 22 additions & 0 deletions serialization/common/test/InstantSerializationTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
package kotlinx.datetime.serialization.test

import kotlinx.datetime.*
import kotlinx.datetime.format.DateTimeComponents
import kotlinx.datetime.serializers.*
import kotlinx.serialization.*
import kotlinx.serialization.json.*
Expand Down Expand Up @@ -66,4 +67,25 @@ class InstantSerializationTest {
// should be the same as the ISO 8601
iso8601Serialization(Json.serializersModule.serializer())
}

object Rfc1123InstantSerializer : CustomInstantSerializer(DateTimeComponents.Formats.RFC_1123)

@Test
fun testCustomSerializer() {
for ((instant, json) in listOf(
Pair(Instant.fromEpochSeconds(1607505416),
"\"Wed, 9 Dec 2020 09:16:56 GMT\""),
Pair(Instant.fromEpochSeconds(-1607505416),
"\"Thu, 23 Jan 1919 14:43:04 GMT\""),
Pair(Instant.fromEpochSeconds(987654321),
"\"Thu, 19 Apr 2001 04:25:21 GMT\""),
)) {
assertEquals(json, Json.encodeToString(Rfc1123InstantSerializer, instant))
assertEquals(instant, Json.decodeFromString(Rfc1123InstantSerializer, json))
}
assertEquals("\"Thu, 19 Apr 2001 04:25:21 GMT\"",
Json.encodeToString(Rfc1123InstantSerializer, Instant.fromEpochSeconds(987654321, 123456789)))
assertEquals(Instant.fromEpochSeconds(987654321),
Json.decodeFromString(Rfc1123InstantSerializer, "\"Thu, 19 Apr 2001 08:25:21 +0400\""))
}
}
13 changes: 13 additions & 0 deletions serialization/common/test/LocalDateSerializationTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -70,4 +70,17 @@ class LocalDateSerializationTest {
iso8601Serialization(Json.serializersModule.serializer())
}

object IsoBasicLocalDateSerializer : CustomLocalDateSerializer(LocalDate.Formats.ISO_BASIC)

@Test
fun testCustomSerializer() {
for ((localDate, json) in listOf(
Pair(LocalDate(2020, 12, 9), "\"20201209\""),
Pair(LocalDate(-2020, 1, 1), "\"-20200101\""),
Pair(LocalDate(2019, 10, 1), "\"20191001\""),
)) {
assertEquals(json, Json.encodeToString(IsoBasicLocalDateSerializer, localDate))
assertEquals(localDate, Json.decodeFromString(IsoBasicLocalDateSerializer, json))
}
}
}
21 changes: 21 additions & 0 deletions serialization/common/test/LocalDateTimeSerializationTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
package kotlinx.datetime.serialization.test

import kotlinx.datetime.*
import kotlinx.datetime.format.char
import kotlinx.datetime.serializers.*
import kotlinx.serialization.KSerializer
import kotlinx.serialization.json.*
Expand Down Expand Up @@ -82,4 +83,24 @@ class LocalDateTimeSerializationTest {
// should be the same as the ISO 8601
iso8601Serialization(Json.serializersModule.serializer())
}

object PythonDateTimeSerializer : CustomLocalDateTimeSerializer(LocalDateTime.Format {
date(LocalDate.Formats.ISO)
char(' ')
time(LocalTime.Formats.ISO)
})

@Test
fun testCustomSerializer() {
for ((localDateTime, json) in listOf(
Pair(LocalDateTime(2008, 7, 5, 2, 1), "\"2008-07-05 02:01:00\""),
Pair(LocalDateTime(2007, 12, 31, 23, 59, 1), "\"2007-12-31 23:59:01\""),
Pair(LocalDateTime(999, 12, 31, 23, 59, 59, 990000000), "\"0999-12-31 23:59:59.99\""),
Pair(LocalDateTime(-1, 1, 2, 23, 59, 59, 999990000), "\"-0001-01-02 23:59:59.99999\""),
Pair(LocalDateTime(-2008, 1, 2, 23, 59, 59, 999999990), "\"-2008-01-02 23:59:59.99999999\""),
)) {
assertEquals(json, Json.encodeToString(PythonDateTimeSerializer, localDateTime))
assertEquals(localDateTime, Json.decodeFromString(PythonDateTimeSerializer, json))
}
}
}
20 changes: 20 additions & 0 deletions serialization/common/test/LocalTimeSerializationTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
package kotlinx.datetime.serialization.test

import kotlinx.datetime.*
import kotlinx.datetime.format.char
import kotlinx.datetime.serializers.*
import kotlinx.serialization.KSerializer
import kotlinx.serialization.json.*
Expand Down Expand Up @@ -72,4 +73,23 @@ class LocalTimeSerializationTest {
// should be the same as the ISO 8601
iso8601Serialization(Json.serializersModule.serializer())
}

object FixedWidthTimeSerializer : CustomLocalTimeSerializer(LocalTime.Format {
hour(); char(':'); minute(); char(':'); second(); char('.'); secondFraction(3)
})

@Test
fun testCustomSerializer() {
for ((localTime, json) in listOf(
Pair(LocalTime(2, 1), "\"02:01:00.000\""),
Pair(LocalTime(23, 59, 1), "\"23:59:01.000\""),
Pair(LocalTime(23, 59, 59, 990000000), "\"23:59:59.990\""),
Pair(LocalTime(23, 59, 59, 999000000), "\"23:59:59.999\""),
)) {
assertEquals(json, Json.encodeToString(FixedWidthTimeSerializer, localTime))
assertEquals(localTime, Json.decodeFromString(FixedWidthTimeSerializer, json))
}
assertEquals("\"12:34:56.123\"", Json.encodeToString(FixedWidthTimeSerializer,
LocalTime(12, 34, 56, 123999999)))
}
}
16 changes: 16 additions & 0 deletions serialization/common/test/UtcOffsetSerializationTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -35,4 +35,20 @@ class UtcOffsetSerializationTest {
testSerializationAsPrimitive(UtcOffsetSerializer)
testSerializationAsPrimitive(UtcOffset.serializer())
}

object FourDigitOffsetSerializer : CustomUtcOffsetSerializer(UtcOffset.Formats.FOUR_DIGITS)

@Test
fun testCustomSerializer() {
for ((utcOffset, json) in listOf(
Pair(UtcOffset.ZERO, "\"+0000\""),
Pair(UtcOffset(2), "\"+0200\""),
Pair(UtcOffset(2, 30), "\"+0230\""),
Pair(UtcOffset(-2, -30), "\"-0230\""),
)) {
assertEquals(json, Json.encodeToString(FourDigitOffsetSerializer, utcOffset))
assertEquals(utcOffset, Json.decodeFromString(FourDigitOffsetSerializer, json))
}
assertEquals("\"+1234\"", Json.encodeToString(FourDigitOffsetSerializer, UtcOffset(12, 34, 56)))
}
}

0 comments on commit 314121a

Please sign in to comment.