From 75b2e8e59a82b59bc1434c4f700b15750e595c93 Mon Sep 17 00:00:00 2001 From: Ellet <73608287+freshtechtips@users.noreply.github.com> Date: Sat, 2 Dec 2023 15:20:56 +0300 Subject: [PATCH 1/2] docs: fix typos in README.md --- README.md | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index bfe0296b..974250d8 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# kotlinx-datetime +# Kotlinx DateTime [![Kotlin Alpha](https://kotl.in/badges/alpha.svg)](https://kotlinlang.org/docs/components-stability.html) [![JetBrains official project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) @@ -11,26 +11,26 @@ A multiplatform Kotlin library for working with date and time. -See [Using in your projects](#using-in-your-projects) for the instructions how to setup a dependency in your project. +See [Using in your projects](#using-in-your-projects) for the instructions on how to set up a dependency in your project. ## Design overview -There are a few guiding principles in the design of `kotlinx-datetime`. First of all, it is pragmatic, focused +There are a few guiding principles in the design of `kotlinx-datetime`. First of all, it is pragmatic and focused on the most common problems developers face every day (pun intended) when working with dates and times. It is not all-encompassing and lacks some domain-specific utilities that special-purpose applications might need. We chose convenience over generality, so the API surface this library provides is as minimal as possible -to meet the use-cases. +to meet the use cases. -The library puts a clear boundary between the physical time of an instant and the local, time-zone dependent +The library puts a clear boundary between the physical time of an instant and the local, time-zone-dependent civil time, consisting of components such as year, month, etc that people use when talking about time. We intentionally avoid entities in the library that mix both together and could be misused. However, there are convenience operations that take, for example, a physical instant and perform a calendar-based adjustment (such as adding a month); all such operations -explicitly take a time-zone information as parameter to clearly state that their result depends on the civil time-zone +explicitly take time-zone information as a parameter to clearly state that their result depends on the civil time zone rules which are subject to change at any time. The library is based on the ISO 8601 international standard, other ways to represent dates and times are out of -its scope. Internationalization (such as locale-specific month and day names) is out the scope, too. +its scope. Internationalization (such as locale-specific month and day names) is out of the scope, too. ## Types @@ -59,7 +59,7 @@ Here is some basic advice on how to choose which of the date-carrying types to u - Use `LocalDateTime` to represent a time of the event that is scheduled to happen in the far future at a certain local time (like a scheduled meeting in a few months from now). You'll have to keep track of the `TimeZone` of - the scheduled event separately. Try to avoid converting future events to `Instant` in advance, because time-zone + the scheduled event separately. Try to avoid converting future events to `Instant` in advance, because time zone rules might change unexpectedly in the future. In this [blog post](https://codeblog.jonskeet.uk/2019/03/27/storing-utc-is-not-a-silver-bullet/), you can read more about why it's not always a good idea to use `Instant` everywhere. @@ -71,7 +71,7 @@ Here is some basic advice on how to choose which of the date-carrying types to u ## Operations -With the above types you can get the following operations done. +With the above types, you can get the following operations done. ### Getting the current moment of time @@ -95,7 +95,7 @@ val currentMoment = Clock.System.now() ### Converting an instant to local date and time components -An `Instant` is just a counter of high resolution time intervals since the beginning of time scale. +An `Instant` is just a counter of high-resolution time intervals since the beginning of the time scale. To get human readable components from an `Instant` value, you need to convert it to the `LocalDateTime` type that represents date and time components without a reference to the particular time zone. @@ -152,7 +152,7 @@ val knownDate = LocalDate(2020, 2, 21) ### Getting local time components -A `LocalTime` represents local time without date. You can obtain one from an `Instant` +A `LocalTime` represents local time without a date. You can obtain one from an `Instant` by converting it to `LocalDateTime` and taking its `time` property. ```kotlin @@ -160,23 +160,23 @@ val now: Instant = Clock.System.now() val thisTime: LocalTime = now.toLocalDateTime(TimeZone.currentSystemDefault()).time ``` -A `LocalTime` can be constructed from four components, hour, minute, second and nanosecond: +A `LocalTime` can be constructed from four components, hour, minute, second, and nanosecond: ```kotlin val knownTime = LocalTime(hour = 23, minute = 59, second = 12) val timeWithNanos = LocalTime(hour = 23, minute = 59, second = 12, nanosecond = 999) val hourMinute = LocalTime(hour = 12, minute = 13) ``` -### Converting instant to and from unix time +### Converting instant to and from Unix time An `Instant` can be converted to a number of milliseconds since the Unix/POSIX epoch with the `toEpochMilliseconds()` function. To convert back, use the companion object function `Instant.fromEpochMilliseconds(Long)`. ### Converting instant and local date/time to and from string -Currently, `Instant`, `LocalDateTime`, `LocalDate` and `LocalTime` only support ISO-8601 format. +Currently, `Instant`, `LocalDateTime`, `LocalDate`, and `LocalTime` only support ISO-8601 format. The `toString()` function is used to convert the value to a string in that format, and -the `parse` function in companion object is used to parse a string representation back. +the `parse` function in the companion object is used to parse a string representation back. ```kotlin @@ -188,11 +188,11 @@ val instantBefore = Instant.parse("2010-06-01T22:19:44.475Z") Alternatively, the `String.to...()` extension functions can be used instead of `parse`, where it feels more convenient: -`LocalDateTime` uses a similar format, but without `Z` UTC time zone designator in the end. +`LocalDateTime` uses a similar format, but without `Z` UTC time zone designator at the end. `LocalDate` uses a format with just year, month, and date components, e.g. `2010-06-01`. -`LocalTime` uses a format with just hour, minute, second and (if non-zero) nanosecond components, e.g. `12:01:03`. +`LocalTime` uses a format with just hour, minute, second, and (if non-zero) nanosecond components, e.g. `12:01:03`. ```kotlin "2010-06-01T22:19:44.475Z".toInstant() @@ -240,7 +240,7 @@ val threeYearsAndAMonthLater = now.plus(DateTimePeriod(years = 3, months = 1), s ``` Note that `plus` and `...until` operations require a `TimeZone` as a parameter because the calendar interval between -two particular instants can be different, when calculated in different time zones. +two particular instants can be different when calculated in different time zones. ### Date arithmetic @@ -253,7 +253,7 @@ Similar operations with date units are provided for `LocalDate` type: Notice that, instead of the general `DateTimeUnit` and `DateTimePeriod` types, we're using their subtypes `DateTimeUnit.DateBased` and `DatePeriod` respectively. This allows preventing the situations when -time components are being added to a date at compile time. +time components are being added to date at compile time. ### Date + time arithmetic @@ -284,7 +284,7 @@ val localDateTimeTwoDaysLater = instantTwoDaysLater.toLocalDateTime(timeZone) ## Implementation -The implementation of date/time types, such as `Instant`, `LocalDateTime`, `TimeZone` and so on, relies on: +The implementation of date/time types, such as `Instant`, `LocalDateTime`, `TimeZone`, and so on, relies on: - in JVM: [`java.time`](https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html) API; - in Js and Wasm-Js: [`js-joda`](https://js-joda.github.io/js-joda/) library; @@ -301,7 +301,7 @@ The implementation of date/time types, such as `Instant`, `LocalDateTime`, `Time > Note that the library is experimental, and the API is subject to change. -The library is published to Maven Central. +The library is published by Maven Central. The library is compatible with the Kotlin Standard Library not lower than `1.9.0`. @@ -318,7 +318,7 @@ repositories { } ``` -- In multiplatform projects, add a dependency to the commonMain source set dependencies +- In multiplatform projects, add a dependency to the `commonMain` source set of dependencies ```kotlin kotlin { sourceSets { @@ -343,7 +343,7 @@ dependencies { By default, there's only one time zone available in Kotlin/JS: the `SYSTEM` time zone with a fixed offset. -If you want to use all time zones in Kotlin/JS platform, you need to add the following npm dependency: +If you want to use all time zones in the Kotlin/JS platform, you need to add the following npm dependency: ```kotlin kotlin { @@ -357,7 +357,7 @@ kotlin { } ``` -and after that add the following initialization code in your project: +and after that add the following initialization code to your project: ```kotlin @JsModule("@js-joda/timezone") @@ -391,7 +391,7 @@ git submodule update ``` The project requires JDK 8 to build classes and to run tests. -Gradle will try to find it among the installed JDKs or [provision](https://docs.gradle.org/current/userguide/toolchains.html#sec:provisioning) it automatically if it couldn't be found. +Gradle will try to find it among the installed JDKs or [provision](https://docs.gradle.org/current/userguide/toolchains.html#sec:provisioning) automatically if it can't be found. The path to JDK 8 can be additionally specified with the environment variable `JDK_8`. For local builds, you can use a later version of JDK if you don't have that version installed. Specify the version of this JDK with the `java.mainToolchainVersion` Gradle property. From 525497036c3f1d873f959c453203093060760531 Mon Sep 17 00:00:00 2001 From: Ellet <73608287+freshtechtips@users.noreply.github.com> Date: Tue, 5 Dec 2023 20:15:41 +0300 Subject: [PATCH 2/2] revert: Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 974250d8..2db43ea6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Kotlinx DateTime +# kotlinx-datetime [![Kotlin Alpha](https://kotl.in/badges/alpha.svg)](https://kotlinlang.org/docs/components-stability.html) [![JetBrains official project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) @@ -301,7 +301,7 @@ The implementation of date/time types, such as `Instant`, `LocalDateTime`, `Time > Note that the library is experimental, and the API is subject to change. -The library is published by Maven Central. +The library is published to Maven Central. The library is compatible with the Kotlin Standard Library not lower than `1.9.0`.