Skip to content

Commit

Permalink
Add samples for format builders
Browse files Browse the repository at this point in the history
  • Loading branch information
dkhalanskyjb committed Apr 15, 2024
1 parent 283afa3 commit 7e8f55e
Show file tree
Hide file tree
Showing 5 changed files with 193 additions and 16 deletions.
39 changes: 23 additions & 16 deletions core/common/src/format/DateTimeFormatBuilder.kt
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,8 @@ public sealed interface DateTimeFormatBuilder {
* The hour of the day, from 0 to 23.
*
* By default, it's zero-padded to two digits, but this can be changed with [padding].
*
* @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.hhmmss
*/
public fun hour(padding: Padding = Padding.ZERO)

Expand All @@ -122,6 +124,7 @@ public sealed interface DateTimeFormatBuilder {
* By default, it's zero-padded to two digits, but this can be changed with [padding].
*
* @see [amPmMarker]
* @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.amPm
*/
public fun amPmHour(padding: Padding = Padding.ZERO)

Expand All @@ -131,13 +134,16 @@ public sealed interface DateTimeFormatBuilder {
* [am] is used for the AM marker (0-11 hours), [pm] is used for the PM marker (12-23 hours).
*
* @see [amPmHour]
* @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.amPm
*/
public fun amPmMarker(am: String, pm: String)

/**
* The minute of hour.
*
* By default, it's zero-padded to two digits, but this can be changed with [padding].
*
* @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.hhmmss
*/
public fun minute(padding: Padding = Padding.ZERO)

Expand All @@ -147,6 +153,8 @@ public sealed interface DateTimeFormatBuilder {
* By default, it's zero-padded to two digits, but this can be changed with [padding].
*
* This field has the default value of 0. If you want to omit it, use [optional].
*
* @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.hhmmss
*/
public fun second(padding: Padding = Padding.ZERO)

Expand All @@ -166,6 +174,8 @@ public sealed interface DateTimeFormatBuilder {
* part.
*
* @throws IllegalArgumentException if [minLength] is greater than [maxLength] or if either is not in the range 1..9.
*
* @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.hhmmss
*/
public fun secondFraction(minLength: Int = 1, maxLength: Int = 9)

Expand All @@ -186,6 +196,7 @@ public sealed interface DateTimeFormatBuilder {
* @throws IllegalArgumentException if [fixedLength] is not in the range 1..9.
*
* @see secondFraction that accepts two parameters.
* @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.fixedLengthSecondFraction
*/
public fun secondFraction(fixedLength: Int) {
secondFraction(fixedLength, fixedLength)
Expand All @@ -194,10 +205,7 @@ public sealed interface DateTimeFormatBuilder {
/**
* An existing [DateTimeFormat] for the time part.
*
* Example:
* ```
* time(LocalTime.Formats.ISO)
* ```
* @sample kotlinx.datetime.test.samples.format.LocalTimeFormatSamples.time
*/
public fun time(format: DateTimeFormat<LocalTime>)
}
Expand All @@ -209,10 +217,7 @@ public sealed interface DateTimeFormatBuilder {
/**
* An existing [DateTimeFormat] for the date-time part.
*
* Example:
* ```
* dateTime(LocalDateTime.Formats.ISO)
* ```
* @sample kotlinx.datetime.test.samples.format.LocalDateTimeFormatSamples.dateTime
*/
public fun dateTime(format: DateTimeFormat<LocalDateTime>)
}
Expand All @@ -227,6 +232,8 @@ public sealed interface DateTimeFormatBuilder {
* By default, it's zero-padded to two digits, but this can be changed with [padding].
*
* This field has the default value of 0. If you want to omit it, use [optional].
*
* @sample kotlinx.datetime.test.samples.format.UtcOffsetFormatSamples.isoOrGmt
*/
public fun offsetHours(padding: Padding = Padding.ZERO)

Expand All @@ -236,6 +243,8 @@ public sealed interface DateTimeFormatBuilder {
* By default, it's zero-padded to two digits, but this can be changed with [padding].
*
* This field has the default value of 0. If you want to omit it, use [optional].
*
* @sample kotlinx.datetime.test.samples.format.UtcOffsetFormatSamples.isoOrGmt
*/
public fun offsetMinutesOfHour(padding: Padding = Padding.ZERO)

Expand All @@ -245,16 +254,15 @@ public sealed interface DateTimeFormatBuilder {
* By default, it's zero-padded to two digits, but this can be changed with [padding].
*
* This field has the default value of 0. If you want to omit it, use [optional].
*
* @sample kotlinx.datetime.test.samples.format.UtcOffsetFormatSamples.isoOrGmt
*/
public fun offsetSecondsOfMinute(padding: Padding = Padding.ZERO)

/**
* An existing [DateTimeFormat] for the UTC offset part.
*
* Example:
* ```
* offset(UtcOffset.Formats.FOUR_DIGITS)
* ```
* @sample kotlinx.datetime.test.samples.format.UtcOffsetFormatSamples.offset
*/
public fun offset(format: DateTimeFormat<UtcOffset>)
}
Expand All @@ -269,16 +277,15 @@ public sealed interface DateTimeFormatBuilder {
*
* When formatting, the timezone identifier is supplied as is, without any validation.
* On parsing, [TimeZone.availableZoneIds] is used to validate the identifier.
*
* @sample kotlinx.datetime.test.samples.format.DateTimeComponentsFormatSamples.timeZoneId
*/
public fun timeZoneId()

/**
* An existing [DateTimeFormat].
*
* Example:
* ```
* dateTimeComponents(DateTimeComponents.Formats.RFC_1123)
* ```
* @sample kotlinx.datetime.test.samples.format.DateTimeComponentsFormatSamples.dateTimeComponents
*/
public fun dateTimeComponents(format: DateTimeFormat<DateTimeComponents>)
}
Expand Down
46 changes: 46 additions & 0 deletions core/common/test/samples/format/DateTimeComponentsFormatSamples.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
/*
* Copyright 2019-2024 JetBrains s.r.o. and contributors.
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
*/

package kotlinx.datetime.test.samples.format

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*

class DateTimeComponentsFormatSamples {
@Test
fun timeZoneId() {
val format = DateTimeComponents.Format {
dateTime(LocalDateTime.Formats.ISO)
char('[')
timeZoneId()
char(']')
}
val formatted = format.format {
setDateTime(LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000))
timeZoneId = "Europe/Paris"
}
check(formatted == "2021-01-13T09:34:58.12[Europe/Paris]")
val parsed = format.parse("2021-01-13T09:34:58.12[Europe/Paris]")
check(parsed.toLocalDateTime() == LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000))
check(parsed.timeZoneId == "Europe/Paris")
}

@Test
fun dateTimeComponents() {
val format = DateTimeComponents.Format {
char('{')
dateTimeComponents(DateTimeComponents.Formats.RFC_1123)
char('}')
}
val formatted = format.format {
setDateTimeOffset(
LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000),
UtcOffset(hours = 3, minutes = 30)
)
}
check(formatted == "{Wed, 13 Jan 2021 09:34:58 +0330}")
}
}
27 changes: 27 additions & 0 deletions core/common/test/samples/format/LocalDateTimeFormatSamples.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
/*
* Copyright 2019-2024 JetBrains s.r.o. and contributors.
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
*/

package kotlinx.datetime.test.samples.format

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*

class LocalDateTimeFormatSamples {
@Test
fun dateTime() {
val format = DateTimeComponents.Format {
dateTime(LocalDateTime.Formats.ISO)
offset(UtcOffset.Formats.FOUR_DIGITS)
}
val formatted = format.format {
setDateTimeOffset(
LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000),
UtcOffset(hours = 2)
)
}
check(formatted == "2021-01-13T09:34:58.12+0200")
}
}
54 changes: 54 additions & 0 deletions core/common/test/samples/format/LocalTimeFormatSamples.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
/*
* Copyright 2019-2024 JetBrains s.r.o. and contributors.
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
*/

package kotlinx.datetime.test.samples.format

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*

class LocalTimeFormatSamples {
@Test
fun hhmmss() {
// format the local time as a single number
val format = LocalTime.Format {
hour(); minute(); second()
optional { char('.'); secondFraction(1, 9) }
}
val formatted = format.format(LocalTime(9, 34, 58, 120_000_000))
check(formatted == "093458.12")
}

@Test
fun amPm() {
val format = LocalTime.Format {
amPmHour(); char(':'); minute(); char(':'); second()
char(' '); amPmMarker("AM", "PM")
}
val formatted = format.format(LocalTime(9, 34, 58, 120_000_000))
check(formatted == "09:34:58 AM")
}

@Test
fun fixedLengthSecondFraction() {
val format = LocalTime.Format {
hour(); char(':'); minute(); char(':'); second()
char('.'); secondFraction(fixedLength = 3)
}
val formatted = format.format(LocalTime(9, 34, 58, 120_000_000))
check(formatted == "09:34:58.120")
}

@Test
fun time() {
val format = LocalDateTime.Format {
date(LocalDate.Formats.ISO)
char(' ')
time(LocalTime.Formats.ISO)
}
val formatted = format.format(LocalDateTime(2021, 1, 13, 9, 34, 58, 120_000_000))
check(formatted == "2021-01-13 09:34:58.12")
}
}
43 changes: 43 additions & 0 deletions core/common/test/samples/format/UtcOffsetFormatSamples.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
/*
* Copyright 2019-2024 JetBrains s.r.o. and contributors.
* Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
*/

package kotlinx.datetime.test.samples.format

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*

class UtcOffsetFormatSamples {
@Test
fun isoOrGmt() {
val format = UtcOffset.Format {
// if the offset is zero, `GMT` is printed
optional("GMT") {
offsetHours(); char(':'); offsetMinutesOfHour()
// if seconds are zero, they are omitted
optional { char(':'); offsetSecondsOfMinute() }
}
}
check(format.format(UtcOffset.ZERO) == "GMT")
check(format.format(UtcOffset(hours = -2)) == "-02:00")
check(format.format(UtcOffset(hours = -2, minutes = -30)) == "-02:30")
check(format.format(UtcOffset(hours = -2, minutes = -30, seconds = -59)) == "-02:30:59")
}

@Test
fun offset() {
val format = DateTimeComponents.Format {
dateTime(LocalDateTime.Formats.ISO)
offset(UtcOffset.Formats.FOUR_DIGITS)
}
val formatted = format.format {
setDateTimeOffset(
LocalDate(2021, 1, 13).atTime(9, 34, 58, 120_000_000),
UtcOffset(hours = 2)
)
}
check(formatted == "2021-01-13T09:34:58.12+0200")
}
}

0 comments on commit 7e8f55e

Please sign in to comment.