Package io.islandtime.ranges

Date ranges, time intervals, and the ability to iterate over them and perform various operations.

Types

DateDayProgression

common

abstract class DateDayProgression : Iterable<Date>

DateMonthProgression

common

class DateMonthProgression : Iterable<Date>

DateRange

common

An inclusive range of dates.

Date.MIN and Date.MAX are used as sentinels to indicate an unbounded (ie. infinite) start or end.

class DateRange(start: Date,endInclusive: Date) : DateDayProgression, Interval<Date> , ClosedRange<Date>

DateTimeInterval

common

An interval between two date-times, assumed to be at the same offset from UTC.

DateTime.MIN and DateTime.MAX are used as sentinels to indicate an unbounded (ie. infinite) start or end.

class DateTimeInterval(start: DateTime,endExclusive: DateTime) : Interval<DateTime>

InstantInterval

common

A half-open interval between two instants.

Instant.MIN and Instant.MAX are used as sentinels to indicate an unbounded (ie. infinite) start or end.

class InstantInterval(start: Instant,endExclusive: Instant) : TimePointInterval<Instant> , TimePointProgressionBuilder<Instant>

Interval

common

A half-open or closed interval.

interface Interval<T>

OffsetDateTimeInterval

common

A half-open interval between two offset date-times based on timeline order.

DateTime.MIN and DateTime.MAX are used as sentinels to indicate an unbounded (ie. infinite) start or end. An OffsetDateTime with either as the date-time component will be treated accordingly, regardless of the offset.

class OffsetDateTimeInterval(start: OffsetDateTime,endExclusive: OffsetDateTime) : TimePointInterval<OffsetDateTime>

TimePointInterval

common

A half-open interval of time points.

abstract class TimePointInterval<T : TimePoint<T>> : Interval<T>

TimePointNanosecondProgression

common

class TimePointNanosecondProgression<T : TimePoint<T>> : TimePointProgressionBuilder<T> , Iterable<T>

TimePointProgressionBuilder

common

A time point progression builder.

Without a step, a time-based progression can't be created. This interface represents an intermediate state in the process of creating a time point progression.

interface TimePointProgressionBuilder<T : TimePoint<T>>

TimePointSecondProgression

common

class TimePointSecondProgression<T : TimePoint<T>> : TimePointProgressionBuilder<T> , Iterable<T>

ZonedDateTimeInterval

common

A half-open interval of zoned date-times based on timeline order.

DateTime.MIN and DateTime.MAX are used as sentinels to indicate an unbounded (ie. infinite) start or end. A ZonedDateTime with either as the date-time component will be treated accordingly, regardless of the offset or time zone.

class ZonedDateTimeInterval(start: ZonedDateTime,endExclusive: ZonedDateTime) : TimePointInterval<ZonedDateTime>

Functions

asZonedDateTimeInterval

common

Converts this interval to an equivalent ZonedDateTimeInterval where both endpoints are given a fixed-offset time zone.

This comes with the caveat that a fixed-offset zone lacks knowledge of any region and will not respond to daylight savings time changes. To convert each endpoint to a region-based zone, use toZonedDateTimeInterval instead.

fun OffsetDateTimeInterval.asZonedDateTimeInterval(): ZonedDateTimeInterval

common

Combines this DateRange with a TimeZone to create a ZonedDateTimeInterval between the start of the first day and the end of the last day in zone.

infix fun DateRange.at(zone: TimeZone): ZonedDateTimeInterval

Combines this DateTimeInterval with a TimeZone to create a ZonedDateTimeInterval where both endpoints are in zone.

Due to daylight savings time transitions, there a few complexities to be aware of. If the local time of either endpoint 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 (meaning the local time exists twice), the earlier offset will be used.

infix fun DateTimeInterval.at(zone: TimeZone): ZonedDateTimeInterval

Combines this InstantInterval with a TimeZone to create an equivalent ZonedDateTimeInterval where both endpoints are in zone.

