The performance of creating new datetime formats can be improved

benchmarks/src/jmh/kotlin/CommonFormats.kt

@@ -0,0 +1,167 @@
+/*
+ * Copyright 2019-2025 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.
+ */
+
+@file:Suppress("unused")
+
+package kotlinx.datetime
+
+import kotlinx.datetime.format.*
+import org.openjdk.jmh.annotations.*
+import org.openjdk.jmh.infra.Blackhole
+import java.util.concurrent.*
+
+@Warmup(iterations = 20, time = 2)
+@Measurement(iterations = 30, time = 2)
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
+@State(Scope.Benchmark)
+@Fork(2)
+open class CommonFormats {
+
+    @Benchmark
+    fun buildPythonDateTimeFormat(blackhole: Blackhole) {
+        val v = LocalDateTime.Format {
+            year()
+            char('-')
+            monthNumber()
+            char('-')
+            day()
+            char(' ')
+            hour()
+            char(':')
+            minute()
+            optional {
+                char(':')
+                second()
+                optional {
+                    char('.')
+                    secondFraction()
+                }
+            }
+        }
+        blackhole.consume(v)
+    }
+
+    @Benchmark
+    fun buildIsoDateTimeFormat(blackhole: Blackhole) {
+        val format = LocalDateTime.Format {
+            date(LocalDate.Format {
+                year()
+                char('-')
+                monthNumber()
+                char('-')
+                day()
+            })
+            alternativeParsing({ char('t') }) { char('T') }
+            time(LocalTime.Format {
+                hour()
+                char(':')
+                minute()
+                alternativeParsing({}) {
+                    char(':')
+                    second()
+                    optional {
+                        char('.')
+                        secondFraction(1, 9)
+                    }
+                }
+            })
+        }
+        blackhole.consume(format)
+    }
+
+    @Benchmark
+    fun buildFourDigitsUtcOffsetFormat(blackhole: Blackhole) {
+        val format = UtcOffset.Format {
+            offsetHours()
+            offsetMinutesOfHour()
+        }
+        blackhole.consume(format)
+    }
+
+    @Benchmark
+    fun buildRfc1123DateTimeFormat(blackhole: Blackhole) {
+        val format = DateTimeComponents.Format {
+            alternativeParsing({
+                // the day of week may be missing
+            }) {
+                dayOfWeek(DayOfWeekNames.ENGLISH_ABBREVIATED)
+                chars(", ")
+            }
+            day(Padding.NONE)
+            char(' ')
+            monthName(MonthNames.ENGLISH_ABBREVIATED)
+            char(' ')
+            year()
+            char(' ')
+            hour()
+            char(':')
+            minute()
+            optional {
+                char(':')
+                second()
+            }
+            chars(" ")
+            alternativeParsing({
+                chars("UT")
+            }, {
+                chars("Z")
+            }) {
+                optional("GMT") {
+                    offset(UtcOffset.Format {
+                        offsetHours()
+                        offsetMinutesOfHour()
+                    })
+                }
+            }
+        }
+        blackhole.consume(format)
+    }
+
+    @Benchmark
+    fun buildIsoDateTimeOffsetFormat(blackhole: Blackhole) {
+        val format = DateTimeComponents.Format {
+            date(LocalDate.Format {
+                year()
+                char('-')
+                monthNumber()
+                char('-')
+                day()
+            })
+            alternativeParsing({
+                char('t')
+            }) {
+                char('T')
+            }
+            hour()
+            char(':')
+            minute()
+            char(':')
+            second()
+            optional {
+                char('.')
+                secondFraction(1, 9)
+            }
+            alternativeParsing({
+                offsetHours()
+            }) {
+                offset(UtcOffset.Format {
+                    alternativeParsing({ chars("z") }) {
+                        optional("Z") {
+                            offsetHours()
+                            char(':')
+                            offsetMinutesOfHour()
+                            optional {
+                                char(':')
+                                offsetSecondsOfMinute()
+                            }
+                        }
+                    }
+                })
+            }
+        }
+        blackhole.consume(format)
+    }
+}

