Returns an instant that corresponds to the start of this date in the specified timeZone.

Note that it's not equivalent to atTime(0, 0).toInstant(timeZone) because a day does not always start at the fixed time 00:00:00. For example, if due do daylight saving time, clocks were shifted from 23:30 of one day directly to 00:30 of the next day, skipping the midnight, then atStartOfDayIn would return the Instant corresponding to 00:30, whereas atTime(0, 0).toInstant(timeZone) would return the Instant corresponding to 01:00.


import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*
fun main() { 
   // Finding the start of a given day in specific time zones
val zone = TimeZone.of("America/Cuiaba")
// The normal case where `atStartOfDayIn` returns the instant of 00:00:00 in the given time zone.
val normalDate = LocalDate(2023, 6, 2)
val startOfDay = normalDate.atStartOfDayIn(zone)
check(startOfDay.toLocalDateTime(zone) == normalDate.atTime(hour = 0, minute = 0))
// The edge case where 00:00:00 does not exist in this time zone on this date due to clocks moving forward.
val dateWithoutMidnight = LocalDate(1985, 11, 2)
val startOfDayWithoutMidnight = dateWithoutMidnight.atStartOfDayIn(zone)
check(startOfDayWithoutMidnight.toLocalDateTime(zone) == dateWithoutMidnight.atTime(hour = 1, minute = 0))