infix fun InstantInterval.at(zone: TimeZone): ZonedDateTimeInterval

contains

common

Checks if this interval contains value.

This will always return false if value is null.

fun <T> Interval<T>.contains(value: T?): Boolean

Checks if this interval contains value. This will always return false if value is null.

operator fun <T : TimePoint<T>> TimePointInterval<T>.contains(value: TimePoint<*>?): Boolean

daysBetween

common

Gets the number of days between two dates.

fun daysBetween(start: Date, endExclusive: Date): LongDays

Gets the number whole days between two date-times, assuming they're in the same time zone.

fun daysBetween(start: DateTime, endExclusive: DateTime): LongDays

Gets the number whole days between two date-times, adjusting the offset of endExclusive if necessary to match the starting date-time.

fun daysBetween(start: OffsetDateTime, endExclusive: OffsetDateTime): LongDays

Gets the number of 24-hour days between two time points.

fun <T1, T2> daysBetween(start: TimePoint<T1>, endExclusive: TimePoint<T2>): LongDays

Gets the number of whole days between two zoned date-times, adjusting the time zone of endExclusive if necessary to match the starting date-time.

fun daysBetween(start: ZonedDateTime, endExclusive: ZonedDateTime): LongDays

downTo

common

Creates a progression of dates in descending order.

infix fun Date.downTo(to: Date): DateDayProgression

Creates a progression of time points in descending order.

infix fun <T : TimePoint<T>> T.downTo(to: T): TimePointProgressionBuilder<T>

durationBetween

common

Gets the Duration between two date-times, assuming they have the same UTC offset. In general, it's more appropriate to calculate duration using Instant or ZonedDateTime as any daylight savings rules won't be taken into account when working with DateTime directly.

fun durationBetween(start: DateTime, endExclusive: DateTime): Duration

Gets the Duration between two time points.

fun <T1, T2> durationBetween(start: TimePoint<T1>, endExclusive: TimePoint<T2>): Duration

hoursBetween

common

Gets the number of whole hours between two date-times, assuming they have the same UTC offset. In general, it's more appropriate to calculate duration using Instant or ZonedDateTime as any daylight savings rules won't be taken into account when working with DateTime directly.

fun hoursBetween(start: DateTime, endExclusive: DateTime): LongHours

Gets the number of whole hours between two time points.

fun <T1, T2> hoursBetween(start: TimePoint<T1>, endExclusive: TimePoint<T2>): LongHours

microsecondsBetween

common

Gets the number of whole microseconds between two date-times, assuming they have the same UTC offset. In general, it's more appropriate to calculate duration using Instant or ZonedDateTime as any daylight savings rules won't be taken into account when working with DateTime directly.

fun microsecondsBetween(start: DateTime, endExclusive: DateTime): LongMicroseconds

Gets the number of whole microseconds between two time points.

fun <T1, T2> microsecondsBetween(start: TimePoint<T1>, endExclusive: TimePoint<T2>): LongMicroseconds

millisecondsBetween

common

Gets the number of whole milliseconds between two date-times, assuming they have the same UTC offset. In general, it's more appropriate to calculate duration using Instant or ZonedDateTime as any daylight savings rules won't be taken into account when working with DateTime directly.

fun millisecondsBetween(start: DateTime, endExclusive: DateTime): LongMilliseconds

Gets the number of whole milliseconds between two time points.

fun <T1, T2> millisecondsBetween(start: TimePoint<T1>, endExclusive: TimePoint<T2>): LongMilliseconds

minutesBetween

common

Gets the number of whole minutes between two date-times, assuming they have the same UTC offset. In general, it's more appropriate to calculate duration using Instant or ZonedDateTime as any daylight savings rules won't be taken into account when working with DateTime directly.

fun minutesBetween(start: DateTime, endExclusive: DateTime): LongMinutes

Gets the number of whole minutes between two time points.

fun <T1, T2> minutesBetween(start: TimePoint<T1>, endExclusive: TimePoint<T2>): LongMinutes

