kotlinx-datetime/kotlinx.datetime/LocalDateTime/Companion/Format

Format

actual fun Format(builder: DateTimeFormatBuilder.WithDateTime.() -> Unit): DateTimeFormat<LocalDateTime>(source)

expect fun Format(builder: DateTimeFormatBuilder.WithDateTime.() -> Unit): DateTimeFormat<LocalDateTime>(source)

Creates a new format for parsing and formatting LocalDateTime values.

Examples:

// `2020-08-30 18:43:13`, using predefined date and time formats
LocalDateTime.Format { date(LocalDate.Formats.ISO); char(' '); time(LocalTime.Formats.ISO) }

// `08/30 18:43:13`, using a custom format:
LocalDateTime.Format {
  monthNumber(); char('/'); dayOfMonth()
  char(' ')
  hour(); char(':'); minute()
  optional { char(':'); second() }
}

Only parsing and formatting of well-formed values is supported. If the input does not fit the boundaries (for example, dayOfMonth is 31 for February), consider using DateTimeComponents.Format instead.

There is a collection of predefined formats in LocalDateTime.Formats.

Throws

IllegalArgumentException

if parsing using this format is ambiguous.

Samples

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*
fun main() { 
   //sampleStart 
   // Parsing and formatting LocalDateTime values using a custom format
val customFormat = LocalDateTime.Format {
    date(LocalDate.Formats.ISO)
    char(' ')
    hour(); char(':'); minute(); char(':'); second()
    char(','); secondFraction(fixedLength = 3)
}
val dateTime = LocalDate(2024, 2, 15)
    .atTime(8, 30, 15, 123_456_789)
check(dateTime.format(customFormat) == "2024-02-15 08:30:15,123")
check(customFormat.parse("2024-02-15 08:30:15,123") ==
    LocalDate(2024, 2, 15).atTime(8, 30, 15, 123_000_000)
)
check(dateTime.format(LocalDateTime.Formats.ISO) == "2024-02-15T08:30:15.123456789") 
   //sampleEnd
}

actual fun Format(builder: DateTimeFormatBuilder.WithDateTime.() -> Unit): DateTimeFormat<LocalDateTime>(source)