kotlin-stdlib/kotlin.time/Instant/Companion/parse

parse

fun parse(input: CharSequence): Instant(source)

Parses an ISO 8601 string that represents an instant (for example, 2020-08-30T18:43:00Z).

Guaranteed to parse all strings that Instant.toString produces.

Examples of instants in the ISO 8601 format:

  • 2020-08-30T18:43:00Z

  • 2020-08-30T18:43:00.50Z

  • 2020-08-30T18:43:00.123456789Z

  • 2020-08-30T18:40:00+03:00

  • 2020-08-30T18:40:00+03:30:20

  • 2020-01-01T23:59:59.123456789+01

  • +12020-01-31T23:59:59Z

See ISO-8601-1:2019, 5.4.2.1b), excluding the format without the offset.

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.

Since Kotlin

2.1

See also

for formatting.

Throws

if the text cannot be parsed or the boundaries of Instant are exceeded.

Samples

import kotlin.test.*
import kotlin.time.*
import kotlin.time.Duration.Companion.hours
import kotlin.time.Duration.Companion.nanoseconds

fun main() { 
   //sampleStart 
   // Parsing a string that represents the Unix epoch.
val unixEpochInstant = Instant.parse("1970-01-01T00:00:00Z")
println(unixEpochInstant.epochSeconds) // 0

// Parsing an ISO 8601 string with a time zone offset.
val instant = Instant.parse("2020-08-30T18:40:00+03:00")
// Instants are presented in the UTC time zone when converted to string.
println(instant.toString()) // 2020-08-30T15:40:00Z 
   //sampleEnd
}