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

fromEpochSeconds

fun fromEpochSeconds(epochSeconds: Long, nanosecondAdjustment: Long = 0): Instant(source)
fun fromEpochSeconds(epochSeconds: Long, nanosecondAdjustment: Int): Instant(source)

Returns an Instant that is the epochSeconds number of seconds from the epoch instant 1970-01-01T00:00:00Z and the nanosecondAdjustment number of nanoseconds.

nanosecondAdjustment describes how many nanoseconds the given instant is later than the one defined by just epochSeconds. For convenience and flexibility, fromEpochSeconds accepts nanosecondAdjustment values outside of Instant.nanosecondsOfSecond range. Negative nanosecondAdjustment means that the given instant will be earlier than the one defined by just epochSeconds, and values greater than a second will contribute to the resulting number of seconds.

For example, if nanosecondAdjustment is -1, the resulting Instant will be 1 nanosecond earlier than if nanosecondAdjustment was 0, and if it is 1_000_000_000, the resulting Instant will be 1 second later.

The return value is clamped to the boundaries of Instant if the result exceeds them. In any case, it is guaranteed that instants between DISTANT_PAST and DISTANT_FUTURE can be represented.

fromEpochMilliseconds is a similar function for when input data only has millisecond precision.

Since Kotlin

2.3

See also

Samples

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

fun main() { 
   //sampleStart 
   // Creating an Instant representing the Unix epoch.
val unixEpochInstant = Instant.fromEpochSeconds(0)
// Creating an Instant from a specific number of milliseconds and nanoseconds since the Unix epoch.
val instant = Instant.fromEpochSeconds(999_999_999, nanosecondAdjustment = 999_999_999)

// The string representation of the constructed instants.
println(unixEpochInstant) // 1970-01-01T00:00:00Z
println(instant) // 2001-09-09T01:46:39.999999999Z

// Creating an Instant with negative nanosecondAdjustment
val earlierInstant = Instant.fromEpochSeconds(999_999_999, nanosecondAdjustment = -999_999_999)
println(earlierInstant) // 2001-09-09T01:46:38.000000001Z
println("earlierInstant < instant is ${earlierInstant < instant}") // true

// Creating an Instant with nanosecondAdjustment > 1s
val laterInstant = Instant.fromEpochSeconds(999_999_999, nanosecondAdjustment = 1_999_999_999)
println(laterInstant) // 2001-09-09T01:46:40.999999999Z
println("laterInstant > instant is ${laterInstant > instant}") // true 
   //sampleEnd
}
import kotlin.test.*
import kotlin.time.*
import kotlin.time.Duration.Companion.hours
import kotlin.time.Duration.Companion.nanoseconds
import kotlin.time.Duration.Companion.seconds

fun main() { 
   //sampleStart 
   // When nanosecondAdjustment is within the range `0..999_999_999`,
// epochSeconds and nanosecondsOfSecond hold the exact values provided.
val instant1 = Instant.fromEpochSeconds(999_999, nanosecondAdjustment = 123_456_789)
println(instant1.epochSeconds) // 999999
println(instant1.nanosecondsOfSecond) // 123456789

// When nanosecondAdjustment exceeds `999_999_999`, the excess contributes to whole seconds,
// increasing epochSeconds. The remainder forms the new value of nanosecondsOfSecond.
val instant2 = Instant.fromEpochSeconds(1_000_000, nanosecondAdjustment = 100_123_456_789)
println(instant2.epochSeconds) // 1000100
println(instant2.nanosecondsOfSecond) // 123456789

// When nanosecondAdjustment is negative, epochSeconds is decreased
// to offset the negative nanoseconds and ensure nanosecondsOfSecond remains non-negative.
val instant3 = Instant.fromEpochSeconds(1_000_000, nanosecondAdjustment = -100_876_543_211)
println(instant3.epochSeconds) // 999899
println(instant3.nanosecondsOfSecond) // 123456789 
   //sampleEnd
}