monthsBetween

common

Gets the number of whole months between two dates.

fun monthsBetween(start: Date, endExclusive: Date): IntMonths

Gets the number of whole months between two date-times, assuming they're in the same time zone.

fun monthsBetween(start: DateTime, endExclusive: DateTime): IntMonths

Gets the number of whole months between two date-times, adjusting the offset of endExclusive if necessary to match the starting date-time.

fun monthsBetween(start: OffsetDateTime, endExclusive: OffsetDateTime): IntMonths

Gets the number of whole months between two zoned date-times, adjusting the time zone of endExclusive if necessary to match the starting date-time.

fun monthsBetween(start: ZonedDateTime, endExclusive: ZonedDateTime): IntMonths

nanosecondsBetween

common

Gets the number of nanoseconds between two date-times, assuming they have the same UTC offset. In general, it's more appropriate to calculate duration using Instant or ZonedDateTime as any daylight savings rules won't be taken into account when working with DateTime directly.

fun nanosecondsBetween(start: DateTime, endExclusive: DateTime): LongNanoseconds

Gets the number of nanoseconds between two time points.

fun <T1, T2> nanosecondsBetween(start: TimePoint<T1>, endExclusive: TimePoint<T2>): LongNanoseconds

periodBetween

common

Gets the Period between two dates.

fun periodBetween(start: Date, endExclusive: Date): Period

Gets the Period between two date-times, assuming they're in the same time zone.

fun periodBetween(start: DateTime, endExclusive: DateTime): Period

Gets the Period between two date-times, adjusting the offset of endExclusive if necessary to match the starting date-time.

fun periodBetween(start: OffsetDateTime, endExclusive: OffsetDateTime): Period

Gets the Period between two zoned date-times, adjusting the time zone of endExclusive if necessary to match the starting date-time.

fun periodBetween(start: ZonedDateTime, endExclusive: ZonedDateTime): Period

random

common

Returns a random date within this range using the default random number generator.

fun DateRange.random(): Date

Returns a random date within this range using the supplied random number generator.

fun DateRange.random(random: Random): Date

Returns a random date within this interval using the default random number generator.

fun DateTimeInterval.random(): DateTime

fun InstantInterval.random(): Instant

Returns a random date within this interval using the supplied random number generator.

fun DateTimeInterval.random(random: Random): DateTime

fun InstantInterval.random(random: Random): Instant

Returns a random date within this interval using the default random number generator. The offset of the start date-time will be used.

fun OffsetDateTimeInterval.random(): OffsetDateTime

Returns a random date within this interval using the supplied random number generator. The offset of the start date-time will be used.

fun OffsetDateTimeInterval.random(random: Random): OffsetDateTime

Returns a random date within this interval using the default random number generator. The zone of the start date-time will be used.

fun ZonedDateTimeInterval.random(): ZonedDateTime

Returns a random date within this interval using the supplied random number generator. The zone of the start date-time will be used.

fun ZonedDateTimeInterval.random(random: Random): ZonedDateTime

randomOrNull

common

Returns a random date within this range using the default random number generator or null if the interval is empty or unbounded.

fun DateRange.randomOrNull(): Date?

Returns a random date within this range using the supplied random number generator or null if the interval is empty or unbounded.

fun DateRange.randomOrNull(random: Random): Date?

Returns a random date within this interval using the default random number generator or null if the interval is empty or unbounded.

fun DateTimeInterval.randomOrNull(): DateTime?

fun InstantInterval.randomOrNull(): Instant?

Returns a random date within this interval using the supplied random number generator or null if the interval is empty or unbounded.

fun DateTimeInterval.randomOrNull(random: Random): DateTime?

fun InstantInterval.randomOrNull(random: Random): Instant?

Returns a random date within this interval using the default random number generator or null if the interval is empty or unbounded. The offset of the start date-time will be used.

fun OffsetDateTimeInterval.randomOrNull(): OffsetDateTime?