benchmarks/src/jmh/kotlin/ParallelFormatBenchmark.kt

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2019-2025 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.
+ */
+
+@file:Suppress("unused")
+
+package kotlinx.datetime
+
+import kotlinx.datetime.format.alternativeParsing
+import kotlinx.datetime.format.char
+import org.openjdk.jmh.annotations.*
+import org.openjdk.jmh.infra.Blackhole
+import java.util.concurrent.TimeUnit
+
+@Warmup(iterations = 10, time = 2)
+@Measurement(iterations = 20, time = 2)
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
+@State(Scope.Benchmark)
+@Fork(1)
+open class ParallelFormatBenchmark {
+
+    @Param("2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12")
+    var n = 0
+
+    @Benchmark
+    fun formatCreationWithAlternativeParsing(blackhole: Blackhole) {
+        val format = LocalDateTime.Format {
+            repeat(n) {
+                alternativeParsing(
+                    { monthNumber() },
+                    { day() },
+                    primaryFormat = { hour() }
+                )
+                char('@')
+                minute()
+                char('#')
+                second()
+            }
+        }
+        blackhole.consume(format)
+    }
+
+    @Benchmark
+    fun formatCreationWithNestedAlternativeParsing(blackhole: Blackhole) {
+        val format = LocalDateTime.Format {
+            repeat(n) { index ->
+                alternativeParsing(
+                    { monthNumber(); char('-'); day() },
+                    { day(); char('/'); monthNumber() },
+                    primaryFormat = { year(); char('-'); monthNumber(); char('-'); day() }
+                )
+
+                if (index and 1 == 0) {
+                    alternativeParsing(
+                        {
+                            alternativeParsing(
+                                { hour(); char(':'); minute() },
+                                { minute(); char(':'); second() },
+                                primaryFormat = { hour(); char(':'); minute(); char(':'); second() }
+                            )
+                        },
+                        primaryFormat = {
+                            year(); char('-'); monthNumber(); char('-'); day()
+                            char('T')
+                            hour(); char(':'); minute(); char(':'); second()
+                        }
+                    )
+                }
+
+                char('|')
+                if (index % 3 == 0) {
+                    char('|')
+                }
+
+                if (index and 2 == 0) {
+                    alternativeParsing(
+                        { char('Z') },
+                        { char('+'); hour(); char(':'); minute() },
+                        primaryFormat = { char('-'); hour(); char(':'); minute() }
+                    )
+                }
+            }
+        }
+        blackhole.consume(format)
+    }
+}

core/common/src/internal/format/parser/Parser.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 JetBrains s.r.o. and contributors.
+ * Copyright 2023-2025 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.
  */
 
@@ -41,19 +41,40 @@ internal class ParserStructure<in Output>(
         "${operations.joinToString(", ")}(${followedBy.joinToString(";")})"
 }
 
