Added LocalTime.Formats.ISO_BASIC (ISO 8601 basic format) by lucgirardin · Pull Request #518 · Kotlin/kotlinx-datetime

lucgirardin · 2025-04-13T15:16:34Z

No description provided.

dkhalanskyjb · 2025-04-14T07:46:17Z

ISO 8601 specifies that the format for time-of-day includes a leading T. The extended format can omit it, but a basic representation of time-of-day must always include T. Therefore, the format you're proposing is not a valid basic ISO time-of-day, and should not be named ISO_BASIC.

lucgirardin · 2025-04-14T20:26:53Z

You are right, thanks for spotting this! I believe the same should also apply to LocalTime.Formats.ISO. Should I attempt to change it as well?

dkhalanskyjb · 2025-04-15T07:18:29Z

I believe the same should also apply to LocalTime.Formats.ISO.

The extended ISO format is allowed to omit the T, and since the format without the T is vastly more useful, we use that, so no.

In fact, regarding usefulness: is LocalTime.Formats.ISO_BASIC useful at all? When researching how people used date-time formats, I haven't seen anyone defining this format on their own.

lucgirardin · 2025-04-15T07:28:18Z

I find it very useful, for example if one need to have a timestamp stored in a file name, in my case weather-20250415T065500Z.parquet.

dkhalanskyjb

Got it! I don't see any problems with adding a LocalTime.Formats.ISO_BASIC if it is indeed useful, but by that logic, it also makes sense to add LocalDateTime.Formats.ISO_BASIC (which is the 20250415T065500 part in your message).

dkhalanskyjb · 2025-04-15T08:51:46Z

 // these are constants so that the formats are not recreated every time they are used