Returns a random date within this interval using the supplied random number generator or null if the interval is empty or unbounded. The offset of the start date-time will be used.

fun OffsetDateTimeInterval.randomOrNull(random: Random): OffsetDateTime?

Returns a random date within this interval using the default random number generator or null if the interval is empty or unbounded. The zone of the start date-time will be used.

fun ZonedDateTimeInterval.randomOrNull(): ZonedDateTime?

Returns a random date within this interval using the supplied random number generator or null if the interval is empty or unbounded. The zone of the start date-time will be used.

fun ZonedDateTimeInterval.randomOrNull(random: Random): ZonedDateTime?

reversed

common

Reverses this progression such that it counts down instead of up, or vice versa.

fun DateDayProgression.reversed(): DateDayProgression

fun DateMonthProgression.reversed(): DateMonthProgression

secondsBetween

common

Gets the number of whole seconds between two date-times, assuming they have the same UTC offset. In general, it's more appropriate to calculate duration using Instant or ZonedDateTime as any daylight savings rules won't be taken into account when working with DateTime directly.

fun secondsBetween(start: DateTime, endExclusive: DateTime): LongSeconds

Gets the number of whole seconds between two time points.

fun <T1, T2> secondsBetween(start: TimePoint<T1>, endExclusive: TimePoint<T2>): LongSeconds

step

common

Creates a progression that steps over the dates in this progression in increments of days.

infix fun DateDayProgression.step(step: IntDays): DateDayProgression

Creates a progression that steps over the dates in this progression in increments of weeks.

infix fun DateDayProgression.step(step: IntWeeks): DateDayProgression

Creates a progression that steps over the dates in this progression in increments of months.

infix fun DateDayProgression.step(step: IntMonths): DateMonthProgression

Creates a progression that steps over the dates in this progression in increments of years.

infix fun DateDayProgression.step(step: IntYears): DateMonthProgression

Creates a progression that steps over the dates in this progression in increments of decades.

infix fun DateDayProgression.step(step: IntDecades): DateMonthProgression

Creates a progression that steps over the dates in this progression in increments of centuries.

infix fun DateDayProgression.step(step: IntCenturies): DateMonthProgression

infix fun <T : TimePoint<T>> TimePointProgressionBuilder<T>.step(step: IntDays): TimePointSecondProgression<T>

infix fun <T : TimePoint<T>> TimePointProgressionBuilder<T>.step(step: IntHours): TimePointSecondProgression<T>

infix fun <T : TimePoint<T>> TimePointProgressionBuilder<T>.step(step: IntMinutes): TimePointSecondProgression<T>

infix fun <T : TimePoint<T>> TimePointProgressionBuilder<T>.step(step: IntSeconds): TimePointSecondProgression<T>

infix fun <T : TimePoint<T>> TimePointProgressionBuilder<T>.step(step: IntMilliseconds): TimePointNanosecondProgression<T>

infix fun <T : TimePoint<T>> TimePointProgressionBuilder<T>.step(step: LongMilliseconds): TimePointNanosecondProgression<T>

infix fun <T : TimePoint<T>> TimePointProgressionBuilder<T>.step(step: IntMicroseconds): TimePointNanosecondProgression<T>

infix fun <T : TimePoint<T>> TimePointProgressionBuilder<T>.step(step: LongMicroseconds): TimePointNanosecondProgression<T>

infix fun <T : TimePoint<T>> TimePointProgressionBuilder<T>.step(step: IntNanoseconds): TimePointNanosecondProgression<T>

infix fun <T : TimePoint<T>> TimePointProgressionBuilder<T>.step(step: LongNanoseconds): TimePointNanosecondProgression<T>

toDateRange

common

Returns this interval with the precision reduced to just the date.

fun DateTimeInterval.toDateRange(): DateRange

fun OffsetDateTimeInterval.toDateRange(): DateRange

fun ZonedDateTimeInterval.toDateRange(): DateRange

Converts a string to a DateRange.