-// TODO: O(size of the resulting parser ^ 2), but can be O(size of the resulting parser)
 internal fun <T> List<ParserStructure<T>>.concat(): ParserStructure<T> {
-    fun <T> ParserStructure<T>.append(other: ParserStructure<T>): ParserStructure<T> = if (followedBy.isEmpty()) {
-        ParserStructure(operations + other.operations, other.followedBy)
-    } else {
-        ParserStructure(operations, followedBy.map { it.append(other) })
+    fun mergeOperations(
+        baseOperations: List<ParserOperation<T>>,
+        numberSpan: List<NumberConsumer<T>>?,
+        unconditionalModifications: List<UnconditionalModification<T>>,
+        simplifiedParserStructure: ParserStructure<T>,
+    ): ParserStructure<T> {
+        val operationsToMerge = simplifiedParserStructure.operations
+        val firstOperation = operationsToMerge.firstOrNull()
+        val mergedOperations = buildList {
+            addAll(baseOperations)
+            when {
+                numberSpan == null -> {
+                    addAll(operationsToMerge)
+                }
+                firstOperation is NumberSpanParserOperation -> {
+                    add(NumberSpanParserOperation(numberSpan + firstOperation.consumers))
+                    addAll(operationsToMerge.drop(1))
+                }
+                else -> {
+                    add(NumberSpanParserOperation(numberSpan))
+                    addAll(operationsToMerge)
+                }
+            }
+            addAll(unconditionalModifications)
+        }
+        return ParserStructure(mergedOperations, simplifiedParserStructure.followedBy)
     }
 
-    fun <T> ParserStructure<T>.simplify(unconditionalModifications: List<UnconditionalModification<T>>): ParserStructure<T> {
+    fun ParserStructure<T>.simplifyAndAppend(other: ParserStructure<T>): ParserStructure<T> {
         val newOperations = mutableListOf<ParserOperation<T>>()
         var currentNumberSpan: MutableList<NumberConsumer<T>>? = null
-        val unconditionalModificationsForTails = unconditionalModifications.toMutableList()
-        // joining together the number consumers in this parser before the first alternative;
+        val unconditionalModifications = mutableListOf<UnconditionalModification<T>>()
+        // joining together the number of consumers in this parser before the first alternative;
         // collecting the unconditional modifications to push them to the end of all the parser's branches.
         for (op in operations) {
             if (op is NumberSpanParserOperation) {
@@ -63,7 +84,7 @@ internal fun <T> List<ParserStructure<T>>.concat(): ParserStructure<T> {
                     currentNumberSpan = op.consumers.toMutableList()
                 }
             } else if (op is UnconditionalModification) {
-                unconditionalModificationsForTails.add(op)
+                unconditionalModifications.add(op)
             } else {
                 if (currentNumberSpan != null) {
                     newOperations.add(NumberSpanParserOperation(currentNumberSpan))
@@ -72,8 +93,9 @@ internal fun <T> List<ParserStructure<T>>.concat(): ParserStructure<T> {
                 newOperations.add(op)
             }
         }
+
         val mergedTails = followedBy.flatMap {
-            val simplified = it.simplify(unconditionalModificationsForTails)
+            val simplified = it.simplifyAndAppend(other)
             // parser `ParserStructure(emptyList(), p)` is equivalent to `p`,
             // unless `p` is empty. For example, ((a|b)|(c|d)) is equivalent to (a|b|c|d).
             // As a special case, `ParserStructure(emptyList(), emptyList())` represents a parser that recognizes an empty
@@ -83,46 +105,30 @@ internal fun <T> List<ParserStructure<T>>.concat(): ParserStructure<T> {
             else
                 listOf(simplified)
         }.ifEmpty {
-            // preserving the invariant that `mergedTails` contains all unconditional modifications
-            listOf(ParserStructure(unconditionalModificationsForTails, emptyList()))
+            if (other.operations.isNotEmpty()) {
+                return mergeOperations(newOperations, currentNumberSpan, unconditionalModifications, other)
+            }
+            other.followedBy
         }
+
         return if (currentNumberSpan == null) {
             // the last operation was not a number span, or it was a number span that we are allowed to interrupt
+            newOperations.addAll(unconditionalModifications)
             ParserStructure(newOperations, mergedTails)
-        } else if (mergedTails.none {
-                it.operations.firstOrNull()?.let { it is NumberSpanParserOperation } == true
-            }) {
+        } else if (mergedTails.none { it.operations.firstOrNull() is NumberSpanParserOperation }) {
             // the last operation was a number span, but there are no alternatives that start with a number span.
             newOperations.add(NumberSpanParserOperation(currentNumberSpan))
+            newOperations.addAll(unconditionalModifications)
             ParserStructure(newOperations, mergedTails)
         } else {
             val newTails = mergedTails.map {
-                when (val firstOperation = it.operations.firstOrNull()) {
-                    is NumberSpanParserOperation -> {
-                        ParserStructure(
-                            listOf(NumberSpanParserOperation(currentNumberSpan + firstOperation.consumers)) + it.operations.drop(
-                                1
-                            ),
-                            it.followedBy
-                        )
-                    }
-
-                    null -> ParserStructure(
-                        listOf(NumberSpanParserOperation(currentNumberSpan)),
-                        it.followedBy
-                    )
-
-                    else -> ParserStructure(
-                        listOf(NumberSpanParserOperation(currentNumberSpan)) + it.operations,
-                        it.followedBy
-                    )
-                }
+                mergeOperations(emptyList(), currentNumberSpan, unconditionalModifications, it)
             }
             ParserStructure(newOperations, newTails)
         }
     }
-    val naiveParser = foldRight(ParserStructure<T>(emptyList(), emptyList())) { parser, acc -> parser.append(acc) }
-    return naiveParser.simplify(emptyList())
+
+    return foldRight(ParserStructure(emptyList(), emptyList())) { parser, acc -> parser.simplifyAndAppend(acc) }
 }
 
 internal interface Copyable<Self> {