Describe moving kotlinx.datetime.Instant to stdlib #387
Conversation
| ``` | ||
|
|
||
| ```kotlin | ||
| // Darwin |
There was a problem hiding this comment.
According to the UUID KEEP, the stdlib is not specialized for various native targets today. These extensions would no longer be possible.
| 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 | ||
| a proposed replacement. |
There was a problem hiding this comment.
Isn't documentation for the Instant class enough?
There was a problem hiding this comment.
If anyone does read it, it should be enough. Instant.now() is for establishing a smooth enough migration using the compiler errors that it's straightforward to arrive at correct code without reading anything, just with autocomplete.
dkhalanskyjb
force-pushed
the
dkhalanskyjb-instant
branch
from
3852f17
to
7eabfbe
Compare
proposals/stdlib/instant.md
Outdated
|
|
||
| ### `Instant` | ||
|
|
||
| `Instant` denotes a moment in time, regardless of the observer. |
There was a problem hiding this comment.
Maybe best to remove the phrase "regardless of observer" since that evokes relativistic effects. According to the theory of relativity, simultaneity is relative. If events occur in different places, there may be frames of reference in which they are simultaneous, other frames in which one occurs first and other frames in which the other occurred first.
There is no "absolute" frame of reference from which we can say that two events occurring at different places occurred at the "same instant".
So, I'm thinking it's probably best not to mention "observers" since none of our usual language and intuition about instants or clocks works when we try to account for observers in different reference frames.
There was a problem hiding this comment.
Doesn't "regardless of the observer" strongly imply that relativistic effects are not accounted for, given that this definition is absurd in the context of relativity?
There was a problem hiding this comment.
"Regardless of observer" means "for any observer." Or "in any frame of reference."
But everything else we're talking about here is only true if everyone is in the same frame of reference.
In other words, only for specific observers.
So using the phrase "regardless of observer" is the opposite of what we want.
Probably best just not to mention observers.
proposals/stdlib/instant.md
Outdated
| * ### Platform specifics | ||
| * | ||
| * On the JVM, there are `Instant.toJavaInstant()` and `java.time.Instant.toKotlinInstant()` | ||
| * extension functions to convert between `kotlinx.datetime` and `java.time` objects used for the same purpose. |
There was a problem hiding this comment.
The package is no longer kotlinx.datetime.
| leap seconds. | ||
|
|
||
| <https://github.com/ThreeTen/threeten-extra/tree/4e016340b97cab604114d10e02a672c1e94c6be5/src/main/java/org/threeten/extra/scale> | ||
| is an implementation that converts between "UTC `Instant`", a new class, and |
There was a problem hiding this comment.
| is an implementation that converts between "UTC `Instant`", a new class, and | |
| is an implementation that converts between "`UtcInstant`", a new class, and |
assuming you wanted to mention the actual class name
proposals/stdlib/instant.md
Outdated
| // Constructing | ||
| println(runCatching { | ||
| java.time.Instant.ofEpochSecond(Long.MAX_VALUE) | ||
| }) // Failure(java.time.DateTimeException: Instant exceeds minimum or maximum instant) | ||
| println(runCatching { | ||
| kotlinx.datetime.Instant.fromEpochSeconds(Long.MAX_VALUE) | ||
| }) // Success(+1000000000-12-31T23:59:59.999999999Z) | ||
|
|
||
| // Arithmetics | ||
| println(runCatching { | ||
| java.time.Instant.EPOCH | ||
| .plusSeconds(Long.MAX_VALUE) | ||
| }) // Failure(java.time.DateTimeException: Instant exceeds minimum or maximum instant) | ||
| println(runCatching { | ||
| kotlinx.datetime.Instant.fromEpochMilliseconds(0) | ||
| .plus(kotlin.time.Duration.INFINITE) | ||
| }) // Success(+1000000000-12-31T23:59:59.999999999Z) |
There was a problem hiding this comment.
is the kotlinx.datetime package intended here?
proposals/stdlib/instant.md
Outdated
| This API is based on the eponymous API entry in JSR 310 (available in | ||
| the 310bp project and the standard library of Java9 and later): |
There was a problem hiding this comment.
Isn't it available since Java 8?
https://jcp.org/aboutJava/communityprocess/pfd/jsr310/JSR-310-guide.html |
Issue: #395