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

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

An inclusive range of dates.

DateTimeInterval

common

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

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

InstantInterval

common

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

A half-open interval between two instants.

Interval

common

interface Interval<T>

A half-open or closed interval.

OffsetDateTimeInterval

common

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

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

TimePointInterval

common

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

A half-open interval of time points.

TimePointNanosecondProgression

common

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

TimePointProgressionBuilder

common

interface TimePointProgressionBuilder<T : TimePoint<T>>

A time point progression builder.

TimePointSecondProgression

common

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

ZonedDateTimeInterval

common

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

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

Functions

asZonedDateTimeInterval

common

fun OffsetDateTimeInterval.asZonedDateTimeInterval(): ZonedDateTimeInterval

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

common

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

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 DateTimeInterval.at(zone: TimeZone): ZonedDateTimeInterval

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

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

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

contains

common

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

Checks if this interval contains value.

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

Checks if this interval contains value.

daysBetween

common

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

Gets the number of days between two dates.

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

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

fun daysBetween(start: OffsetDateTime, endExclusive: OffsetDateTime): 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: ZonedDateTime, endExclusive: ZonedDateTime): 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 <T1, T2> daysBetween(start: TimePoint<T1>, endExclusive: TimePoint<T2>): LongDays

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

downTo

common

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

Creates a progression of time points in descending order.

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

Creates a progression of dates in descending order.

durationBetween

common

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

Gets the Duration between two date-times, assuming they have the same UTC offset.

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

Gets the Duration between two time points.

hoursBetween

common

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

Gets the number of whole hours between two date-times, assuming they have the same UTC offset.

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

Gets the number of whole hours between two time points.

microsecondsBetween

common

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

Gets the number of whole microseconds between two date-times, assuming they have the same UTC offset.

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

Gets the number of whole microseconds between two time points.

millisecondsBetween

common

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

Gets the number of whole milliseconds between two date-times, assuming they have the same UTC offset.

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

Gets the number of whole milliseconds between two time points.

minutesBetween

common

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

Gets the number of whole minutes between two date-times, assuming they have the same UTC offset.

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

Gets the number of whole minutes between two time points.

monthsBetween

common

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

Gets the number of whole months between two dates.

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

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

fun monthsBetween(start: OffsetDateTime, endExclusive: OffsetDateTime): 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: ZonedDateTime, endExclusive: ZonedDateTime): 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.

nanosecondsBetween

common

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

Gets the number of nanoseconds between two date-times, assuming they have the same UTC offset.

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

Gets the number of nanoseconds between two time points.

periodBetween

common

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

Gets the Period between two dates.

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

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

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

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

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

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

random

common

fun DateRange.random(): Date

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

fun DateTimeInterval.random(): DateTime

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

fun InstantInterval.random(): Instant

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

fun OffsetDateTimeInterval.random(): OffsetDateTime

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

fun ZonedDateTimeInterval.random(): ZonedDateTime

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

fun DateRange.random(random: Random): Date

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

fun DateTimeInterval.random(random: Random): DateTime

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

fun InstantInterval.random(random: Random): Instant

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

fun OffsetDateTimeInterval.random(random: Random): OffsetDateTime

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

fun ZonedDateTimeInterval.random(random: Random): ZonedDateTime

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

randomOrNull

common

fun DateRange.randomOrNull(): Date?

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

fun DateTimeInterval.randomOrNull(): DateTime?

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

fun InstantInterval.randomOrNull(): Instant?

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

fun OffsetDateTimeInterval.randomOrNull(): OffsetDateTime?

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

fun ZonedDateTimeInterval.randomOrNull(): ZonedDateTime?

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

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

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

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

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

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

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

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

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

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

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

reversed

common

fun DateDayProgression.reversed(): DateDayProgression

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

fun DateMonthProgression.reversed(): DateMonthProgression

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

secondsBetween

common

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

Gets the number of whole seconds between two date-times, assuming they have the same UTC offset.

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

Gets the number of whole seconds between two time points.

step

common

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

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

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

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

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

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

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

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

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

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

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

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

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: IntMicroseconds): TimePointNanosecondProgression<T>

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

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

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

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

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

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

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

toDateRange

common

fun DateTimeInterval.toDateRange(): DateRange

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

fun OffsetDateTimeInterval.toDateRange(): DateRange

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

fun ZonedDateTimeInterval.toDateRange(): DateRange

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

fun String.toDateRange(): DateRange

Converts a string to a DateRange.

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

Converts a string to a DateRange using a specific parser.

toDateRangeAt

common

fun InstantInterval.toDateRangeAt(zone: TimeZone): DateRange

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

toDateTimeInterval

common

fun OffsetDateTimeInterval.toDateTimeInterval(): DateTimeInterval

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

fun ZonedDateTimeInterval.toDateTimeInterval(): DateTimeInterval

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

fun String.toDateTimeInterval(): DateTimeInterval

Converts a string to a DateTimeInterval.

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

Converts a string to a DateTimeInterval using a specific parser.

toDateTimeIntervalAt

common

fun InstantInterval.toDateTimeIntervalAt(zone: TimeZone): DateTimeInterval

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

toInstantInterval

common

fun OffsetDateTimeInterval.toInstantInterval(): InstantInterval

Converts this interval to an InstantInterval.

fun ZonedDateTimeInterval.toInstantInterval(): InstantInterval

Converts this interval to an InstantInterval.

fun String.toInstantInterval(): InstantInterval

Converts a string to an InstantInterval.

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

Converts a string to an InstantInterval using a specific parser.

toInstantIntervalAt

common

fun DateRange.toInstantIntervalAt(zone: TimeZone): InstantInterval

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

fun DateTimeInterval.toInstantIntervalAt(zone: TimeZone): InstantInterval

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

toOffsetDateTimeInterval

common

fun ZonedDateTimeInterval.toOffsetDateTimeInterval(): OffsetDateTimeInterval

Converts this interval to an OffsetDateTimeInterval.

fun String.toOffsetDateTimeInterval(): OffsetDateTimeInterval

Converts a string to an OffsetDateTimeInterval.

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

Converts a string to an OffsetDateTimeInterval using a specific parser.

toZonedDateTimeInterval

common

fun String.toZonedDateTimeInterval(): ZonedDateTimeInterval

Converts a string to a ZonedDateTimeInterval.

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

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

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

Converts a string to a ZonedDateTimeInterval using a specific parser.

until

common

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

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

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

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

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

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

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

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

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

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

weeksBetween

common

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

Gets the number of whole weeks between two dates.

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

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

fun weeksBetween(start: OffsetDateTime, endExclusive: OffsetDateTime): 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: ZonedDateTime, endExclusive: ZonedDateTime): 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.

yearsBetween

common

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

Gets the number of whole years between two dates.

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

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

fun yearsBetween(start: OffsetDateTime, endExclusive: OffsetDateTime): 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: ZonedDateTime, endExclusive: ZonedDateTime): 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.