kotlinx-datetime/kotlinx.datetime/format

format

fun Instant.format(format: DateTimeFormat<DateTimeComponents>, offset: UtcOffset = UtcOffset.ZERO): String(source)

Formats this value using the given format using the given offset.

Equivalent to calling DateTimeFormat.format on format and using DateTimeComponents.setDateTimeOffset in the lambda.

DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET is a format very similar to the one used by toString. The only difference is that Instant.toString adds trailing zeros to the fraction-of-second component so that the number of digits after a dot is a multiple of three.

Samples

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
import kotlin.time.Duration.Companion.hours

fun main() { 
   //sampleStart 
   // Formatting an Instant to a string using predefined and custom formats
val epochStart = Instant.fromEpochSeconds(0)
check(epochStart.toString() == "1970-01-01T00:00:00Z")
check(epochStart.format(DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET) == "1970-01-01T00:00:00Z")
val customFormat = DateTimeComponents.Format {
    date(LocalDate.Formats.ISO_BASIC)
    hour(); minute(); second(); char('.'); secondFraction(3)
    offset(UtcOffset.Formats.FOUR_DIGITS)
}
check(epochStart.format(customFormat, UtcOffset(hours = 3, minutes = 30)) == "19700101033000.000+0330") 
   //sampleEnd
}

fun LocalDate.format(format: DateTimeFormat<LocalDate>): String(source)

Formats this value using the given format. Equivalent to calling DateTimeFormat.format on format with this.

Samples

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

fun main() { 
   //sampleStart 
   // Formatting a LocalDate value using predefined and custom formats
check(LocalDate(2024, 4, 16).toString() == "2024-04-16")
check(LocalDate(2024, 4, 16).format(LocalDate.Formats.ISO) == "2024-04-16")
val customFormat = LocalDate.Format {
    monthName(MonthNames.ENGLISH_ABBREVIATED); char(' '); dayOfMonth(); chars(", "); year()
}
check(LocalDate(2024, 4, 16).format(customFormat) == "Apr 16, 2024") 
   //sampleEnd
}

fun LocalDateTime.format(format: DateTimeFormat<LocalDateTime>): String(source)

Formats this value using the given format. Equivalent to calling DateTimeFormat.format on format with this.

See LocalDateTime.Formats and LocalDateTime.Format for predefined and custom formats.

Samples

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

fun main() { 
   //sampleStart 
   // Formatting LocalDateTime values using predefined and custom formats
check(LocalDate(2024, 2, 15).atTime(16, 48).toString() == "2024-02-15T16:48")
check(LocalDate(2024, 2, 15).atTime(16, 48).format(LocalDateTime.Formats.ISO) == "2024-02-15T16:48:00")
val customFormat = LocalDateTime.Format {
    date(LocalDate.Formats.ISO)
    char(' ')
    hour(); char(':'); minute()
    optional {
        char(':'); second()
        optional {
            char('.'); secondFraction(minLength = 3)
        }
    }
}
val dateTime1 = LocalDate(2024, 2, 15).atTime(8, 30)
check(dateTime1.format(customFormat) == "2024-02-15 08:30")
val dateTime2 = LocalDate(2023, 12, 31).atTime(8, 30, 0, 120_000_000)
check(dateTime2.format(customFormat) == "2023-12-31 08:30:00.120") 
   //sampleEnd
}

fun LocalTime.format(format: DateTimeFormat<LocalTime>): String(source)

Formats this value using the given format. Equivalent to calling DateTimeFormat.format on format with this.

Samples

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

fun main() { 
   //sampleStart 
   // Formatting LocalTime values using predefined and custom formats
check(LocalTime(hour = 8, minute = 30).toString() == "08:30")
check(LocalTime(hour = 8, minute = 30).format(LocalTime.Formats.ISO) == "08:30:00")
val customFormat = LocalTime.Format {
    hour(); char(':'); minute()
    optional {
        char(':'); second()
        optional {
            char('.'); secondFraction(minLength = 3)
        }
    }
}
val timeWithZeroSeconds = LocalTime(hour = 8, minute = 30)
check(timeWithZeroSeconds.format(customFormat) == "08:30")
val timeWithNonZeroSecondFraction = LocalTime(hour = 8, minute = 30, second = 0, nanosecond = 120000000)
check(timeWithNonZeroSecondFraction.format(customFormat) == "08:30:00.120") 
   //sampleEnd
}

fun UtcOffset.format(format: DateTimeFormat<UtcOffset>): String(source)

Formats this value using the given format. Equivalent to calling DateTimeFormat.format on format with this.

Samples

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

fun main() { 
   //sampleStart 
   // Formatting a UtcOffset to a string using predefined and custom formats
check(UtcOffset(hours = 1, minutes = 30).format(UtcOffset.Formats.FOUR_DIGITS) == "+0130")
val customFormat = UtcOffset.Format { offsetHours(Padding.NONE); offsetMinutesOfHour() }
check(UtcOffset(hours = 1, minutes = 30).format(customFormat) == "+130") 
   //sampleEnd
}