parse
A shortcut for calling DateTimeFormat.parse, followed by DateTimeComponents.toInstantUsingOffset.
Parses a string that represents an instant, including date and time components and a mandatory time zone offset and returns the parsed Instant value.
The string is considered to represent time on the UTC-SLS time scale instead of UTC. In practice, this means that, even if there is a leap second on the given day, it will not affect how the time is parsed, even if it's in the last 1000 seconds of the day. Instead, even if there is a negative leap second on the given day, 23:59:59 is still considered a valid time. 23:59:60 is invalid on UTC-SLS, so parsing it will fail.
Instant.parse is equivalent to calling this function with the DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET format. 2023-01-02T23:40:57.120Z is an example of a string in this format.
See also
for formatting using the default format.
for formatting using a custom format.
for parsing an ISO string without involving kotlinx-datetime.
Throws
if the text cannot be parsed or the boundaries of Instant are exceeded.
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
import kotlin.time.Duration.Companion.hours
import kotlin.time.Clock
import kotlin.time.Instant
import kotlin.time.isDistantFuture
import kotlin.time.isDistantPast
fun main() {
//sampleStart
// Parsing an Instant from a string using predefined and custom formats
check(Instant.parse("1970-01-01T00:00:00Z") == Instant.fromEpochSeconds(0))
check(Instant.parse("Thu, 01 Jan 1970 03:30:00 +0330", DateTimeComponents.Formats.RFC_1123) == Instant.fromEpochSeconds(0))
//sampleEnd
}