parse

expect fun parse(input: CharSequence, format: DateTimeFormat<DateTimeComponents> = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET): Instant(source)

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.

If the format is not specified, DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET is used. 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.

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
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
}