+internal val ISO_TIME_BASIC by lazy {
+    LocalTimeFormat.build {
+        char('T')


Please see internal val ISO_DATETIME: our format is case-insensitive.

dkhalanskyjb · 2025-04-15T08:53:50Z

+         *
+         * @sample kotlinx.datetime.test.samples.LocalTimeSamples.Formats.isoBasic
+         */
+        public val ISO_BASIC: DateTimeFormat<LocalTime>


Please also add tests. Examples: LocalDateTimeFormatTest#testIso, LocalDateFormatTest#testBasicIso, etc.

dkhalanskyjb · 2025-04-15T08:54:21Z

+        /**
+         * ISO 8601 basic format.
+         *
+         * Examples: `1234`, `123456`, `123456.789`, `123456.1234`.


These examples are not valid for this format.

lucgirardin · 2025-05-01T06:27:24Z

Should be complete now!

dkhalanskyjb · 2025-05-02T04:03:01Z

+         * When formatting, seconds are included, only if they are non-zero.
+         * Fractional parts of the second are included if non-zero.
+         *
+         * See ISO-8601-1:2019, 5.4.2.1b), the version without the offset, together with


Suggested change

* See ISO-8601-1:2019, 5.4.2.1b), the version without the offset, together with

* See ISO-8601-1:2019, 5.4.2.1a), the version without the offset, together with

b) is the extended format.

dkhalanskyjb · 2025-05-02T04:04:49Z

+         *
+         * When formatting, seconds are always included, even if they are zero.
+         * Fractional parts of the second are included if non-zero.
+         *


I think LocalDateTime.ISO_BASIC is also worth mentioning (given that you personally were interested in LocalDateTime.Formats.ISO_BASIC, for example).

dkhalanskyjb · 2025-05-02T04:07:48Z

+            optional {
+                second()
+            }
+            optional {
+                char('.')
+                secondFraction(1, 9)
+            }
+        }


Suggested change

optional {

second()

}

optional {

char('.')

secondFraction(1, 9)

}

}

optional {

second()

optional {

char('.')

secondFraction(1, 9)

}

}

}

As the tests show, otherwise, 12:30:00.123 gets formatted as T1230.123, which is not valid: fractions of a second are only emitted together with the second value itself, even if it is zero.

… itself, even if it is zero.

lucgirardin · 2025-05-02T05:48:02Z

Thanks for your careful review!

dkhalanskyjb · 2025-05-19T08:27:38Z

+    @Test
+    fun testBasicIso() {
+        val dateTimes = buildMap<LocalDateTime, Pair<String, Set<String>>> {
+            put(LocalDateTime(2008, 7, 5, 0, 0, 0, 0), ("20080705T0000" to setOf("20080705T0000")))


Here, the same parsable representation is listed twice.

dkhalanskyjb · 2025-05-19T10:37:48Z

+            optional {
+                second()
+                optional {
+                    char('.')
+                    secondFraction(1, 9)
+                }
+            }


Now that I look at it, it's inconsistent to optionally omit seconds here on formatting. ISO allows parsing missing seconds, but does not omit them on its own.

Suggested change

optional {

second()

optional {

char('.')

secondFraction(1, 9)

}

}

second()

optional {

char('.')

secondFraction(1, 9)

}

lucgirardin · 2025-07-14T17:06:15Z

Sorry for the long delay. Everything should now be good to go, hopefully!

dkhalanskyjb · 2025-09-16T12:05:55Z

+         * - `00000830T184300.5`
+         * - `-00010830T184300.123456789`
+         *
+         * When formatting, seconds always included.


Suggested change

* When formatting, seconds always included.

* When formatting, seconds are always included.

dkhalanskyjb · 2025-09-16T12:07:53Z

+         * See ISO-8601-1:2019, 5.4.2.1a), the version without the offset, together with
+         * [LocalDate.Formats.ISO_BASIC] and [LocalTime.Formats.ISO_BASIC].
+         *
+         * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.Formats.basicIso


LocalDateTimeSamples needs to include the actual sample. Also, please use consistent naming: for LocalDate and LocalTime, this sample is called isoBasic.

dkhalanskyjb · 2025-09-16T12:14:37Z

    }

+    @Test
+    fun testBasicIso() {


Please also add the corresponding test for LocalTime.Formats.ISO_BASIC.

dkhalanskyjb · 2025-09-16T12:16:12Z

+    @Test
+    fun testBasicIso() {
+        val dateTimes = buildMap<LocalDateTime, Pair<String, Set<String>>> {
+            put(LocalDateTime(2008, 7, 5, 0, 0, 0, 0), ("20080705T000000" to setOf("20080705t000000")))


Please also test the scenarios of parsing a string which does not include the seconds.

dkhalanskyjb

Another thing that I noticed just now: please also add the new constants to this list:

kotlinx-datetime/core/common/src/format/DateTimeFormat.kt

Lines 154 to 171 in 90be731

    
           private val allFormatConstants: List<Pair<String, CachedFormatStructure<*>>> by lazy { 
        
               fun unwrap(format: DateTimeFormat<*>): CachedFormatStructure<*> = (format as AbstractDateTimeFormat<*, *>).actualFormat 
        
               // the formats are ordered vaguely by decreasing length, as the topmost among suitable ones is chosen. 
        
               listOf( 
        
                   "${DateTimeFormatBuilder.WithDateTimeComponents::dateTimeComponents.name}(DateTimeComponents.Formats.RFC_1123)" to 
        
                       unwrap(DateTimeComponents.Formats.RFC_1123), 
        
                   "${DateTimeFormatBuilder.WithDateTimeComponents::dateTimeComponents.name}(DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET)" to 
        
                       unwrap(DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET), 
        
                   "${DateTimeFormatBuilder.WithDateTime::date.name}(LocalDateTime.Formats.ISO)" to unwrap(LocalDateTime.Formats.ISO), 
        
                   "${DateTimeFormatBuilder.WithDate::date.name}(LocalDate.Formats.ISO)" to unwrap(LocalDate.Formats.ISO), 
        
                   "${DateTimeFormatBuilder.WithDate::date.name}(LocalDate.Formats.ISO_BASIC)" to unwrap(LocalDate.Formats.ISO_BASIC), 
        
                   "${DateTimeFormatBuilder.WithTime::time.name}(LocalTime.Formats.ISO)" to unwrap(LocalTime.Formats.ISO), 
        
                   "${DateTimeFormatBuilder.WithUtcOffset::offset.name}(UtcOffset.Formats.ISO)" to unwrap(UtcOffset.Formats.ISO), 
        
                   "${DateTimeFormatBuilder.WithUtcOffset::offset.name}(UtcOffset.Formats.ISO_BASIC)" to unwrap(UtcOffset.Formats.ISO_BASIC), 
        
                   "${DateTimeFormatBuilder.WithUtcOffset::offset.name}(UtcOffset.Formats.FOUR_DIGITS)" to unwrap(UtcOffset.Formats.FOUR_DIGITS), 
        
                   "${DateTimeFormatBuilder.WithYearMonth::yearMonth.name}(YearMonth.Formats.ISO)" to unwrap(YearMonth.Formats.ISO), 
        
               ) 
        
           }

Added LocalTime.Formats.ISO_BASIC (ISO 8601 basic format)

c8e2757

lucgirardin added 2 commits April 14, 2025 22:21

Corrected LocalTime.Formats.ISO_BASIC with leading 'T'

cca454f

Corrected LocalTime.Formats.ISO_BASIC with leading 'T'

8d17ebb

dkhalanskyjb requested changes Apr 15, 2025

View reviewed changes

lucgirardin added 5 commits April 26, 2025 14:22

Format is case-insensitive

8cddb49

ISO_BASIC starts with T

76a093a

Merge branch 'Kotlin:master' into master

bae2c6e

Added ISO_BASIC to API

8075aa0

Added tests for ISO_BASIC

8177fe6

lucgirardin requested a review from dkhalanskyjb May 1, 2025 06:27

dkhalanskyjb requested changes May 2, 2025

View reviewed changes

lucgirardin added 2 commits May 2, 2025 07:30

a) is the basic format

a403817

Fractions of a second are only emitted together with the second value…

deefb8d

… itself, even if it is zero.

lucgirardin requested a review from dkhalanskyjb May 2, 2025 05:48

dkhalanskyjb requested changes May 19, 2025

View reviewed changes

lucgirardin added 4 commits May 29, 2025 11:57

Merge branch 'Kotlin:master' into master

e2e0455

Parsable representation is listed twice

9b19750

Merge branch 'Kotlin:master' into master

2d57be0

ISO allows parsing missing seconds, but does not omit them on its own.

6847e0e

dkhalanskyjb requested changes Sep 16, 2025

View reviewed changes

dkhalanskyjb requested changes Oct 22, 2025

View reviewed changes

	* See ISO-8601-1:2019, 5.4.2.1b), the version without the offset, together with
	* See ISO-8601-1:2019, 5.4.2.1a), the version without the offset, together with

	* When formatting, seconds always included.
	* When formatting, seconds are always included.

	private val allFormatConstants: List<Pair<String, CachedFormatStructure<*>>> by lazy {
	fun unwrap(format: DateTimeFormat<>): CachedFormatStructure<> = (format as AbstractDateTimeFormat<, >).actualFormat
	// the formats are ordered vaguely by decreasing length, as the topmost among suitable ones is chosen.
	listOf(
	"${DateTimeFormatBuilder.WithDateTimeComponents::dateTimeComponents.name}(DateTimeComponents.Formats.RFC_1123)" to
	unwrap(DateTimeComponents.Formats.RFC_1123),
	"${DateTimeFormatBuilder.WithDateTimeComponents::dateTimeComponents.name}(DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET)" to
	unwrap(DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET),
	"${DateTimeFormatBuilder.WithDateTime::date.name}(LocalDateTime.Formats.ISO)" to unwrap(LocalDateTime.Formats.ISO),
	"${DateTimeFormatBuilder.WithDate::date.name}(LocalDate.Formats.ISO)" to unwrap(LocalDate.Formats.ISO),
	"${DateTimeFormatBuilder.WithDate::date.name}(LocalDate.Formats.ISO_BASIC)" to unwrap(LocalDate.Formats.ISO_BASIC),
	"${DateTimeFormatBuilder.WithTime::time.name}(LocalTime.Formats.ISO)" to unwrap(LocalTime.Formats.ISO),
	"${DateTimeFormatBuilder.WithUtcOffset::offset.name}(UtcOffset.Formats.ISO)" to unwrap(UtcOffset.Formats.ISO),
	"${DateTimeFormatBuilder.WithUtcOffset::offset.name}(UtcOffset.Formats.ISO_BASIC)" to unwrap(UtcOffset.Formats.ISO_BASIC),
	"${DateTimeFormatBuilder.WithUtcOffset::offset.name}(UtcOffset.Formats.FOUR_DIGITS)" to unwrap(UtcOffset.Formats.FOUR_DIGITS),
	"${DateTimeFormatBuilder.WithYearMonth::yearMonth.name}(YearMonth.Formats.ISO)" to unwrap(YearMonth.Formats.ISO),
	)
	}

Uh oh!

Conversation

lucgirardin commented Apr 13, 2025

Uh oh!

dkhalanskyjb commented Apr 14, 2025

Uh oh!

lucgirardin commented Apr 14, 2025

Uh oh!

dkhalanskyjb commented Apr 15, 2025

Uh oh!

lucgirardin commented Apr 15, 2025

Uh oh!

dkhalanskyjb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucgirardin commented May 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucgirardin commented May 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lucgirardin commented Jul 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkhalanskyjb left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants