diff --git a/core/src/commonMain/kotlin/io/islandtime/Date.kt b/core/src/commonMain/kotlin/io/islandtime/Date.kt index 2b0a1e3d6..5c3cb661e 100644 --- a/core/src/commonMain/kotlin/io/islandtime/Date.kt +++ b/core/src/commonMain/kotlin/io/islandtime/Date.kt @@ -11,7 +11,7 @@ import io.islandtime.ranges.DateRange /** * A date in an ambiguous region. * - * @constructor Create a [Date] from a year, month, and day of month. + * @constructor Creates a [Date] from a year, month, and day of month. * @param year the year * @param month the month * @param day the day of the month @@ -31,7 +31,7 @@ class Date( } /** - * Create a [Date] from a year, ISO month number, and day of month. + * Creates a [Date] from a year, ISO month number, and day of month. * @param year the year * @param monthNumber the ISO month number, from 1-12 * @param day the day of the month @@ -58,7 +58,7 @@ class Date( val dayOfMonth: Int get() = day /** - * The day of the year -- also known as the ordinal date in ISO-8601. + * The day of the year. */ val dayOfYear: Int get() = month.firstDayOfYearIn(year) + dayOfMonth - 1 @@ -289,24 +289,24 @@ class Date( companion object { /** - * The smallest supported [Date], which can be used as a "far past" sentinel. + * The earliest supported [Date], which can be used as a "far past" sentinel. */ val MIN = Date(Year.MIN_VALUE, Month.JANUARY, 1) /** - * The largest supported [Date], which can be used as a "far future" sentinel. + * The latest supported [Date], which can be used as a "far future" sentinel. */ val MAX = Date(Year.MAX_VALUE, Month.DECEMBER, 31) /** - * Create a [Date] from a duration of days relative to the Unix epoch of 1970-01-01. + * Creates a [Date] from a duration of days relative to the Unix epoch of 1970-01-01. * @param days the number of days relative to the Unix epoch * @throws DateTimeException if outside of the supported date range */ fun fromDaysSinceUnixEpoch(days: LongDays): Date = fromDayOfUnixEpoch(days.value) /** - * Create a [Date] from the day of the Unix epoch. + * Creates a [Date] from the day of the Unix epoch. * @param day the day of the Unix epoch * @throws DateTimeException if outside of the supported date range */ @@ -330,7 +330,7 @@ class Date( } /** - * Create a [Date] from a year and day of year + * Creates a [Date] from a year and day of year * @param year the year * @param dayOfYear the day of the calendar year * @throws DateTimeException if the year or day of year are invalid @@ -347,7 +347,7 @@ fun Date(year: Int, dayOfYear: Int): Date { } /** - * Convert an [Instant] into the [Date] represented by it at a particular UTC offset. + * Converts this instant to the corresponding [Date] at [offset]. */ fun Instant.toDateAt(offset: UtcOffset): Date { val adjustedSeconds = secondOfUnixEpoch + offset.totalSeconds.value @@ -356,20 +356,20 @@ fun Instant.toDateAt(offset: UtcOffset): Date { } /** - * Convert an [Instant] into the [Date] represented by it in a particular time zone. + * Converts this instant to the corresponding [Date] in [zone]. */ fun Instant.toDateAt(zone: TimeZone): Date { return this.toDateAt(zone.rules.offsetAt(this)) } /** - * Combine a [YearMonth] with a day of the month to create a [Date]. + * Combines a [YearMonth] with a day of the month to create a [Date]. * @param day the day of the month */ fun YearMonth.atDay(day: Int) = Date(year, month, day) /** - * Convert a string to a [Date]. + * Converts a string to a [Date]. * * The string is assumed to be an ISO-8601 calendar date in extended format. For example, `2010-10-05`. The output of * [Date.toString] can be safely parsed using this method. @@ -380,7 +380,7 @@ fun YearMonth.atDay(day: Int) = Date(year, month, day) fun String.toDate() = toDate(DateTimeParsers.Iso.Extended.CALENDAR_DATE) /** - * Convert a string to a [Date] using a specific parser. + * Converts a string to a [Date] using a specific parser. * * A set of predefined parsers can be found in [DateTimeParsers]. * diff --git a/core/src/commonMain/kotlin/io/islandtime/DateTime.kt b/core/src/commonMain/kotlin/io/islandtime/DateTime.kt index a7662bd08..15dfdeecd 100644 --- a/core/src/commonMain/kotlin/io/islandtime/DateTime.kt +++ b/core/src/commonMain/kotlin/io/islandtime/DateTime.kt @@ -8,7 +8,7 @@ import io.islandtime.ranges.DateTimeInterval /** * A date and time of day in an ambiguous region. * - * @constructor Create a [DateTime] by combining a [Date] and [Time]. + * @constructor Creates a [DateTime] by combining a [Date] and [Time]. * @param date the date * @param time the time */ @@ -20,7 +20,7 @@ class DateTime( ) : Comparable { /** - * Create a [DateTime]. + * Creates a [DateTime]. * @throws DateTimeException if the date-time is invalid */ constructor( @@ -34,7 +34,7 @@ class DateTime( ) : this(Date(year, month, day), Time(hour, minute, second, nanosecond)) /** - * Create a [DateTime]. + * Creates a [DateTime]. * @throws DateTimeException if the date-time is invalid */ constructor( @@ -48,7 +48,7 @@ class DateTime( ) : this(year, monthNumber.toMonth(), day, hour, minute, second, nanosecond) /** - * Create a [DateTime]. + * Creates a [DateTime]. * @throws DateTimeException if the date-time is invalid */ constructor( @@ -101,7 +101,7 @@ class DateTime( inline val dayOfMonth: Int get() = date.dayOfMonth /** - * The day of the year -- also known as the ordinal date in ISO-8601. + * The day of the year. */ inline val dayOfYear: Int get() = date.dayOfYear @@ -592,17 +592,17 @@ class DateTime( companion object { /** - * The smallest supported [DateTime], which can be used as a "far past" sentinel. + * The earliest supported [DateTime], which can be used as a "far past" sentinel. */ val MIN = DateTime(Date.MIN, Time.MIN) /** - * The largest supported [DateTime], which can be used as a "far future" sentinel. + * The latest supported [DateTime], which can be used as a "far future" sentinel. */ val MAX = DateTime(Date.MAX, Time.MAX) /** - * Create a [DateTime] from a duration of milliseconds relative to the Unix epoch at [offset]. + * Creates a [DateTime] from a duration of milliseconds relative to the Unix epoch at [offset]. */ fun fromMillisecondsSinceUnixEpoch(millisecondsSinceUnixEpoch: LongMilliseconds, offset: UtcOffset): DateTime { val localMilliseconds = millisecondsSinceUnixEpoch + offset.totalSeconds @@ -615,7 +615,7 @@ class DateTime( } /** - * Create a [DateTime] from a duration of seconds relative to the Unix epoch at [offset], optionally, with some + * Creates a [DateTime] from a duration of seconds relative to the Unix epoch at [offset], optionally, with some * number of additional nanoseconds added to it. */ fun fromSecondsSinceUnixEpoch( @@ -635,14 +635,14 @@ class DateTime( } /** - * Create a [DateTime] from the millisecond of the Unix epoch at [offset]. + * Creates a [DateTime] from the millisecond of the Unix epoch at [offset]. */ fun fromMillisecondOfUnixEpoch(millisecond: Long, offset: UtcOffset): DateTime { return fromMillisecondsSinceUnixEpoch(millisecond.milliseconds, offset) } /** - * Create a [DateTime] from the second of the Unix epoch at [offset] and optionally, the nanosecond of the + * Creates a [DateTime] from the second of the Unix epoch at [offset] and optionally, the nanosecond of the * second. */ fun fromSecondOfUnixEpoch(second: Long, nanosecond: Int = 0, offset: UtcOffset): DateTime { @@ -670,12 +670,12 @@ class DateTime( } /** - * Combine a [Date] with a [Time] to create a [DateTime]. + * Combines a [Date] with a [Time] to create a [DateTime]. */ infix fun Date.at(time: Time) = DateTime(this, time) /** - * Combine a [Date] with a time to create a [DateTime]. + * Combines a [Date] with a time to create a [DateTime]. */ fun Date.atTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): DateTime { return DateTime(this, Time(hour, minute, second, nanosecond)) @@ -710,7 +710,7 @@ val Date.endOfDay: DateTime get() = DateTime(this, Time.MAX) fun String.toDateTime() = toDateTime(DateTimeParsers.Iso.Extended.DATE_TIME) /** - * Convert a string to a [DateTime] using a specific parser. + * Converts a string to a [DateTime] using a specific parser. * * A set of predefined parsers can be found in [DateTimeParsers]. * diff --git a/core/src/commonMain/kotlin/io/islandtime/DayOfWeek.kt b/core/src/commonMain/kotlin/io/islandtime/DayOfWeek.kt index 6147b83a5..429bc0e35 100644 --- a/core/src/commonMain/kotlin/io/islandtime/DayOfWeek.kt +++ b/core/src/commonMain/kotlin/io/islandtime/DayOfWeek.kt @@ -71,22 +71,22 @@ enum class DayOfWeek { } /** - * Add days to this day of the week, wrapping when the beginning or end of the week is reached. + * Adds days to this day of the week, wrapping when the beginning or end of the week is reached. */ operator fun plus(days: IntDays) = plus(days.value % DAYS_PER_WEEK) /** - * Add days to this day of the week, wrapping when the beginning or end of the week is reached. + * Adds days to this day of the week, wrapping when the beginning or end of the week is reached. */ operator fun plus(days: LongDays) = plus((days.value % DAYS_PER_WEEK).toInt()) /** - * Subtract days from this day of the week, wrapping when the beginning or end of the week is reached. + * Subtracts days from this day of the week, wrapping when the beginning or end of the week is reached. */ operator fun minus(days: IntDays) = plus(-(days.value % DAYS_PER_WEEK)) /** - * Subtract days from this day of the week, wrapping when the beginning or end of the week is reached. + * Subtracts days from this day of the week, wrapping when the beginning or end of the week is reached. */ operator fun minus(days: LongDays) = plus(-(days.value % DAYS_PER_WEEK).toInt()) @@ -101,7 +101,7 @@ enum class DayOfWeek { } /** - * Convert an ISO day of week number to a [DayOfWeek]. + * Converts an ISO day of week number to a [DayOfWeek]. * * The ISO week starts on Monday (1) and ends on Sunday (7). */ @@ -110,7 +110,7 @@ fun Int.toDayOfWeek(): DayOfWeek { } /** - * Convert a day of week number (1-7) to a [DayOfWeek] according to the week definition provided by [settings]. + * Converts a day of week number (1-7) to a [DayOfWeek] using the week definition provided by [settings]. */ fun Int.toDayOfWeek(settings: WeekSettings): DayOfWeek { return settings.firstDayOfWeek + (checkValidDayOfWeek(this) - 1).days diff --git a/core/src/commonMain/kotlin/io/islandtime/Instant.kt b/core/src/commonMain/kotlin/io/islandtime/Instant.kt index 1257ddf17..892eeb0bb 100644 --- a/core/src/commonMain/kotlin/io/islandtime/Instant.kt +++ b/core/src/commonMain/kotlin/io/islandtime/Instant.kt @@ -204,12 +204,12 @@ class Instant private constructor( private const val MAX_SECOND = 31556889864403199L /** - * The smallest supported [Instant], which can be used as a "far past" sentinel. + * The earliest supported [Instant], which can be used as a "far past" sentinel. */ val MIN = fromSecondOfUnixEpoch(MIN_SECOND) /** - * The largest supported [Instant], which can be used as a "far future" sentinel. + * The latest supported [Instant], which can be used as a "far future" sentinel. */ val MAX = fromSecondOfUnixEpoch(MAX_SECOND, 999_999_999L) @@ -219,21 +219,21 @@ class Instant private constructor( val UNIX_EPOCH = fromSecondOfUnixEpoch(0L) /** - * Create an [Instant] from the second of the Unix epoch. + * Creates an [Instant] from the second of the Unix epoch. */ fun fromSecondOfUnixEpoch(second: Long): Instant { return Instant(second, 0) } /** - * Create an [Instant] from the second of the Unix epoch. + * Creates an [Instant] from the second of the Unix epoch. */ fun fromSecondOfUnixEpoch(second: Long, nanosecond: Int): Instant { return fromSecondOfUnixEpoch(second, nanosecond.toLong()) } /** - * Create an [Instant] from the second of the Unix epoch. + * Creates an [Instant] from the second of the Unix epoch. */ fun fromSecondOfUnixEpoch(second: Long, nanosecond: Long): Instant { val newSecond = second plusExact (nanosecond floorDiv NANOSECONDS_PER_SECOND) @@ -243,7 +243,7 @@ class Instant private constructor( } /** - * Create an [Instant] from the millisecond of the Unix epoch. + * Creates an [Instant] from the millisecond of the Unix epoch. */ fun fromMillisecondOfUnixEpoch(millisecond: Long): Instant { val second = millisecond floorDiv MILLISECONDS_PER_SECOND @@ -290,12 +290,12 @@ class Instant private constructor( } /** - * Create the [Instant] represented by a number of seconds relative to the Unix epoch of 1970-01-01T00:00Z. + * Creates the [Instant] represented by a number of seconds relative to the Unix epoch of 1970-01-01T00:00Z. */ fun Instant(secondsSinceUnixEpoch: LongSeconds) = Instant.fromSecondOfUnixEpoch(secondsSinceUnixEpoch.value) /** - * Create the [Instant] represented by a number of seconds and additional nanoseconds relative to the Unix epoch of + * Creates the [Instant] represented by a number of seconds and additional nanoseconds relative to the Unix epoch of * 1970-01-01T00:00Z. */ fun Instant(secondsSinceUnixEpoch: LongSeconds, nanosecondAdjustment: IntNanoseconds): Instant { @@ -303,7 +303,7 @@ fun Instant(secondsSinceUnixEpoch: LongSeconds, nanosecondAdjustment: IntNanosec } /** - * Create the [Instant] represented by a number of seconds and additional nanoseconds relative to the Unix epoch of + * Creates the [Instant] represented by a number of seconds and additional nanoseconds relative to the Unix epoch of * 1970-01-01T00:00Z. */ fun Instant(secondsSinceUnixEpoch: LongSeconds, nanosecondAdjustment: LongNanoseconds): Instant { @@ -311,14 +311,14 @@ fun Instant(secondsSinceUnixEpoch: LongSeconds, nanosecondAdjustment: LongNanose } /** - * Create the [Instant] represented by a number of milliseconds relative to the Unix epoch of 1970-01-01T00:00Z. + * Creates the [Instant] represented by a number of milliseconds relative to the Unix epoch of 1970-01-01T00:00Z. */ fun Instant(millisecondsSinceUnixEpoch: LongMilliseconds): Instant { return Instant.fromMillisecondOfUnixEpoch(millisecondsSinceUnixEpoch.value) } /** - * Convert a string to an [Instant]. + * Converts a string to an [Instant]. * * The string is assumed to be an ISO-8601 UTC date-time representation in extended format. For example, * `2010-10-05T18:30Z` or `2010-10-05T18:30:00.123456789Z`. The output of [Instant.toString] can be safely parsed @@ -330,7 +330,7 @@ fun Instant(millisecondsSinceUnixEpoch: LongMilliseconds): Instant { fun String.toInstant() = toInstant(DateTimeParsers.Iso.Extended.INSTANT) /** - * Convert a string to an [Instant] using a specific parser. + * Converts a string to an [Instant] using a specific parser. * * A set of predefined parsers can be found in [DateTimeParsers]. * diff --git a/core/src/commonMain/kotlin/io/islandtime/IslandTime.kt b/core/src/commonMain/kotlin/io/islandtime/IslandTime.kt index ceffd9eff..d80f0f6fc 100644 --- a/core/src/commonMain/kotlin/io/islandtime/IslandTime.kt +++ b/core/src/commonMain/kotlin/io/islandtime/IslandTime.kt @@ -36,7 +36,7 @@ object IslandTime { } /** - * Initialize Island Time. + * Initializes Island Time. * * This method should be called prior to any of use of the library, usually during an application's initialization * process. If Island Time is not explicitly initialized, the [PlatformTimeZoneRulesProvider] and all other default @@ -49,7 +49,7 @@ object IslandTime { } /** - * Initialize Island Time with a specific time zone rules provider, leaving all other settings in their default + * Initializes Island Time with a specific time zone rules provider, leaving all other settings in their default * state. * * This method should be called prior to any of use of the library, usually during an application's initialization @@ -64,7 +64,7 @@ object IslandTime { } /** - * Reset Island Time to an uninitialized state. + * Resets Island Time to an uninitialized state. * * This method is intended to be used to clean up custom providers in tests. It shouldn't be necessary to call this * in production. diff --git a/core/src/commonMain/kotlin/io/islandtime/Month.kt b/core/src/commonMain/kotlin/io/islandtime/Month.kt index eb3954def..cde96d7f0 100644 --- a/core/src/commonMain/kotlin/io/islandtime/Month.kt +++ b/core/src/commonMain/kotlin/io/islandtime/Month.kt @@ -65,7 +65,7 @@ enum class Month { /** - * Get the ISO month number, from 1-12. + * The ISO month number, from 1-12. */ val number: Int get() = ordinal + 1 @@ -127,7 +127,7 @@ enum class Month { } /** - * Get the number of days in the month for a particular year. + * Returns the number of days in the month for a particular year. * @param year retrieve the length of the month within this year * @return the number of days in the month */ @@ -139,16 +139,13 @@ enum class Month { } /** - * The last day of the month in a particular year. + * Returns the last day of the month in a particular year. */ fun lastDayIn(year: Int) = lengthIn(year).value /** - * The day of the year that this month's first days falls on. This may vary depending on whether or not the year is - * a leap year. - * - * For example, the first day of [MARCH] will be either 60th or 61st day of the year. - * + * Returns the day of the year that this month's first days falls on. This may vary depending on whether or not the + * year is a leap year. For example, the first day of [MARCH] will be either 60th or 61st day of the year. * @param year retrieve the day of year number within this year * @return the first day of year number */ @@ -157,11 +154,8 @@ enum class Month { } /** - * The day of the year that this month's last day falls on. This may vary depending on whether or not the year is a - * leap year. - * - * For example, the last of [FEBRUARY] will be either 59th or 60th day of the year. - * + * Returns the day of the year that this month's last day falls on. This may vary depending on whether or not the + * year is a leap year. For example, the last of [FEBRUARY] will be either 59th or 60th day of the year. * @param year retrieve the day of year number within this year * @return the last day of year number */ @@ -176,7 +170,7 @@ enum class Month { } /** - * The range of valid days for this month within a given year + * Returns the range of valid days for this month within a given year * @param year retrieve the day range within this year * @return the range of valid days */ @@ -185,22 +179,22 @@ enum class Month { } /** - * Add months to this month, wrapping when the beginning or end of the year is reached. + * Adds months to this month, wrapping when the beginning or end of the year is reached. */ operator fun plus(months: IntMonths) = plus(months.value % 12) /** - * Add months to this month, wrapping when the beginning or end of the year is reached. + * Adds months to this month, wrapping when the beginning or end of the year is reached. */ operator fun plus(months: LongMonths) = plus((months.value % 12).toInt()) /** - * Subtract months from this month, wrapping when the beginning or end of the year is reached. + * Subtracts months from this month, wrapping when the beginning or end of the year is reached. */ operator fun minus(months: IntMonths) = plus(-(months.value % 12)) /** - * Subtract months from this month, wrapping when the beginning or end of the year is reached. + * Subtracts months from this month, wrapping when the beginning or end of the year is reached. */ operator fun minus(months: LongMonths) = plus(-(months.value % 12).toInt()) @@ -215,7 +209,7 @@ enum class Month { } /** - * Convert an ISO month number (from 1-12) to a [Month]. + * Converts an ISO month number, from 1-12, to a [Month]. */ fun Int.toMonth(): Month { if (this !in Month.MIN.number..Month.MAX.number) { diff --git a/core/src/commonMain/kotlin/io/islandtime/OffsetDateTime.kt b/core/src/commonMain/kotlin/io/islandtime/OffsetDateTime.kt index 0b0a2395d..5c2fc31a5 100644 --- a/core/src/commonMain/kotlin/io/islandtime/OffsetDateTime.kt +++ b/core/src/commonMain/kotlin/io/islandtime/OffsetDateTime.kt @@ -12,7 +12,7 @@ import io.islandtime.ranges.OffsetDateTimeInterval * application of time zone rules may be undesirable. For most applications, [ZonedDateTime] is a better choice since * it takes time zone rules into account when performing calendrical calculations. * - * @constructor Create an [OffsetDateTime] by combining a [DateTime] and [UtcOffset]. + * @constructor Creates an [OffsetDateTime] by combining a [DateTime] and [UtcOffset]. * @param dateTime the local date and time of day * @param offset the offset from UTC * @throws DateTimeException if the offset is invalid @@ -29,13 +29,13 @@ class OffsetDateTime( } /** - * Create an [OffsetDateTime]. + * Creates an [OffsetDateTime]. * @throws DateTimeException if the offset is invalid */ constructor(date: Date, time: Time, offset: UtcOffset) : this(DateTime(date, time), offset) /** - * Create an [OffsetDateTime]. + * Creates an [OffsetDateTime]. * @throws DateTimeException if the date-time or offset is invalid */ constructor( @@ -50,7 +50,7 @@ class OffsetDateTime( ) : this(DateTime(year, month, dayOfMonth, hour, minute, second, nanosecond), offset) /** - * Create an [OffsetDateTime]. + * Creates an [OffsetDateTime]. * @throws DateTimeException if the date-time or offset is invalid */ constructor( @@ -65,7 +65,7 @@ class OffsetDateTime( ) : this(DateTime(year, monthNumber.toMonth(), dayOfMonth, hour, minute, second, nanosecond), offset) /** - * Create an [OffsetDateTime]. + * Creates an [OffsetDateTime]. * @throws DateTimeException if the date-time or offset is invalid */ constructor( @@ -129,7 +129,7 @@ class OffsetDateTime( inline val dayOfMonth: Int get() = dateTime.dayOfMonth /** - * The day of the year -- also known as the ordinal date in ISO-8601. + * The day of the year. */ inline val dayOfYear: Int get() = dateTime.dayOfYear @@ -189,7 +189,7 @@ class OffsetDateTime( get() = dateTime.millisecondsSinceUnixEpochAt(offset) /** - * Changes the offset of an [OffsetDateTime], adjusting the date and time components such that the instant + * Changes the offset of this [OffsetDateTime], adjusting the date and time components such that the instant * represented by it remains the same. */ fun adjustedTo(newOffset: UtcOffset): OffsetDateTime { @@ -335,12 +335,12 @@ class OffsetDateTime( companion object { /** - * The smallest supported [OffsetDateTime], which can be used as a "far past" sentinel. + * The earliest supported [OffsetDateTime], which can be used as a "far past" sentinel. */ val MIN = DateTime.MIN at UtcOffset.MAX /** - * The largest supported [OffsetDateTime], which can be used as a "far future" sentinel. + * The latest supported [OffsetDateTime], which can be used as a "far future" sentinel. */ val MAX = DateTime.MAX at UtcOffset.MIN @@ -357,14 +357,14 @@ class OffsetDateTime( val TIMELINE_ORDER get() = TimePoint.TIMELINE_ORDER /** - * Create an [OffsetDateTime] from a duration of milliseconds relative to the Unix epoch at [offset]. + * Creates an [OffsetDateTime] from a duration of milliseconds relative to the Unix epoch at [offset]. */ fun fromMillisecondsSinceUnixEpoch(milliseconds: LongMilliseconds, offset: UtcOffset): OffsetDateTime { return OffsetDateTime(DateTime.fromMillisecondsSinceUnixEpoch(milliseconds, offset), offset) } /** - * Create an [OffsetDateTime] from a duration of seconds relative to the Unix epoch at [offset], optionally, + * Creates an [OffsetDateTime] from a duration of seconds relative to the Unix epoch at [offset], optionally, * with some number of additional nanoseconds added to it. */ fun fromSecondsSinceUnixEpoch( @@ -376,14 +376,14 @@ class OffsetDateTime( } /** - * Create an [OffsetDateTime] from the millisecond of the Unix epoch at [offset]. + * Creates an [OffsetDateTime] from the millisecond of the Unix epoch at [offset]. */ fun fromMillisecondOfUnixEpoch(millisecond: Long, offset: UtcOffset): OffsetDateTime { return OffsetDateTime(DateTime.fromMillisecondOfUnixEpoch(millisecond, offset), offset) } /** - * Create an [OffsetDateTime] from the second of the Unix epoch at [offset] and optionally, the nanosecond of + * Creates an [OffsetDateTime] from the second of the Unix epoch at [offset] and optionally, the nanosecond of * the second. */ fun fromSecondOfUnixEpoch(second: Long, nanosecond: Int = 0, offset: UtcOffset): OffsetDateTime { @@ -411,17 +411,17 @@ class OffsetDateTime( } /** - * Combine a local date and time with a UTC offset to create an [OffsetDateTime]. + * Combines a local date and time with a UTC offset to create an [OffsetDateTime]. */ infix fun DateTime.at(offset: UtcOffset) = OffsetDateTime(this, offset) /** - * Combine a local date with a time and UTC offset to create an [OffsetDateTime]. + * Combines a local date with a time and UTC offset to create an [OffsetDateTime]. */ infix fun Date.at(offsetTime: OffsetTime) = OffsetDateTime(this, offsetTime.time, offsetTime.offset) /** - * Combine an instant with a UTC offset to create an [OffsetDateTime]. + * Combines an instant with a UTC offset to create an [OffsetDateTime]. */ infix fun Instant.at(offset: UtcOffset) = OffsetDateTime(this.toDateTimeAt(offset), offset) @@ -433,7 +433,7 @@ infix fun Instant.at(offset: UtcOffset) = OffsetDateTime(this.toDateTimeAt(offse fun ZonedDateTime.asOffsetDateTime() = toOffsetDateTime() /** - * Convert a string to an [OffsetDateTime]. + * Converts a string to an [OffsetDateTime]. * * The string is assumed to be an ISO-8601 date-time with the UTC offset in extended format. For example, * `2019-05-30T02:30+01:00`. The output of [OffsetDateTime.toString] can be safely parsed using this method. @@ -444,7 +444,7 @@ fun ZonedDateTime.asOffsetDateTime() = toOffsetDateTime() fun String.toOffsetDateTime() = toOffsetDateTime(DateTimeParsers.Iso.Extended.OFFSET_DATE_TIME) /** - * Convert a string to an [OffsetDateTime] using a specific parser. + * Converts a string to an [OffsetDateTime] using a specific parser. * * A set of predefined parsers can be found in [DateTimeParsers]. * diff --git a/core/src/commonMain/kotlin/io/islandtime/OffsetTime.kt b/core/src/commonMain/kotlin/io/islandtime/OffsetTime.kt index 144b4aa5d..acd099bfe 100644 --- a/core/src/commonMain/kotlin/io/islandtime/OffsetTime.kt +++ b/core/src/commonMain/kotlin/io/islandtime/OffsetTime.kt @@ -5,6 +5,8 @@ import io.islandtime.parser.* /** * A time of day with an offset from UTC. + * @constructor Creates an [OffsetTime] by combining a [Time] and [UtcOffset]. + * @throws DateTimeException if the offset is invalid */ class OffsetTime( /** The time of day. */ @@ -18,7 +20,7 @@ class OffsetTime( } /** - * Create an [OffsetTime]. + * Creates an [OffsetTime]. * @throws DateTimeException if the time or offset is invalid */ constructor( @@ -57,7 +59,7 @@ class OffsetTime( get() = (time.nanosecondsSinceStartOfDay.value - offset.totalSeconds.inNanoseconds.value).nanoseconds /** - * Return an [OffsetTime] with the offset changed to [newOffset], adjusting the time component such that the instant + * Changes the offset of this [OffsetTime], adjusting the time component such that the instant represented by it * remains the same. */ fun adjustedTo(newOffset: UtcOffset): OffsetTime { @@ -98,7 +100,7 @@ class OffsetTime( operator fun minus(nanoseconds: IntNanoseconds) = copy(time = time - nanoseconds) /** - * Compare to another [OffsetTime] based on timeline order, ignoring offset differences. + * Compares to another [OffsetTime] based on timeline order, ignoring offset differences. * @see DEFAULT_SORT_ORDER * @see TIMELINE_ORDER */ @@ -156,25 +158,25 @@ class OffsetTime( val MAX = Time.MAX at UtcOffset.MIN /** - * Compare by UTC equivalent instant, then time. Using this `Comparator` guarantees a deterministic order when + * Compares by UTC equivalent instant, then time. Using this `Comparator` guarantees a deterministic order when * sorting. */ val DEFAULT_SORT_ORDER = compareBy { it.nanosecondsSinceStartOfUtcDay }.thenBy { it.time } /** - * Compare by timeline order only, ignoring any offset differences. + * Compares by timeline order only, ignoring any offset differences. */ val TIMELINE_ORDER = compareBy { it.nanosecondsSinceStartOfUtcDay } } } /** - * Combine a local time with a UTC offset to create an [OffsetTime]. + * Combines a local time with a UTC offset to create an [OffsetTime]. */ infix fun Time.at(offset: UtcOffset) = OffsetTime(this, offset) /** - * Convert a string to an [OffsetTime]. + * Converts a string to an [OffsetTime]. * * The string is assumed to be an ISO-8601 time with the UTC offset in extended format. For example, `02:30+01:00` or * `14:40:23Z`. The output of [OffsetTime.toString] can be safely parsed using this method. @@ -185,7 +187,7 @@ infix fun Time.at(offset: UtcOffset) = OffsetTime(this, offset) fun String.toOffsetTime() = toOffsetTime(DateTimeParsers.Iso.Extended.OFFSET_TIME) /** - * Convert a string to an [OffsetTime] using a specific parser. + * Converts a string to an [OffsetTime] using a specific parser. * * A set of predefined parsers can be found in [DateTimeParsers]. * diff --git a/core/src/commonMain/kotlin/io/islandtime/Time.kt b/core/src/commonMain/kotlin/io/islandtime/Time.kt index 427526da0..d9075acf5 100644 --- a/core/src/commonMain/kotlin/io/islandtime/Time.kt +++ b/core/src/commonMain/kotlin/io/islandtime/Time.kt @@ -8,7 +8,7 @@ import io.islandtime.parser.* /** * A time of day in an ambiguous region. * - * @constructor Create a [Time] from its individual components. + * @constructor Creates a [Time] from its individual components. * @param hour the hour of day * @param minute the minute of the hour * @param second the second of the minute @@ -249,7 +249,7 @@ class Time( val NOON = Time(12, 0) /** - * Create a [Time] from the second of the day and optionally, the number of nanoseconds within that second. + * Creates a [Time] from the second of the day and optionally, the number of nanoseconds within that second. * * @param secondOfDay the second of the day * @param nanosecond the nanosecond of the second, from 0 - 999,999,999 @@ -261,7 +261,7 @@ class Time( } /** - * Create the [Time] at a number of seconds since the start of the day and optionally, a number of additional + * Creates the [Time] at a number of seconds since the start of the day and optionally, a number of additional * nanoseconds. * * @param seconds the number of seconds since the start of the day @@ -283,7 +283,7 @@ class Time( } /** - * Create a [Time] from the nanosecond of the day. + * Creates a [Time] from the nanosecond of the day. * * @param nanosecondOfDay the nanosecond of the day * @return a new [Time] @@ -302,7 +302,7 @@ class Time( } /** - * Create the [Time] at a number of nanoseconds since the start of the day. + * Creates the [Time] at a number of nanoseconds since the start of the day. * * @param nanoseconds the number of nanoseconds since the start of the day * @return a new [Time] @@ -315,7 +315,7 @@ class Time( } /** - * Convert a string to a [Time]. + * Converts a string to a [Time]. * * The string is assumed to be an ISO-8601 time representation in extended format. For example, `05`, `05:30`, * `05:30:00`, or `05:30:00.123456789`. The output of [Time.toString] can be safely parsed using this method. @@ -326,7 +326,7 @@ class Time( fun String.toTime() = toTime(DateTimeParsers.Iso.Extended.TIME) /** - * Convert a string to a [Time] using a specific parser. + * Converts a string to a [Time] using a specific parser. * * A set of predefined parsers can be found in [DateTimeParsers]. * diff --git a/core/src/commonMain/kotlin/io/islandtime/TimeZone.kt b/core/src/commonMain/kotlin/io/islandtime/TimeZone.kt index 591eabcbf..c1d3709bd 100644 --- a/core/src/commonMain/kotlin/io/islandtime/TimeZone.kt +++ b/core/src/commonMain/kotlin/io/islandtime/TimeZone.kt @@ -26,18 +26,18 @@ sealed class TimeZone : Comparable { abstract val id: String /** - * Check if this is a valid time zone according to the current time zone rules provider. + * Checks if this is a valid time zone according to the current time zone rules provider. */ abstract val isValid: Boolean /** - * Get the rules associated with this time zone. + * The rules associated with this time zone. * @throws TimeZoneRulesException if the current time zone rules provider doesn't support [id] */ abstract val rules: TimeZoneRules /** - * Check if the time zone is valid and throw an exception if it isn't. + * Checks if this time zone is valid and throws an exception if it isn't. * * @throws TimeZoneRulesException if the current time zone rules provider doesn't support [id] * @see isValid @@ -49,15 +49,14 @@ sealed class TimeZone : Comparable { } /** - * Ensure that the time zone is valid, throwing an exception if it isn't. - * + * Ensures that this time zone is valid, throwing an exception if it isn't. * @throws TimeZoneRulesException if the current time zone rules provider doesn't support [id] * @see isValid */ fun validated(): TimeZone = apply { validate() } /** - * The localized name of the time zone, if available for the locale in the specified style. The result depends on + * The localized name of this time zone, if available for the locale in the specified style. The result depends on * the configured [TimeZoneTextProvider] and may differ between platforms. * * Example output for the "America/New_York" ID and "en-US" locale: @@ -75,8 +74,8 @@ sealed class TimeZone : Comparable { } /** - * A textual representation of the time zone, suitable for display purposes. The localized name will be returned, if - * available for the locale in the specified style. If not, the [id] will be returned instead. + * A textual representation of this time zone, suitable for display purposes. The localized name will be returned, + * if available for the locale in the specified style. If not, the [id] will be returned instead. * * The result depends on the configured [TimeZoneTextProvider] and may differ between platforms. * @@ -96,10 +95,7 @@ sealed class TimeZone : Comparable { } /** - * Get a normalized time zone. - * - * Any time zone with a fixed offset will be converted to use a consistent identifier. - * + * Returns a normalized time zone, converting any zone with a fixed offset to use a consistent identifier. * @throws TimeZoneRulesException if the current time zone rules provider doesn't support [id] */ abstract fun normalized(): TimeZone @@ -180,12 +176,12 @@ sealed class TimeZone : Comparable { val UTC: TimeZone = FixedOffset(UtcOffset.ZERO) /** - * Get the system's current [TimeZone]. + * Returns the system's current [TimeZone]. */ fun systemDefault(): TimeZone = systemDefaultTimeZone() /** - * Create a fixed-offset [TimeZone] from an identifier in the form of `+01:00`. + * Creates a fixed-offset [TimeZone] from an identifier in the form of `+01:00`. */ fun FixedOffset(id: String): FixedOffset { return try { @@ -198,7 +194,7 @@ sealed class TimeZone : Comparable { } /** - * Create a [TimeZone] from an identifier. + * Creates a [TimeZone] from an identifier. */ fun TimeZone(id: String): TimeZone { return when { diff --git a/core/src/commonMain/kotlin/io/islandtime/UtcOffset.kt b/core/src/commonMain/kotlin/io/islandtime/UtcOffset.kt index 802754b68..7f5209143 100644 --- a/core/src/commonMain/kotlin/io/islandtime/UtcOffset.kt +++ b/core/src/commonMain/kotlin/io/islandtime/UtcOffset.kt @@ -22,17 +22,17 @@ import kotlin.math.sign inline class UtcOffset(val totalSeconds: IntSeconds) : Comparable { /** - * Check if this offset is within the supported range. + * Checks if this offset is within the supported range. */ val isValid: Boolean get() = totalSeconds in MIN_TOTAL_SECONDS..MAX_TOTAL_SECONDS /** - * Is this the UTC offset of +00:00? + * Checks if this is the UTC offset of +00:00. */ fun isZero(): Boolean = this == ZERO /** - * Break a UTC offset down into components. The sign will indicate whether the offset is positive or negative while + * Breaks a UTC offset down into components. The sign will indicate whether the offset is positive or negative while * each component will be positive. */ inline fun toComponents( @@ -44,7 +44,7 @@ inline class UtcOffset(val totalSeconds: IntSeconds) : Comparable { } /** - * Break a UTC offset down into components. If the offset is negative, each component will be negative. + * Breaks a UTC offset down into components. If the offset is negative, each component will be negative. */ inline fun toComponents( action: (hours: IntHours, minutes: IntMinutes, seconds: IntSeconds) -> T @@ -67,7 +67,7 @@ inline class UtcOffset(val totalSeconds: IntSeconds) : Comparable { } /** - * Check if the offset is valid and throw an exception if it isn't. + * Checks if the offset is valid and throws an exception if it isn't. * @throws DateTimeException if the offset is outside the supported range * @see isValid */ @@ -78,7 +78,7 @@ inline class UtcOffset(val totalSeconds: IntSeconds) : Comparable { } /** - * Ensure that the offset is valid, throwing an exception if it isn't. + * Ensures that the offset is valid, throwing an exception if it isn't. * @throws DateTimeException if the offset is outside the supported range * @see isValid */ @@ -95,7 +95,7 @@ inline class UtcOffset(val totalSeconds: IntSeconds) : Comparable { } /** - * Create a UTC offset of hours, minutes, and seconds. Each component must be within its valid range and without any + * Creates a UTC offset of hours, minutes, and seconds. Each component must be within its valid range and without any * mixed positive and negative values. * @param hours hours to offset by, within +/-18 * @param minutes minutes to offset by, within +/-59 @@ -130,7 +130,7 @@ fun IntMinutes.asUtcOffset() = UtcOffset(this.inSeconds) fun IntSeconds.asUtcOffset() = UtcOffset(this) /** - * Convert a string to a [UtcOffset]. + * Converts a string to a [UtcOffset]. * * The string is assumed to be an ISO-8601 UTC offset representation in extended format. For example, `Z`, `+05`, or * `-04:30`. The output of [UtcOffset.toString] can be safely parsed using this method. @@ -141,7 +141,7 @@ fun IntSeconds.asUtcOffset() = UtcOffset(this) fun String.toUtcOffset() = toUtcOffset(DateTimeParsers.Iso.Extended.UTC_OFFSET) /** - * Convert a string to a [UtcOffset] using a specific parser. + * Converts a string to a [UtcOffset] using a specific parser. * * A set of predefined parsers can be found in [DateTimeParsers]. * @@ -157,7 +157,7 @@ fun String.toUtcOffset( } /** - * Resolve a parser result into a [UtcOffset]. + * Resolves a parser result into a [UtcOffset]. * * Required fields are [DateTimeField.UTC_OFFSET_TOTAL_SECONDS] or [DateTimeField.UTC_OFFSET_SIGN] in conjunction with * any combination of [DateTimeField.UTC_OFFSET_HOURS], [DateTimeField.UTC_OFFSET_MINUTES], and diff --git a/core/src/commonMain/kotlin/io/islandtime/Year.kt b/core/src/commonMain/kotlin/io/islandtime/Year.kt index c97e41d33..42899fd31 100644 --- a/core/src/commonMain/kotlin/io/islandtime/Year.kt +++ b/core/src/commonMain/kotlin/io/islandtime/Year.kt @@ -7,15 +7,21 @@ import io.islandtime.parser.* import io.islandtime.ranges.DateRange import kotlin.math.absoluteValue +/** + * A year as defined by ISO-8601. + * @constructor Creates a [Year]. + * @param value the year + * @property value The year value. + */ inline class Year(val value: Int) : Comparable { /** - * Is this year within the supported range? + * Checks if this year is within the supported range. */ val isValid: Boolean get() = value in MIN_VALUE..MAX_VALUE /** - * Is this a leap year? + * Checks if this is a leap year. */ val isLeap: Boolean get() = value % 4 == 0 && (value % 100 != 0 || value % 400 == 0) @@ -72,6 +78,11 @@ inline class Year(val value: Int) : Comparable { operator fun contains(yearMonth: YearMonth) = yearMonth.year == value operator fun contains(date: Date) = date.year == value + /** + * Ensures that this year is valid, throwing an exception if it isn't. + * @throws DateTimeException if the year is invalid + * @see isValid + */ fun validated(): Year { if (!isValid) { throw DateTimeException(getInvalidYearMessage(value.toLong())) @@ -99,16 +110,30 @@ inline class Year(val value: Int) : Comparable { } companion object { + /** + * The earliest supported year value. + */ const val MIN_VALUE = -999_999_999 + + /** + * The latest supported year value. + */ const val MAX_VALUE = 999_999_999 + /** + * The earliest supported [Year], which can be used as a "far past" sentinel. + */ val MIN = Year(MIN_VALUE) + + /** + * The latest supported [Year], which can be used as a "far future" sentinel. + */ val MAX = Year(MAX_VALUE) } } /** - * Convert a string to a [Year]. + * Converts a string to a [Year]. * * The string is assumed to be an ISO-8601 year. For example, `2010`, `+002010`, or 'Y12345'. The output of * [Year.toString] can be safely parsed using this method. @@ -119,7 +144,7 @@ inline class Year(val value: Int) : Comparable { fun String.toYear() = toYear(DateTimeParsers.Iso.YEAR) /** - * Convert a string to a [Year] using a specific parser. + * Converts a string to a [Year] using a specific parser. * * A set of predefined parsers can be found in [DateTimeParsers]. * diff --git a/core/src/commonMain/kotlin/io/islandtime/YearMonth.kt b/core/src/commonMain/kotlin/io/islandtime/YearMonth.kt index 21d608644..8a4ad9810 100644 --- a/core/src/commonMain/kotlin/io/islandtime/YearMonth.kt +++ b/core/src/commonMain/kotlin/io/islandtime/YearMonth.kt @@ -9,7 +9,7 @@ import io.islandtime.ranges.DateRange /** * A month in a particular year. * - * @constructor Create a [YearMonth]. + * @constructor Creates a [YearMonth]. * @param year the year * @param month the month of the year * @throws DateTimeException if the year is outside the supported range @@ -26,7 +26,7 @@ class YearMonth( } /** - * Create a [YearMonth]. + * Creates a [YearMonth]. * @throws DateTimeException if the year or month is invalid */ constructor(year: Int, monthNumber: Int) : this(year, monthNumber.toMonth()) @@ -37,7 +37,7 @@ class YearMonth( inline val monthNumber: Int get() = month.number /** - * Check if this year-month falls within a leap year. + * Checks if this year-month falls within a leap year. */ val isInLeapYear: Boolean get() = isLeapYear(year) diff --git a/core/src/commonMain/kotlin/io/islandtime/ZonedDateTime.kt b/core/src/commonMain/kotlin/io/islandtime/ZonedDateTime.kt index 73b93d756..edea52f9b 100644 --- a/core/src/commonMain/kotlin/io/islandtime/ZonedDateTime.kt +++ b/core/src/commonMain/kotlin/io/islandtime/ZonedDateTime.kt @@ -72,7 +72,7 @@ class ZonedDateTime private constructor( inline val dayOfMonth: Int get() = dateTime.dayOfMonth /** - * The day of the year -- also known as the ordinal date in ISO-8601. + * The day of the year. */ inline val dayOfYear: Int get() = dateTime.dayOfYear @@ -413,7 +413,7 @@ class ZonedDateTime private constructor( companion object { /** - * Compare by instant, then date-time, then time zone. Using this `Comparator` guarantees a deterministic order + * Compares by instant, then date-time, then time zone. Using this `Comparator` guarantees a deterministic order * when sorting. */ val DEFAULT_SORT_ORDER = compareBy { it.secondOfUnixEpoch } @@ -422,12 +422,12 @@ class ZonedDateTime private constructor( .thenBy { it.zone } /** - * Compare by timeline order only, ignoring any offset or time zone differences. + * Compares by timeline order only, ignoring any offset or time zone differences. */ val TIMELINE_ORDER get() = TimePoint.TIMELINE_ORDER /** - * Create a [ZonedDateTime] from a local date and time, optionally using a preferred offset. If the local date + * Creates a [ZonedDateTime] from a local date and time, optionally using a preferred offset. If the local date * and time fall during an overlap, [preferredOffset] will be used if it represents one of the two valid * offsets. If it is `null` or invalid, it will be ignored. */ @@ -458,7 +458,7 @@ class ZonedDateTime private constructor( } /** - * Create a [ZonedDateTime] from the instant represented by a local date-time and offset. The resulting + * Creates a [ZonedDateTime] from the instant represented by a local date-time and offset. The resulting * `ZonedDateTime` may have a different date-time and offset depending on the time zone rules, but the instant * will be the same. */ @@ -467,7 +467,7 @@ class ZonedDateTime private constructor( } /** - * Create a [ZonedDateTime] from a duration of milliseconds relative to the Unix epoch at [zone]. + * Creates a [ZonedDateTime] from a duration of milliseconds relative to the Unix epoch at [zone]. */ fun fromMillisecondsSinceUnixEpoch(milliseconds: LongMilliseconds, zone: TimeZone): ZonedDateTime { val offset = zone.rules.offsetAt(milliseconds) @@ -476,7 +476,7 @@ class ZonedDateTime private constructor( } /** - * Create a [ZonedDateTime] from a duration of seconds relative to the Unix epoch at [zone], optionally, + * Creates a [ZonedDateTime] from a duration of seconds relative to the Unix epoch at [zone], optionally, * with some number of additional nanoseconds added to it. */ fun fromSecondsSinceUnixEpoch( @@ -490,14 +490,14 @@ class ZonedDateTime private constructor( } /** - * Create a [ZonedDateTime] from the millisecond of the Unix epoch at [zone]. + * Creates a [ZonedDateTime] from the millisecond of the Unix epoch at [zone]. */ fun fromMillisecondOfUnixEpoch(millisecond: Long, zone: TimeZone): ZonedDateTime { return fromMillisecondsSinceUnixEpoch(millisecond.milliseconds, zone) } /** - * Create a [ZonedDateTime] from the second of the Unix epoch at [zone]. + * Creates a [ZonedDateTime] from the second of the Unix epoch at [zone]. */ fun fromSecondOfUnixEpoch(second: Long, nanosecond: Int = 0, zone: TimeZone): ZonedDateTime { return fromSecondsSinceUnixEpoch(second.seconds, nanosecond.nanoseconds, zone) @@ -522,7 +522,7 @@ class ZonedDateTime private constructor( } /** - * Create a [ZonedDateTime] with no additional validation. + * Creates a [ZonedDateTime] with no additional validation. */ internal fun create(dateTime: DateTime, offset: UtcOffset, zone: TimeZone): ZonedDateTime { return ZonedDateTime(dateTime, offset, zone) @@ -531,7 +531,7 @@ class ZonedDateTime private constructor( } /** - * Create a [ZonedDateTime] from a local date and time. + * Creates a [ZonedDateTime] from a local date and time. * * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap @@ -549,7 +549,7 @@ fun ZonedDateTime( ) = ZonedDateTime.fromLocal(DateTime(year, month, day, hour, minute, second, nanosecond), zone) /** - * Create a [ZonedDateTime] from a local date and time. + * Creates a [ZonedDateTime] from a local date and time. * * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap @@ -567,7 +567,7 @@ fun ZonedDateTime( ) = ZonedDateTime.fromLocal(DateTime(year, monthNumber, day, hour, minute, second, nanosecond), zone) /** - * Create a [ZonedDateTime] from a local date and time. + * Creates a [ZonedDateTime] from a local date and time. * * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap @@ -584,7 +584,7 @@ fun ZonedDateTime( ) = ZonedDateTime.fromLocal(DateTime(year, dayOfYear, hour, minute, second, nanosecond), zone) /** - * Create a [ZonedDateTime] from a local date and time. + * Creates a [ZonedDateTime] from a local date and time. * * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap @@ -593,7 +593,7 @@ fun ZonedDateTime( fun ZonedDateTime(date: Date, time: Time, zone: TimeZone) = ZonedDateTime.fromLocal(DateTime(date, time), zone) /** - * Create a [ZonedDateTime] from a local date and time. + * Creates a [ZonedDateTime] from a local date and time. * * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap @@ -602,12 +602,12 @@ fun ZonedDateTime(date: Date, time: Time, zone: TimeZone) = ZonedDateTime.fromLo fun ZonedDateTime(dateTime: DateTime, zone: TimeZone) = ZonedDateTime.fromLocal(dateTime, zone) /** - * Combine an instant with a time zone to create a [ZonedDateTime]. + * Combines an instant with a time zone to create a [ZonedDateTime]. */ infix fun Instant.at(zone: TimeZone) = ZonedDateTime.fromSecondOfUnixEpoch(secondOfUnixEpoch, nanosecond, zone) /** - * Combine a local date and time with a time zone to create a [ZonedDateTime]. + * Combines a local date and time with a time zone to create a [ZonedDateTime]. * * Due to daylight savings time transitions, there a few complexities to be aware of. If the local time falls within a * gap (meaning it doesn't exist), it will be adjusted forward by the length of the gap. If it falls within an overlap @@ -713,7 +713,7 @@ fun OffsetDateTime.asZonedDateTime(): ZonedDateTime { } /** - * Convert a string to a [ZonedDateTime]. + * Converts a string to a [ZonedDateTime]. * * The string is assumed to be a complete ISO-8601 date and time representation in extended format, optionally including * a non-standard region ID. For example, `2005-05-06T23:30+01` or `2005-05-06T23:30-04:00[America/New_York]`. @@ -726,7 +726,7 @@ fun OffsetDateTime.asZonedDateTime(): ZonedDateTime { fun String.toZonedDateTime() = toZonedDateTime(DateTimeParsers.Iso.Extended.ZONED_DATE_TIME) /** - * Convert a string to a [ZonedDateTime] using a specific parser. + * Converts a string to a [ZonedDateTime] using a specific parser. * * A set of predefined parsers can be found in [DateTimeParsers]. *