The string is assumed to be an ISO-8601 time interval representation in extended format. The output of DateRange.toString can be safely parsed using this method.

Examples:

1990-01-04/1991-08-30
../1991-08-30
1990-01-04/..
../..
(empty string)

fun String.toDateRange(): DateRange

Converts a string to a DateRange using a specific parser.

A set of predefined parsers can be found in DateTimeParsers.

fun String.toDateRange(parser: GroupedDateTimeParser, settings: DateTimeParserSettings): DateRange

toDateRangeAt

common

Converts this interval to the equivalent DateRange when both endpoints are in zone.

fun InstantInterval.toDateRangeAt(zone: TimeZone): DateRange

toDateTimeInterval

common

Returns this interval with the precision reduced to only the local date and time.

fun OffsetDateTimeInterval.toDateTimeInterval(): DateTimeInterval

fun ZonedDateTimeInterval.toDateTimeInterval(): DateTimeInterval

Converts a string to a DateTimeInterval.

The string is assumed to be an ISO-8601 time interval representation in extended format. The output of DateTimeInterval.toString can be safely parsed using this method.

Examples:

1990-01-04T03/1991-08-30T15:30:05.123
../1991-08-30T15:30:05.123
1990-01-04T03/..
../..
(empty string)

fun String.toDateTimeInterval(): DateTimeInterval

Converts a string to a DateTimeInterval using a specific parser.

A set of predefined parsers can be found in DateTimeParsers.

fun String.toDateTimeInterval(parser: GroupedDateTimeParser, settings: DateTimeParserSettings): DateTimeInterval

toDateTimeIntervalAt

common

Converts this interval to the equivalent DateTimeInterval when both endpoints are in zone.

fun InstantInterval.toDateTimeIntervalAt(zone: TimeZone): DateTimeInterval

toInstantInterval

common

Converts this interval to an InstantInterval.

fun OffsetDateTimeInterval.toInstantInterval(): InstantInterval

fun ZonedDateTimeInterval.toInstantInterval(): InstantInterval

Converts a string to an InstantInterval.

The string is assumed to be an ISO-8601 time interval representation in extended format. The output of InstantInterval.toString can be safely parsed using this method.

Examples:

1990-01-04T03Z/1991-08-30T15:30:05.123Z
../1991-08-30T15:30:05.123Z
1990-01-04T03Z/..
../..
(empty string)

fun String.toInstantInterval(): InstantInterval

Converts a string to an InstantInterval using a specific parser.

A set of predefined parsers can be found in DateTimeParsers.

fun String.toInstantInterval(parser: GroupedDateTimeParser, settings: DateTimeParserSettings): InstantInterval

toInstantIntervalAt

common

Converts this range to an InstantInterval between the start of the first day and the end of the last day in zone.

fun DateRange.toInstantIntervalAt(zone: TimeZone): InstantInterval

Converts this interval to an InstantInterval where both endpoints are in zone.

fun DateTimeInterval.toInstantIntervalAt(zone: TimeZone): InstantInterval

toOffsetDateTimeInterval

common

Converts this interval to an OffsetDateTimeInterval.

While similar to ZonedDateTime, an OffsetDateTime representation is unaffected by time zone rule changes or database differences between systems, making it better suited for use cases involving persistence or network transfer.

fun ZonedDateTimeInterval.toOffsetDateTimeInterval(): OffsetDateTimeInterval

Converts a string to an OffsetDateTimeInterval.

The string is assumed to be an ISO-8601 time interval representation in extended format. The output of OffsetDateTimeInterval.toString can be safely parsed using this method.

Examples:

1990-01-04T03-05/1991-08-30T15:30:05.123-04:00
../1991-08-30T15:30:05.123-04:00
1990-01-04T03-05/..
../..
(empty string)

fun String.toOffsetDateTimeInterval(): OffsetDateTimeInterval

Converts a string to an OffsetDateTimeInterval using a specific parser.

A set of predefined parsers can be found in DateTimeParsers.

