diff --git a/README.md b/README.md index a30126eeb..a9bf3474d 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ The library provides a basic set of types for working with date and time: - `DatePeriod` is a subclass of `DateTimePeriod` with zero time components, it represents a difference between two LocalDate values decomposed into date units. - `DateTimeUnit` provides a set of predefined date and time units to use in arithmetic operations on `Instant` and `LocalDate`. -- `UtcOffset` represents the amount of time the local date/time at a particular time zone differs from the date/time at UTC. +- `UtcOffset` represents the amount of time the local datetime at a particular time zone differs from the datetime at UTC. ### Type use-cases @@ -63,7 +63,7 @@ Here is some basic advice on how to choose which of the date-carrying types to u 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. - Also, use `LocalDateTime` to decode an `Instant` to its local date-time components for display and UIs. + Also, use `LocalDateTime` to decode an `Instant` to its local datetime components for display and UIs. - Use `LocalDate` to represent the date of an event that does not have a specific time associated with it (like a birth date). @@ -99,7 +99,7 @@ An `Instant` is just a counter of high resolution time intervals since the begin 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. -The `TimeZone` type provides the rules to convert instants from and to date/time components. +The `TimeZone` type provides the rules to convert instants from and to datetime components. ```kotlin val currentMoment: Instant = Clock.System.now() @@ -172,7 +172,7 @@ val hourMinute = LocalTime(hour = 12, minute = 13) 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 the ISO 8601 string +### Converting instant and local datetime to and from the ISO 8601 string `Instant`, `LocalDateTime`, `LocalDate` and `LocalTime` provide shortcuts for parsing and formatting them using the extended ISO 8601 format. @@ -268,7 +268,7 @@ dateTimeFormat.parse("2023-12-24T23:59:59") Sometimes, the required string format doesn't fully correspond to any of the classes `kotlinx-datetime` provides. In these cases, `DateTimeComponents`, a -collection of all date-time fields, can be used instead. +collection of all datetime fields, can be used instead. ```kotlin // import kotlinx.datetime.format.* @@ -341,7 +341,7 @@ val diffInMonths = instantInThePast.until(Clock.System.now(), DateTimeUnit.MONTH ``` There are also shortcuts `yearsUntil(...)`, `monthsUntil(...)`, and `daysUntil(...)`. -A particular amount of date/time units or a date/time period can be added to an `Instant` with the `plus` function: +A particular amount of datetime units or a datetime period can be added to an `Instant` with the `plus` function: ```kotlin val now = Clock.System.now() @@ -395,7 +395,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 datetime 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; @@ -405,7 +405,7 @@ The implementation of date/time types, such as `Instant`, `LocalDateTime`, `Time ## Known/open issues, work TBD - [x] Some kind of `Clock` interface is needed as a pluggable replacement for `Instant.now()`. -- [ ] Flexible locale-neutral parsing and formatting facilities are needed to support various date/time interchange +- [ ] Flexible locale-neutral parsing and formatting facilities are needed to support various datetime interchange formats that are used in practice (in particular, various RFCs). ## Using in your projects diff --git a/core/common/src/Clock.kt b/core/common/src/Clock.kt index 6d3dee7c3..e9cd9137e 100644 --- a/core/common/src/Clock.kt +++ b/core/common/src/Clock.kt @@ -21,8 +21,8 @@ public interface Clock { /** * Returns the [Instant] corresponding to the current time, according to this clock. * - * It is not guaranteed that calling [now] later will return a larger [Instant]. - * In particular, for [Clock.System] it is completely expected that the opposite will happen, + * Calling [now] later is not guaranteed to return a larger [Instant]. + * In particular, for [Clock.System], the opposite is completely expected, * and it must be taken into account. * See the [System] documentation for details. * diff --git a/core/common/src/DateTimePeriod.kt b/core/common/src/DateTimePeriod.kt index 0ce452ece..f9b2d3f3b 100644 --- a/core/common/src/DateTimePeriod.kt +++ b/core/common/src/DateTimePeriod.kt @@ -434,7 +434,7 @@ public class DatePeriod internal constructor( /** * Constructs a new [DatePeriod]. * - * It is always recommended to name the arguments explicitly when constructing this manually, + * It is recommended to always name the arguments explicitly when constructing this manually, * like `DatePeriod(years = 1, months = 12, days = 16)`. * * The passed numbers are not stored as is but are normalized instead for human readability, so, for example, @@ -527,7 +527,7 @@ internal fun buildDateTimePeriod(totalMonths: Int = 0, days: Int = 0, totalNanos /** * Constructs a new [DateTimePeriod]. If all the time components are zero, returns a [DatePeriod]. * - * It is recommended to always explicitly name the arguments when constructing this manually, + * It is recommended to always name the arguments explicitly when constructing this manually, * like `DateTimePeriod(years = 1, months = 12, days = 16)`. * * The passed numbers are not stored as is but are normalized instead for human readability, so, for example, diff --git a/core/common/src/DateTimeUnit.kt b/core/common/src/DateTimeUnit.kt index 97ab32f77..3e9a7313a 100644 --- a/core/common/src/DateTimeUnit.kt +++ b/core/common/src/DateTimeUnit.kt @@ -14,9 +14,9 @@ import kotlin.time.Duration.Companion.nanoseconds /** * A unit for measuring time; for example, a second, 20 seconds, a day, a month, or a quarter. * - * This class is used to express arithmetic operations like addition and subtraction on date-time values: - * for example, adding 10 days to a date-time value, subtracting 5 hours from a date-time value, or finding the - * number of 30-second intervals between two date-time values. + * This class is used to express arithmetic operations like addition and subtraction on datetime values: + * for example, adding 10 days to a datetime value, subtracting 5 hours from a datetime value, or finding the + * number of 30-second intervals between two datetime values. * * ### Interaction with other entities * @@ -39,7 +39,7 @@ import kotlin.time.Duration.Companion.nanoseconds * "two days and three hours". * [DatePeriod] is specifically a combination of [DateTimeUnit.DateBased] values. * [DateTimePeriod] is more flexible than [DateTimeUnit] because it can express a combination of values with different - * kinds of units, but in exchange, the duration of time between two [Instant] or [LocalDate] values can be + * kinds of units. However, in exchange, the duration of time between two [Instant] or [LocalDate] values can be * measured in terms of some [DateTimeUnit], but not [DateTimePeriod] or [DatePeriod]. * * ### Construction, serialization, and deserialization @@ -63,7 +63,7 @@ import kotlin.time.Duration.Companion.nanoseconds public sealed class DateTimeUnit { /** - * Produces a date-time unit that is a multiple of this unit times the specified integer [scalar] value. + * Produces a datetime unit that is a multiple of this unit times the specified integer [scalar] value. * * @throws ArithmeticException if the result overflows. * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.multiplication @@ -71,12 +71,12 @@ public sealed class DateTimeUnit { public abstract operator fun times(scalar: Int): DateTimeUnit /** - * A [date-time unit][DateTimeUnit] that has the precise time duration. + * A [datetime unit][DateTimeUnit] that has the precise time duration. * * Such units are independent of the time zone. * Any such unit can be represented as some fixed number of nanoseconds. * - * @see DateTimeUnit for a description of date-time units in general. + * @see DateTimeUnit for a description of datetime units in general. * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.timeBasedUnit */ @Serializable(with = TimeBasedDateTimeUnitSerializer::class) @@ -141,13 +141,13 @@ public sealed class DateTimeUnit { } /** - * A [date-time unit][DateTimeUnit] equal to some number of days or months. + * A [datetime unit][DateTimeUnit] equal to some number of days or months. * * Operations involving `DateBased` units are performed on dates. The same operations on [Instants][Instant] * require a [TimeZone] to find the corresponding [LocalDateTimes][LocalDateTime] first to perform * the operation with the date component of these `LocalDateTime` values. * - * @see DateTimeUnit for a description of date-time units in general. + * @see DateTimeUnit for a description of datetime units in general. * @see DateTimeUnit.DayBased for specifically day-based units. * @see DateTimeUnit.MonthBased for specifically month-based units. */ @@ -162,17 +162,17 @@ public sealed class DateTimeUnit { } /** - * A [date-time unit][DateTimeUnit] equal to some number of calendar days. + * A [datetime unit][DateTimeUnit] equal to some number of calendar days. * * A calendar day is not considered identical to 24 hours. * Thus, a `DayBased` unit cannot be expressed as a multiple of some [TimeBased] unit. * * The reason lies in time zone transitions, because of which some days can be 23 or 25 hours. * For example, we say that exactly a whole day has passed between `2019-10-27T02:59` and `2019-10-28T02:59` - * in Berlin, despite the fact that the clocks were turned back one hour, so there are, in fact, 25 hours - * between the two date-times. + * in Berlin, even though the clocks were turned back one hour, so there are, in fact, 25 hours + * between the two datetimes. * - * @see DateTimeUnit for a description of date-time units in general. + * @see DateTimeUnit for a description of datetime units in general. * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.dayBasedUnit */ @Serializable(with = DayBasedDateTimeUnitSerializer::class) @@ -202,12 +202,12 @@ public sealed class DateTimeUnit { } /** - * A [date-time unit][DateTimeUnit] equal to some number of months. + * A [datetime unit][DateTimeUnit] equal to some number of months. * * Since different months have a different number of days, a `MonthBased` unit cannot be expressed * as a multiple of some [DayBased]-unit. * - * @see DateTimeUnit for a description of date-time units in general. + * @see DateTimeUnit for a description of datetime units in general. * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.monthBasedUnit */ @Serializable(with = MonthBasedDateTimeUnitSerializer::class) diff --git a/core/common/src/DayOfWeek.kt b/core/common/src/DayOfWeek.kt index 32c18f367..ac4388b04 100644 --- a/core/common/src/DayOfWeek.kt +++ b/core/common/src/DayOfWeek.kt @@ -31,7 +31,7 @@ public expect enum class DayOfWeek { public val DayOfWeek.isoDayNumber: Int get() = ordinal + 1 /** - * Returns the [DayOfWeek] instance for the given ISO 8601 week day number. Monday is 1, Sunday is 7. + * Returns the [DayOfWeek] instance for the given ISO 8601 weekday number. Monday is 1, and Sunday is 7. * * @throws IllegalArgumentException if the day number is not in the range 1..7 * @sample kotlinx.datetime.test.samples.DayOfWeekSamples.constructorFunction diff --git a/core/common/src/Exceptions.kt b/core/common/src/Exceptions.kt index a614c3df4..1f5e93ed2 100644 --- a/core/common/src/Exceptions.kt +++ b/core/common/src/Exceptions.kt @@ -6,7 +6,7 @@ package kotlinx.datetime /** - * Thrown by date-time arithmetic operations if the result cannot be computed or represented. + * Thrown by datetime arithmetic operations if the result cannot be computed or represented. */ public class DateTimeArithmeticException: RuntimeException { public constructor(): super() diff --git a/core/common/src/Instant.kt b/core/common/src/Instant.kt index 6168b7b8f..36fd40d28 100644 --- a/core/common/src/Instant.kt +++ b/core/common/src/Instant.kt @@ -15,7 +15,7 @@ import kotlin.time.* /** * A moment in time. * - * A point in time must be uniquely identified so that it is independent of a time zone. + * A point in time must be uniquely identified in a way that is independent of a time zone. * For example, `1970-01-01, 00:00:00` does not represent a moment in time since this would happen at different times * in different time zones: someone in Tokyo would think it is already `1970-01-01` several hours earlier than someone in * Berlin would. To represent such entities, use [LocalDateTime]. @@ -36,7 +36,7 @@ import kotlin.time.* * ``` * * 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 it may be adjusted by the user or the system at any time, + * Note that this clock is not guaranteed to be monotonic, and the user or the system may adjust it at any time, * so it should not be used for measuring time intervals. * For that, consider using [TimeSource.Monotonic] and [TimeMark] instead of [Clock.System] and [Instant]. * @@ -79,7 +79,7 @@ import kotlin.time.* * Clock.System.now() + 5.seconds // 5 seconds from now * ``` * - * Durations can also be represented as multiples of some [time-based date-time unit][DateTimeUnit.TimeBased]: + * Durations can also be represented as multiples of some [time-based datetime unit][DateTimeUnit.TimeBased]: * * ``` * Clock.System.now().plus(4, DateTimeUnit.HOUR) // 4 hours from now @@ -121,7 +121,7 @@ import kotlin.time.* * // Two months, three days, four hours, and five minutes until the concert * ``` * - * or [Instant.until] method, as well as [Instant.daysUntil], [Instant.monthsUntil], + * Or the [Instant.until] method, as well as [Instant.daysUntil], [Instant.monthsUntil], * and [Instant.yearsUntil] extension functions: * * ``` @@ -223,7 +223,7 @@ public expect class Instant : Comparable { /** * Returns the number of milliseconds from the epoch instant `1970-01-01T00:00:00Z`. * - * Any fractional part of millisecond is rounded toward zero to the whole number of milliseconds. + * Any fractional part of a millisecond is rounded toward zero to the whole number of milliseconds. * * If the result does not fit in [Long], returns [Long.MAX_VALUE] for a positive result or [Long.MIN_VALUE] for a negative result. * @@ -362,13 +362,13 @@ public expect class Instant : Comparable { /** * A shortcut for calling [DateTimeFormat.parse], followed by [DateTimeComponents.toInstantUsingOffset]. * - * Parses a string that represents an instant including date and time components and a mandatory + * Parses a string that represents an instant, including date and time components and a mandatory * time zone offset and returns the parsed [Instant] value. * * 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 valid time. + * 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. * * If the format is not specified, [DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET] is used. diff --git a/core/common/src/LocalDateTime.kt b/core/common/src/LocalDateTime.kt index dad1a2c28..db4533b8c 100644 --- a/core/common/src/LocalDateTime.kt +++ b/core/common/src/LocalDateTime.kt @@ -19,9 +19,9 @@ import kotlinx.serialization.Serializable * this on their clocks at different times, but it is a [LocalDateTime]. * * The main purpose of this class is to provide human-readable representations of [Instant] values, to transfer them - * as data, or to define future planned events that will have the same local date-time even if the time zone rules + * as data, or to define future planned events that will have the same local datetime even if the time zone rules * change. - * In all other cases when a specific time zone is known, it is recommended to use [Instant] instead. + * In all other cases, when a specific time zone is known, it is recommended to use [Instant] instead. * * ### Arithmetic operations * @@ -30,11 +30,11 @@ import kotlinx.serialization.Serializable * * For example, in Berlin, naively adding one day to `2021-03-27T02:16:20` without accounting for the time zone would * result in `2021-03-28T02:16:20`. - * However, the resulting local date-time cannot be observed in that time zone + * However, the resulting local datetime cannot be observed in that time zone * because the clocks moved forward from `02:00` to `03:00` on that day. * This is known as a "time gap" or a "spring forward" transition. * - * Similarly, the local date-time `2021-10-31T02:16:20` is ambiguous, + * Similarly, the local datetime `2021-10-31T02:16:20` is ambiguous, * because the clocks moved back from `03:00` to `02:00`. * This is known as a "time overlap" or a "fall back" transition. * @@ -97,8 +97,8 @@ import kotlinx.serialization.Serializable * - [LocalDateTimeIso8601Serializer] for the ISO 8601 extended format. * - [LocalDateTimeComponentSerializer] for an object with components. * - * @see LocalDate for only the date part of the date/time value. - * @see LocalTime for only the time part of the date/time value. + * @see LocalDate for only the date part of the datetime value. + * @see LocalTime for only the time part of the datetime value. * @see Instant for the representation of a specific moment in time independent of a time zone. * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.fromDateAndTime * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.alternativeConstruction @@ -112,7 +112,7 @@ public expect class LocalDateTime : Comparable { /** * A shortcut for calling [DateTimeFormat.parse]. * - * Parses a string that represents a date/time value including date and time components + * Parses a string that represents a datetime value including date and time components * but without any time zone component and returns the parsed [LocalDateTime] value. * * If [format] is not specified, [Formats.ISO] is used. @@ -172,7 +172,7 @@ public expect class LocalDateTime : Comparable { /** * ISO 8601 extended format. * - * Examples of date/time in ISO 8601 format: + * Examples of datetime in ISO 8601 format: * - `2020-08-30T18:43` * - `+12020-08-30T18:43:00` * - `0000-08-30T18:43:00.5` @@ -206,7 +206,7 @@ public expect class LocalDateTime : Comparable { * - [second] `0..59` * - [nanosecond] `0..999_999_999` * - * @throws IllegalArgumentException if any parameter is out of range, + * @throws IllegalArgumentException if any parameter is out of range * or if [dayOfMonth] is invalid for the given [monthNumber] and [year]. * * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.constructorFunctionWithMonthNumber @@ -299,49 +299,49 @@ public expect class LocalDateTime : Comparable { public val dayOfYear: Int /** - * Returns the hour-of-day (`0..59`) [time] component of this date/time value. + * Returns the hour-of-day (`0..59`) [time] component of this datetime value. * * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.timeComponents */ public val hour: Int /** - * Returns the minute-of-hour (`0..59`) [time] component of this date/time value. + * Returns the minute-of-hour (`0..59`) [time] component of this datetime value. * * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.timeComponents */ public val minute: Int /** - * Returns the second-of-minute (`0..59`) [time] component of this date/time value. + * Returns the second-of-minute (`0..59`) [time] component of this datetime value. * * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.timeComponents */ public val second: Int /** - * Returns the nanosecond-of-second (`0..999_999_999`) [time] component of this date/time value. + * Returns the nanosecond-of-second (`0..999_999_999`) [time] component of this datetime value. * * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.timeComponents */ public val nanosecond: Int /** - * Returns the date part of this date/time value. + * Returns the date part of this datetime value. * * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateAndTime */ public val date: LocalDate /** - * Returns the time part of this date/time value. + * Returns the time part of this datetime value. * * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateAndTime */ public val time: LocalTime /** - * Compares `this` date/time value with the [other] date/time value. + * Compares `this` datetime value with the [other] datetime value. * Returns zero if this value is equal to the other, * a negative number if this value represents earlier civil time than the other, * and a positive number if this value represents later civil time than the other. @@ -361,7 +361,7 @@ public expect class LocalDateTime : Comparable { public override operator fun compareTo(other: LocalDateTime): Int /** - * Converts this date/time value to the ISO 8601 string representation. + * Converts this datetime value to the ISO 8601 string representation. * * For readability, if the time represents a round minute (without seconds or fractional seconds), * the string representation will not include seconds. Also, fractions of seconds will add trailing zeros to diff --git a/core/common/src/LocalTime.kt b/core/common/src/LocalTime.kt index 79c61793d..695a1090e 100644 --- a/core/common/src/LocalTime.kt +++ b/core/common/src/LocalTime.kt @@ -29,7 +29,7 @@ import kotlinx.serialization.Serializable * * ### Arithmetic operations * - * Arithmetic operations on [LocalTime] are not provided, because they are not well-defined without a date and + * Arithmetic operations on [LocalTime] are not provided because they are not well-defined without a date and * a time zone. * See [LocalDateTime] for an explanation of why not accounting for time zone transitions may lead to incorrect results. * To perform arithmetic operations on time values, first, obtain an [Instant]. @@ -42,8 +42,8 @@ import kotlinx.serialization.Serializable * val timeThreeHoursLater = instantThreeHoursLater.toLocalDateTime(TimeZone.currentSystemDefault()).time * ``` * - * Because this pattern is extremely verbose and difficult to get right, it is recommended to work exclusively - * with [Instant] and only obtain a [LocalTime] when it is necessary to display the time to the user. + * Since this pattern is extremely verbose and difficult to get right, it is recommended to work exclusively + * with [Instant] and only obtain a [LocalTime] when displaying the time to the user. * * ### Platform specifics * @@ -53,10 +53,10 @@ import kotlinx.serialization.Serializable * * ### Construction, serialization, and deserialization * - * [LocalTime] can be constructed directly from its components, using the constructor. See sample 1. + * [LocalTime] can be constructed directly from its components using the constructor. See sample 1. * * [fromSecondOfDay], [fromMillisecondOfDay], and [fromNanosecondOfDay] can be used to obtain a [LocalTime] from the - * number of seconds, milliseconds, or nanoseconds since the start of the day, assuming there the offset from the UTC + * number of seconds, milliseconds, or nanoseconds since the start of the day, assuming that the offset from the UTC * does not change during the day. * [toSecondOfDay], [toMillisecondOfDay], and [toNanosecondOfDay] are the inverse operations. * See sample 2. @@ -106,7 +106,7 @@ public expect class LocalTime : Comparable { * * It is incorrect to pass to this function * the number of seconds that have physically elapsed since the start of the day. - * The reason is that, due to the daylight-saving-time transitions, the number of seconds since the start + * The reason is that, due to daylight-saving-time transitions, the number of seconds since the start * of the day is not a constant value: clocks could be shifted by an hour or more on some dates. * Use [Instant] to perform reliable time arithmetic. * @@ -127,7 +127,7 @@ public expect class LocalTime : Comparable { * * It is incorrect to pass to this function * the number of milliseconds that have physically elapsed since the start of the day. - * The reason is that, due to the daylight-saving-time transitions, the number of milliseconds since the start + * The reason is that, due to daylight-saving-time transitions, the number of milliseconds since the start * of the day is not a constant value: clocks could be shifted by an hour or more on some dates. * Use [Instant] to perform reliable time arithmetic. * @@ -147,7 +147,7 @@ public expect class LocalTime : Comparable { * * It is incorrect to pass to this function * the number of nanoseconds that have physically elapsed since the start of the day. - * The reason is that, due to the daylight-saving-time transitions, the number of nanoseconds since the start + * The reason is that, due to daylight-saving-time transitions, the number of nanoseconds since the start * of the day is not a constant value: clocks could be shifted by an hour or more on some dates. * Use [Instant] to perform reliable time arithmetic. * @@ -262,7 +262,7 @@ public expect class LocalTime : Comparable { * Returns the time as a second of a day, in `0 until 24 * 60 * 60`. * * Note that this is *not* the number of seconds since the start of the day! - * For example, `LocalTime(4, 0).toMillisecondOfDay()` will return `4 * 60 * 60`, the four hours' + * For example, `LocalTime(4, 0).toMillisecondOfDay()` will return `4 * 60 * 60`, the four hours * worth of seconds, but because of DST transitions, when clocks show 4:00, in fact, three, four, five, or * some other number of hours could have passed since the day started. * Use [Instant] to perform reliable time arithmetic. @@ -278,7 +278,7 @@ public expect class LocalTime : Comparable { * Returns the time as a millisecond of a day, in `0 until 24 * 60 * 60 * 1_000`. * * Note that this is *not* the number of milliseconds since the start of the day! - * For example, `LocalTime(4, 0).toMillisecondOfDay()` will return `4 * 60 * 60 * 1_000`, the four hours' + * For example, `LocalTime(4, 0).toMillisecondOfDay()` will return `4 * 60 * 60 * 1_000`, the four hours * worth of milliseconds, but because of DST transitions, when clocks show 4:00, in fact, three, four, five, or * some other number of hours could have passed since the day started. * Use [Instant] to perform reliable time arithmetic. @@ -294,7 +294,7 @@ public expect class LocalTime : Comparable { * Returns the time as a nanosecond of a day, in `0 until 24 * 60 * 60 * 1_000_000_000`. * * Note that this is *not* the number of nanoseconds since the start of the day! - * For example, `LocalTime(4, 0).toMillisecondOfDay()` will return `4 * 60 * 60 * 1_000_000_000`, the four hours' + * For example, `LocalTime(4, 0).toMillisecondOfDay()` will return `4 * 60 * 60 * 1_000_000_000`, the four hours * worth of nanoseconds, but because of DST transitions, when clocks show 4:00, in fact, three, four, five, or * some other number of hours could have passed since the day started. * Use [Instant] to perform reliable time arithmetic. @@ -359,7 +359,7 @@ public fun String.toLocalTime(): LocalTime = LocalTime.parse(this) /** * Combines this time's components with the specified date components into a [LocalDateTime] value. * - * There is no check of whether the time is valid on the specified date, because that depends on a time zone, which + * There is no check of whether the time is valid on the specified date because that depends on the time zone, which * this method does not accept. * * @sample kotlinx.datetime.test.samples.LocalTimeSamples.atDateComponentWiseMonthNumber @@ -370,7 +370,7 @@ public fun LocalTime.atDate(year: Int, monthNumber: Int, dayOfMonth: Int = 0): L /** * Combines this time's components with the specified date components into a [LocalDateTime] value. * - * There is no check of whether the time is valid on the specified date, because that depends on a time zone, which + * There is no check of whether the time is valid on the specified date because that depends on the time zone, which * this method does not accept. * * @sample kotlinx.datetime.test.samples.LocalTimeSamples.atDateComponentWise @@ -381,7 +381,7 @@ public fun LocalTime.atDate(year: Int, month: Month, dayOfMonth: Int = 0): Local /** * Combines this time's components with the specified [LocalDate] components into a [LocalDateTime] value. * - * There is no check of whether the time is valid on the specified date, because that depends on a time zone, which + * There is no check of whether the time is valid on the specified date because that depends on the time zone, which * this method does not accept. * * @sample kotlinx.datetime.test.samples.LocalTimeSamples.atDate diff --git a/core/common/src/TimeZone.kt b/core/common/src/TimeZone.kt index 69b0de71c..6a6943b34 100644 --- a/core/common/src/TimeZone.kt +++ b/core/common/src/TimeZone.kt @@ -105,10 +105,10 @@ public expect open class TimeZone { } /** - * Return the civil date/time value that this instant has in the time zone provided as an implicit receiver. + * Return the civil datetime value that this instant has in the time zone provided as an implicit receiver. * * Note that while this conversion is unambiguous, the inverse ([LocalDateTime.toInstant]) - * is not necessary so. + * is not necessarily so. * * @see LocalDateTime.toInstant * @see Instant.offsetIn @@ -118,15 +118,15 @@ public expect open class TimeZone { public fun Instant.toLocalDateTime(): LocalDateTime /** - * Returns an instant that corresponds to this civil date/time value in the time zone provided as an implicit receiver. + * Returns an instant that corresponds to this civil datetime value in the time zone provided as an implicit receiver. * * Note that the conversion is not always well-defined. There can be the following possible situations: - * - There's only one instant that has this date/time value in the [timeZone]. + * - Only one instant has this datetime value in the [timeZone]. * In this case, the conversion is unambiguous. - * - There's no instant that has this date/time value in the [timeZone]. + * - No instant has this datetime value in the [timeZone]. * Such a situation appears when the time zone experiences a transition from a lesser to a greater offset. * In this case, the conversion is performed with the lesser (earlier) offset, as if the time gap didn't occur yet. - * - There are two possible instants that can have this date/time components in the [timeZone]. + * - Two possible instants can have these datetime components in the [timeZone]. * In this case, the earlier instant is returned. * * @see Instant.toLocalDateTime @@ -176,7 +176,7 @@ public typealias ZoneOffset = FixedOffsetTimeZone /** * Finds the offset from UTC this time zone has at the specified [instant] of physical time. * - * **Pitfall**: the offset returned from this function should typically not be used for datetime arithmetics, + * **Pitfall**: the offset returned from this function should typically not be used for datetime arithmetics * because the offset can change over time due to daylight-saving-time transitions and other reasons. * Use [TimeZone] directly with arithmetic operations instead. * @@ -187,10 +187,10 @@ public typealias ZoneOffset = FixedOffsetTimeZone public expect fun TimeZone.offsetAt(instant: Instant): UtcOffset /** - * Returns a civil date/time value that this instant has in the specified [timeZone]. + * Returns a civil datetime value that this instant has in the specified [timeZone]. * * Note that while this conversion is unambiguous, the inverse ([LocalDateTime.toInstant]) - * is not necessary so. + * is not necessarily so. * * @see LocalDateTime.toInstant * @see Instant.offsetIn @@ -200,9 +200,9 @@ public expect fun TimeZone.offsetAt(instant: Instant): UtcOffset public expect fun Instant.toLocalDateTime(timeZone: TimeZone): LocalDateTime /** - * Returns a civil date/time value that this instant has in the specified [UTC offset][offset]. + * Returns a civil datetime value that this instant has in the specified [UTC offset][offset]. * - * **Pitfall**: it is typically more robust to use [TimeZone] directly, because the offset can change over time due to + * **Pitfall**: it is typically more robust to use [TimeZone] directly because the offset can change over time due to * daylight-saving-time transitions and other reasons, so [this] instant may actually correspond to a different offset * in the implied time zone. * @@ -215,7 +215,7 @@ internal expect fun Instant.toLocalDateTime(offset: UtcOffset): LocalDateTime /** * Finds the offset from UTC the specified [timeZone] has at this instant of physical time. * - * **Pitfall**: the offset returned from this function should typically not be used for datetime arithmetics, + * **Pitfall**: the offset returned from this function should typically not be used for datetime arithmetics * because the offset can change over time due to daylight-saving-time transitions and other reasons. * Use [TimeZone] directly with arithmetic operations instead. * @@ -227,15 +227,15 @@ public fun Instant.offsetIn(timeZone: TimeZone): UtcOffset = timeZone.offsetAt(this) /** - * Returns an instant that corresponds to this civil date/time value in the specified [timeZone]. + * Returns an instant that corresponds to this civil datetime value in the specified [timeZone]. * * Note that the conversion is not always well-defined. There can be the following possible situations: - * - There's only one instant that has this date/time value in the [timeZone]. + * - Only one instant has this datetime value in the [timeZone]. * In this case, the conversion is unambiguous. - * - There's no instant that has this date/time value in the [timeZone]. + * - No instant has this datetime value in the [timeZone]. * Such a situation appears when the time zone experiences a transition from a lesser to a greater offset. * In this case, the conversion is performed with the lesser (earlier) offset, as if the time gap didn't occur yet. - * - There are two possible instants that can have this date/time components in the [timeZone]. + * - Two possible instants can have these datetime components in the [timeZone]. * In this case, the earlier instant is returned. * * @see Instant.toLocalDateTime @@ -244,7 +244,7 @@ public fun Instant.offsetIn(timeZone: TimeZone): UtcOffset = public expect fun LocalDateTime.toInstant(timeZone: TimeZone): Instant /** - * Returns an instant that corresponds to this civil date/time value that happens at the specified [UTC offset][offset]. + * Returns an instant that corresponds to this civil datetime value that happens at the specified [UTC offset][offset]. * * @see Instant.toLocalDateTime * @sample kotlinx.datetime.test.samples.TimeZoneSamples.localDateTimeToInstantInOffset @@ -255,8 +255,8 @@ public expect fun LocalDateTime.toInstant(offset: UtcOffset): Instant * Returns an instant that corresponds to the start of this date in the specified [timeZone]. * * Note that it's not equivalent to `atTime(0, 0).toInstant(timeZone)` - * because a day does not always start at the fixed time 00:00:00. - * For example, if due do daylight saving time, clocks were shifted from 23:30 + * because a day does not always start at a fixed time 00:00:00. + * For example, if, due to daylight saving time, clocks were shifted from 23:30 * of one day directly to 00:30 of the next day, skipping the midnight, then * `atStartOfDayIn` would return the `Instant` corresponding to 00:30, whereas * `atTime(0, 0).toInstant(timeZone)` would return the `Instant` corresponding diff --git a/core/common/src/UtcOffset.kt b/core/common/src/UtcOffset.kt index 5c5bd7fdb..97c5e4103 100644 --- a/core/common/src/UtcOffset.kt +++ b/core/common/src/UtcOffset.kt @@ -21,7 +21,7 @@ import kotlinx.serialization.Serializable * * **Pitfall**: the offset is not a time zone. * It does not contain any information about the time zone's rules, such as daylight-saving-time transitions. - * It is just a fixed offset from UTC, something that may be in effect in a given location today but change + * It is just a fixed offset from UTC, something that may be in effect in a given location today but will change * tomorrow. * Even if the offset is fixed currently, it may change in the future due to political decisions. * @@ -58,7 +58,7 @@ public expect class UtcOffset { /** * The number of seconds from UTC. * - * The larger the value, the earlier some specific civil date/time happens with the offset. + * The larger the value, the earlier some specific civil datetime happens with the offset. */ public val totalSeconds: Int @@ -118,7 +118,7 @@ public expect class UtcOffset { /** * ISO 8601 extended format, which is the format used by [UtcOffset.parse] and [UtcOffset.toString]. * - * An extension of the ISO 8601 is that this format allows parsing and formatting seconds. + * An extension of ISO 8601 that allows parsing and formatting seconds. * * When formatting, seconds are omitted if they are zero. If the whole offset is zero, the letter `Z` is output. * @@ -138,7 +138,7 @@ public expect class UtcOffset { /** * ISO 8601 basic format. * - * An extension of the ISO 8601 is that this format allows parsing and formatting seconds. + * An extension of ISO 8601 that allows parsing and formatting seconds. * * When formatting, seconds are omitted if they are zero. If the whole offset is zero, the letter `Z` is output. * @@ -173,7 +173,7 @@ public expect class UtcOffset { } /** - * Converts this UTC offset to the extended ISO 8601 string representation; for example, `+02:30` or `Z`. + * Converts this UTC offset to the extended ISO 8601 string representation, for example, `+02:30` or `Z`. * * @see Formats.ISO for the format details. * @see parse for the dual operation: obtaining [UtcOffset] from a string. @@ -220,7 +220,7 @@ public fun UtcOffset(): UtcOffset = UtcOffset.ZERO * * **Pitfall**: UTC offsets are static values and do not change with time. * If the logic requires that the offset changes with time, for example, to account for daylight-saving-time - * transitions, use [TimeZone.of] with a IANA time zone name to obtain a time zone that can handle + * transitions, use [TimeZone.of] with an IANA time zone name to obtain a time zone that can handle * changes in the offset. * * @sample kotlinx.datetime.test.samples.UtcOffsetSamples.asFixedOffsetTimeZone diff --git a/core/common/src/format/DateTimeComponents.kt b/core/common/src/format/DateTimeComponents.kt index 5d5fd2b1f..61f833115 100644 --- a/core/common/src/format/DateTimeComponents.kt +++ b/core/common/src/format/DateTimeComponents.kt @@ -14,9 +14,9 @@ import kotlinx.datetime.internal.safeMultiply import kotlin.reflect.* /** - * A collection of date-time fields, used specifically for parsing and formatting. + * A collection of datetime fields used specifically for parsing and formatting. * - * Its main purpose is to provide support for complex date-time formats that don't correspond to any of the standard + * Its main purpose is to support complex datetime formats that don't correspond to any of the standard * entities in the library. For example, a format that includes only the month and the day of the month but not the * year cannot be represented and parsed as a [LocalDate], but it is valid for a [DateTimeComponents]. * See sample 1. @@ -66,8 +66,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date /** * ISO 8601 extended format for dates and times with UTC offset. * - * For specifying the time zone offset, the format uses the [UtcOffset.Formats.ISO] format, except that during - * parsing, specifying the minutes of the offset is optional (so offsets like `+03` are also allowed). + * The format uses the [UtcOffset.Formats.ISO] format to specify the time zone offset, except that + * specifying the minutes of the offset is optional during parsing (so offsets like `+03` are also allowed). * * This format differs from [LocalTime.Formats.ISO] in its time part in that * specifying the seconds is *not* optional. diff --git a/core/common/src/format/DateTimeFormat.kt b/core/common/src/format/DateTimeFormat.kt index 933360535..375c47325 100644 --- a/core/common/src/format/DateTimeFormat.kt +++ b/core/common/src/format/DateTimeFormat.kt @@ -10,7 +10,7 @@ import kotlinx.datetime.internal.format.* import kotlinx.datetime.internal.format.parser.* /** - * A format for parsing and formatting date-time-related values. + * A format for parsing and formatting datetime-related values. * * By convention, predefined formats for each applicable class can be found in the `Formats` object of the class, and * custom formats can be created using the `Format` function in the companion object of that class. diff --git a/core/common/src/format/DateTimeFormatBuilder.kt b/core/common/src/format/DateTimeFormatBuilder.kt index 3c92bfbfd..cd98ef122 100644 --- a/core/common/src/format/DateTimeFormatBuilder.kt +++ b/core/common/src/format/DateTimeFormatBuilder.kt @@ -24,7 +24,7 @@ public sealed interface DateTimeFormatBuilder { public fun chars(value: String) /** - * Functions specific to the date-time format builders containing the local-date fields. + * Functions specific to the datetime format builders containing the local-date fields. */ public sealed interface WithDate : DateTimeFormatBuilder { /** @@ -99,7 +99,7 @@ public sealed interface DateTimeFormatBuilder { } /** - * Functions specific to the date-time format builders containing the local-time fields. + * Functions specific to the datetime format builders containing the local-time fields. */ public sealed interface WithTime : DateTimeFormatBuilder { /** @@ -214,11 +214,11 @@ public sealed interface DateTimeFormatBuilder { } /** - * Functions specific to the date-time format builders containing the local-date and local-time fields. + * Functions specific to the datetime format builders containing the local-date and local-time fields. */ public sealed interface WithDateTime : WithDate, WithTime { /** - * An existing [DateTimeFormat] for the date-time part. + * An existing [DateTimeFormat] for the datetime part. * * @sample kotlinx.datetime.test.samples.format.LocalDateTimeFormatSamples.dateTime */ @@ -226,7 +226,7 @@ public sealed interface DateTimeFormatBuilder { } /** - * Functions specific to the date-time format builders containing the UTC-offset fields. + * Functions specific to the datetime format builders containing the UTC-offset fields. */ public sealed interface WithUtcOffset : DateTimeFormatBuilder { /** @@ -271,7 +271,7 @@ public sealed interface DateTimeFormatBuilder { } /** - * Builder for formats for values that have all the date-time components: + * Builder for formats for values that have all the datetime components: * date, time, UTC offset, and the timezone ID. */ public sealed interface WithDateTimeComponents : WithDateTime, WithUtcOffset { diff --git a/core/common/src/format/LocalDateFormat.kt b/core/common/src/format/LocalDateFormat.kt index c94a24040..2e96fe10c 100644 --- a/core/common/src/format/LocalDateFormat.kt +++ b/core/common/src/format/LocalDateFormat.kt @@ -27,7 +27,7 @@ import kotlinx.datetime.internal.format.parser.Copyable */ public class MonthNames( /** - * A list of month names, in order from January to December. + * A list of month names in order from January to December. * * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.MonthNamesSamples.names */ @@ -58,7 +58,7 @@ public class MonthNames( public companion object { /** - * English month names, 'January' to 'December'. + * English month names from 'January' to 'December'. * * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.MonthNamesSamples.englishFull */ @@ -70,7 +70,7 @@ public class MonthNames( ) /** - * Shortened English month names, 'Jan' to 'Dec'. + * Shortened English month names from 'Jan' to 'Dec'. * * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.MonthNamesSamples.englishAbbreviated */ @@ -114,7 +114,7 @@ private fun MonthNames.toKotlinCode(): String = when (this.names) { */ public class DayOfWeekNames( /** - * A list of day of week names, in order from Monday to Sunday. + * A list of the names of weekdays in order from Monday to Sunday. * * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.DayOfWeekNamesSamples.names */ @@ -133,7 +133,7 @@ public class DayOfWeekNames( } /** - * A constructor that takes the day of week names, in order from Monday to Sunday. + * A constructor that takes the names of weekdays in order from Monday to Sunday. * * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.DayOfWeekNamesSamples.constructionFromStrings */ @@ -150,7 +150,7 @@ public class DayOfWeekNames( public companion object { /** - * English day of week names, 'Monday' to 'Sunday'. + * English names of weekdays from 'Monday' to 'Sunday'. * * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.DayOfWeekNamesSamples.englishFull */ @@ -161,7 +161,7 @@ public class DayOfWeekNames( ) /** - * Shortened English day of week names, 'Mon' to 'Sun'. + * Shortened English names of weekdays from 'Mon' to 'Sun'. * * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.DayOfWeekNamesSamples.englishAbbreviated */ diff --git a/core/common/src/format/Unicode.kt b/core/common/src/format/Unicode.kt index 2a27b4346..573583c5d 100644 --- a/core/common/src/format/Unicode.kt +++ b/core/common/src/format/Unicode.kt @@ -29,7 +29,7 @@ import kotlin.native.concurrent.* public annotation class FormatStringsInDatetimeFormats /** - * Appends a Unicode date/time format string to the [DateTimeFormatBuilder]. + * Appends a Unicode datetime format string to the [DateTimeFormatBuilder]. * * This is the format string syntax used by the Java Time's `DateTimeFormatter` class, Swift's and Objective-C's * `NSDateFormatter` class, and the ICU library. diff --git a/core/native/src/internal/MonthDayTime.kt b/core/native/src/internal/MonthDayTime.kt index e1596e8aa..f079a903d 100644 --- a/core/native/src/internal/MonthDayTime.kt +++ b/core/native/src/internal/MonthDayTime.kt @@ -20,8 +20,8 @@ import kotlinx.datetime.* */ internal interface DateOfYear { /** - * Converts this date-time to an [Instant] in the given [year], - * using the knowledge of the offset that's in effect at the resulting date-time. + * Converts this datetime to an [Instant] in the given [year], + * using the knowledge of the offset that's in effect at the resulting datetime. */ fun toLocalDate(year: Int): LocalDate } @@ -120,14 +120,14 @@ internal class MonthDayTime( */ val time: TransitionLocaltime, /** - * The definition of how the offset in which the local date-time is expressed. + * The definition of how the offset in which the local datetime is expressed. */ val offset: OffsetResolver, ) { /** * Converts this [MonthDayTime] to an [Instant] in the given [year], - * using the knowledge of the offset that's in effect at the resulting date-time. + * using the knowledge of the offset that's in effect at the resulting datetime. */ fun toInstant(year: Int, effectiveOffset: UtcOffset): Instant { val localDateTime = time.resolve(date.toLocalDate(year)) @@ -138,7 +138,7 @@ internal class MonthDayTime( } /** - * Describes how the offset in which the local date-time is expressed is defined. + * Describes how the offset in which the local datetime is expressed is defined. */ sealed interface OffsetResolver { /**