From 27da4b000f368fea111ea456b8a2d5101dcd5e68 Mon Sep 17 00:00:00 2001 From: Dmitry Khalanskiy Date: Mon, 26 Aug 2024 11:35:25 +0200 Subject: [PATCH] Address the review --- proposals/stdlib/instant.md | 59 +++++++++++++++---------------------- 1 file changed, 24 insertions(+), 35 deletions(-) diff --git a/proposals/stdlib/instant.md b/proposals/stdlib/instant.md index 360d27471..07278a034 100644 --- a/proposals/stdlib/instant.md +++ b/proposals/stdlib/instant.md @@ -45,7 +45,7 @@ Non-examples: ### `Clock` A `Clock` implementation is a way to obtain the current `Instant`. -The `Clock.SYSTEM` default implementation, available on all platforms, queries +The `Clock.System` default implementation, available on all platforms, queries the system clock (the one also used to display the current date and time in the corner of your screen). `Clock` does not provide the current time zone, and so it is not enough on its @@ -101,7 +101,7 @@ This information is stored as `Instant` values. **Example**: listing all files that were modified in the last 24 hours. These calculations require knowing the current moment in time (accessed via -`Clock.SYSTEM`) and the moment in time when some event happened. +`Clock.System`) and the moment in time when some event happened. They do not require knowing the current system time zone: how long ago something happened does not depend on what exactly clocks said, it only depends on the actual passage of time. In fact, it's _incorrect_ to take the current time zone @@ -217,10 +217,8 @@ The specifics of what gets added is given below. * * The [Clock] interface is the primary way to obtain the current moment: * - * ``` - * val clock: Clock = Clock.System - * val instant = clock.now() - * ``` + * - `val clock: Clock = Clock.System` + * - `val instant = clock.now()` * * The [Clock.System] implementation uses the platform-specific system clock to obtain the current moment. * Note that this clock is not guaranteed to be monotonic, and the user or the system may adjust it at any time, @@ -231,16 +229,12 @@ The specifics of what gets added is given below. * * The [plus] and [minus] operators can be used to add [Duration]s to and subtract them from an [Instant]: * - * ``` - * Clock.System.now() + 5.seconds // 5 seconds from now - * ``` + * - `Clock.System.now() + 5.seconds // 5 seconds from now` * * Also, there is a [minus] operator that returns the [Duration] representing the difference between two instants: * - * ``` - * val kotlinRelease = Instant.parse("2016-02-15T02:00T12:00+03:00") - * val kotlinStableDuration = Clock.System.now() - kotlinRelease - * ``` + * - `val kotlinRelease = Instant.parse("2016-02-15T02:00T12:00+03:00")` + * - `val kotlinStableDuration = Clock.System.now() - kotlinRelease` * * ### Platform specifics * @@ -255,31 +249,25 @@ The specifics of what gets added is given below. * `1970-01-01T00:00:00Z` (the Unix epoch). * [epochSeconds] and [nanosecondsOfSecond] can be used to obtain the number of seconds and nanoseconds since the epoch. * - * ``` - * val instant = Instant.fromEpochSeconds(1709898983, 123456789) - * instant.epochSeconds // 1709898983 - * instant.nanosecondsOfSecond // 123456789 - * ``` + * - `val instant = Instant.fromEpochSeconds(1709898983, 123456789)` + * - `instant.epochSeconds // 1709898983` + * - `instant.nanosecondsOfSecond // 123456789` * * [fromEpochMilliseconds] allows constructing an instant from the number of milliseconds since the epoch. * [toEpochMilliseconds] can be used to obtain the number of milliseconds since the epoch. * Note that [Instant] supports nanosecond precision, so converting to milliseconds is a lossy operation. * - * ``` - * val instant1 = Instant.fromEpochSeconds(1709898983, 123456789) - * instant1.nanosecondsOfSecond // 123456789 - * val milliseconds = instant1.toEpochMilliseconds() // 1709898983123 - * val instant2 = Instant.fromEpochMilliseconds(milliseconds) - * instant2.nanosecondsOfSecond // 123000000 - * ``` + * - `val instant1 = Instant.fromEpochSeconds(1709898983, 123456789)` + * - `instant1.nanosecondsOfSecond // 123456789` + * - `val milliseconds = instant1.toEpochMilliseconds() // 1709898983123` + * - `val instant2 = Instant.fromEpochMilliseconds(milliseconds)` + * - `instant2.nanosecondsOfSecond // 123000000` * * [parse] and [toString] methods can be used to obtain an [Instant] from and convert it to a string in the * ISO 8601 extended format. * - * ``` - * val instant = Instant.parse("2023-01-02T22:35:01+01:00") - * instant.toString() // 2023-01-02T21:35:01Z - * ``` + * - `val instant = Instant.parse("2023-01-02T22:35:01+01:00")` + * - `instant.toString() // 2023-01-02T21:35:01Z` */ public expect class Instant : Comparable { @@ -815,7 +803,7 @@ val nextEvent = filter { it > currentTime }.minOrNull() ?: maxTimestamp if (nextEvent != maxTimestamp) { - println("The next event is $earliestEvent") + println("The next event is $nextEvent") } else { println("No events to execute") } @@ -941,8 +929,9 @@ A common way to obtain the current `Instant` on the JVM is to call `Instant.now()`: * is 13000 hits as of writing. -* is less than - 100 hits. +* is about 1200 hits. + This isn't exhaustive, but gives an estimate of how often people use + dependency injection of clocks. It is not obvious to people who want to obtain the current `Instant` that a class like `Clock` even exists, so we direct them to it using a deprecation with @@ -951,7 +940,7 @@ a proposed replacement. #### `DISTANT_PAST` + `DISTANT_FUTURE` + `isDistantPast` + `isDistantFuture` On the JVM, `Instant.MAX` and `Instant.MIN` are occasionally used as default -values, mostly for the purposes of finding the earlies or the latest instant: +values, mostly for the purposes of finding the earliest or the latest instant: ```kotlin var earliestEvent = java.time.Instant.MAX @@ -1232,7 +1221,7 @@ fun epochSecondsLaterThanMaxInstant(epochSeconds: Long): Boolean = Exception: `Clock.asTimeSource` does not get the new overload. - For every function that returns but doesn't accept an `Instant`, hides it and adds a new function, one that returns `kotlin.time.Instant`, - but with a different `JvmName`. + but with different platform names. - Deprecates the `Instant` serializers with a warning. - A new version of `kotlinx-datetime` is published with this. * One major version of `kotlinx-datetime` later: @@ -1269,7 +1258,7 @@ fun LocalDateTime.toInstant(): kotlinx.datetime.Instant fun kotlin.time.Instant.toLocalDateTime(): LocalDateTime -@JvmName("temporary_toInstant") +@JsName("temporary_toInstant") // and other PlatformName annotations fun LocalDateTime.toInstant(): kotlin.time.Instant // 0.X+2.0