fun String.toOffsetDateTimeInterval(parser: GroupedDateTimeParser, settings: DateTimeParserSettings): OffsetDateTimeInterval

toZonedDateTimeInterval

common

Converts this interval to a ZonedDateTimeInterval using the specified strategy to adjust each endpoint to a valid date, time, and offset in zone.

OffsetConversionStrategy.PRESERVE_INSTANT - Preserve the instant captured by the date, time, and offset, ignoring the local time.
OffsetConversionStrategy.PRESERVE_LOCAL_TIME - Preserve the local date and time in the new time zone, adjusting the offset if needed.

Alternatively, you can use asZonedDateTimeInterval to convert each endpoint to a ZonedDateTime with an equivalent fixed-offset zone. However, this comes with the caveat that a fixed-offset zone lacks knowledge of any region and will not respond to daylight savings time changes.

fun OffsetDateTimeInterval.toZonedDateTimeInterval(zone: TimeZone, strategy: OffsetConversionStrategy): ZonedDateTimeInterval

Converts a string to a ZonedDateTimeInterval.

The string is assumed to be an ISO-8601 time interval representation in extended format. The output of ZonedDateTimeInterval.toString can be safely parsed using this method.

Examples:

1990-01-04T03-05[America/New_York]/1991-08-30T15:30:05.123-04:00
../1991-08-30T15:30:05.123-04:00
1990-01-04T03-05[Europe/London]/..
../..
(empty string)

fun String.toZonedDateTimeInterval(): ZonedDateTimeInterval

Converts a string to a ZonedDateTimeInterval using a specific parser.

A set of predefined parsers can be found in DateTimeParsers.

fun String.toZonedDateTimeInterval(parser: GroupedDateTimeParser, settings: DateTimeParserSettings): ZonedDateTimeInterval

until

common

Creates a DateRange containing all of the days from this date up to, but not including to.

infix fun Date.until(to: Date): DateRange

Creates a DateTimeInterval from this date-time up to, but not including the nanosecond represented by to.

infix fun DateTime.until(to: DateTime): DateTimeInterval

Creates an InstantInterval from this instant up to, but not including to.

infix fun Instant.until(to: Instant): InstantInterval

Creates an OffsetDateTimeInterval from this date-time up to, but not including to.

infix fun OffsetDateTime.until(to: OffsetDateTime): OffsetDateTimeInterval

Creates a ZonedDateTimeInterval from this date-time up to, but not including to.

infix fun ZonedDateTime.until(to: ZonedDateTime): ZonedDateTimeInterval

weeksBetween

common

Gets the number of whole weeks between two dates.

fun weeksBetween(start: Date, endExclusive: Date): LongWeeks

Gets the number whole weeks between two date-times, assuming they're in the same time zone.

fun weeksBetween(start: DateTime, endExclusive: DateTime): LongWeeks

Gets the number whole weeks between two date-times, adjusting the offset of endExclusive if necessary to match the starting date-time.

fun weeksBetween(start: OffsetDateTime, endExclusive: OffsetDateTime): LongWeeks

Gets the number of whole weeks between two zoned date-times, adjusting the time zone of endExclusive if necessary to match the starting date-time.

fun weeksBetween(start: ZonedDateTime, endExclusive: ZonedDateTime): LongWeeks

yearsBetween

common

Gets the number of whole years between two dates.

fun yearsBetween(start: Date, endExclusive: Date): IntYears

Gets the number of whole years between two date-times, assuming they're in the same time zone.

fun yearsBetween(start: DateTime, endExclusive: DateTime): IntYears

Gets the number of whole years between two date-times, adjusting the offset of endExclusive if necessary to match the starting date-time.

fun yearsBetween(start: OffsetDateTime, endExclusive: OffsetDateTime): IntYears

Gets the number of whole years between two zoned date-times, adjusting the time zone of endExclusive if necessary to match the starting date-time.

fun yearsBetween(start: ZonedDateTime, endExclusive: ZonedDateTime): IntYears