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. This will always return false if value is null.

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.

random

common

fun DateRange.random(): Date

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

fun DateTimeInterval.random(): DateTime

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. The offset of the start date-time will be used.

fun ZonedDateTimeInterval.random(): ZonedDateTime

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

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

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. The offset of the start date-time will be used.

fun ZonedDateTimeInterval.random(random: 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.

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?

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. The offset of the start date-time will be used.

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. The zone of the start date-time will be used.

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?

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. The offset of the start date-time will be used.

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. The zone of the start date-time will be used.

reversed

common

fun DateDayProgression.reversed(): DateDayProgression

fun DateMonthProgression.reversed(): DateMonthProgression

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

step

common

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

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

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

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

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

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

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

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

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

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

infix fun DateDayProgression.step(step: Years): 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: Days): TimePointSecondProgression<T>

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

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

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

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

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

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

toDateRange

common

fun DateTimeInterval.toDateRange(): DateRange

fun OffsetDateTimeInterval.toDateRange(): DateRange

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

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.

toDuration

common

fun DateTimeInterval.toDuration(): Duration

Converts this interval to the Duration between the start and end date-time, which are assumed to be in the same time zone. 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 TimePointInterval<*>.toDuration(): Duration

Converts this interval into a Duration of the same length.

toInstantInterval

common

fun OffsetDateTimeInterval.toInstantInterval(): 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.

toPeriod

common

fun DateRange.toPeriod(): Period

Converts this range into a Period of the same length. As a range is inclusive, if the start and end date are the same, the resulting period will contain one day.

fun DateTimeInterval.toPeriod(): Period

fun OffsetDateTimeInterval.toPeriod(): Period

fun ZonedDateTimeInterval.toPeriod(): Period

Converts this interval into a Period of the same length.

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.

Properties

lengthInCenturies

common

val DateRange.lengthInCenturies: Centuries

The number of whole centuries between the start and end of this range.

lengthInCenturies

common

val DateTimeInterval.lengthInCenturies: Centuries

The number of whole centuries between the start and end of this interval.

lengthInCenturies

common

val OffsetDateTimeInterval.lengthInCenturies: Centuries

The number of whole centuries between the start and end of this interval.

lengthInCenturies

common

val ZonedDateTimeInterval.lengthInCenturies: Centuries

The number of whole centuries between the start and end of this interval.

lengthInDays

common

val DateRange.lengthInDays: Days

The number of days between the start and end of this range. A range is inclusive, so if the start and end date are the same, the length will be one day.

lengthInDays

common

val DateTimeInterval.lengthInDays: Days

The number of whole days between the start and end of this interval.

lengthInDays

common

val OffsetDateTimeInterval.lengthInDays: Days

The number of whole days between the start and end of this interval.

lengthInDays

common

val ZonedDateTimeInterval.lengthInDays: Days

The number of whole days between the start and end of this interval.

lengthInDecades

common

val DateRange.lengthInDecades: Decades

The number of whole decades between the start and end of this range.

lengthInDecades

common

val DateTimeInterval.lengthInDecades: Decades

The number of whole decades between the start and end of this interval.

lengthInDecades

common

val OffsetDateTimeInterval.lengthInDecades: Decades

The number of whole decades between the start and end of this interval.

lengthInDecades

common

val ZonedDateTimeInterval.lengthInDecades: Decades

The number of whole decades between the start and end of this interval.

lengthInHours

common

val DateTimeInterval.lengthInHours: Hours

The number of whole hours between the start and end of this interval.

lengthInHours

common

val TimePointInterval<*>.lengthInHours: Hours

The number of whole hours between the start and end of this interval.

lengthInMicroseconds

common

val DateTimeInterval.lengthInMicroseconds: Microseconds

The number of whole microseconds between the start and end of this interval.

lengthInMicroseconds

common

val TimePointInterval<*>.lengthInMicroseconds: Microseconds

The number of whole microseconds between the start and end of this interval.

lengthInMilliseconds

common

val DateTimeInterval.lengthInMilliseconds: Milliseconds

The number of whole milliseconds between the start and end of this interval.

lengthInMilliseconds

common

val TimePointInterval<*>.lengthInMilliseconds: Milliseconds

The number of whole milliseconds between the start and end of this interval.

lengthInMinutes

common

val DateTimeInterval.lengthInMinutes: Minutes

The number of whole minutes between the start and end of this interval.

lengthInMinutes

common

val TimePointInterval<*>.lengthInMinutes: Minutes

The number of whole minutes between the start and end of this interval.

lengthInMonths

common

val DateRange.lengthInMonths: Months

The number of whole months between the start and end of this range.

lengthInMonths

common

val DateTimeInterval.lengthInMonths: Months

The number of whole months between the start and end of this interval.

lengthInMonths

common

val OffsetDateTimeInterval.lengthInMonths: Months

The number of whole months between the start and end of this interval.

lengthInMonths

common

val ZonedDateTimeInterval.lengthInMonths: Months

The number of whole months between the start and end of this interval.

lengthInNanoseconds

common

val DateTimeInterval.lengthInNanoseconds: Nanoseconds

The number of nanoseconds between the start and end of this interval.

lengthInNanoseconds

common

val TimePointInterval<*>.lengthInNanoseconds: Nanoseconds

The number of nanoseconds between the start and end of this interval.

lengthInSeconds

common

val DateTimeInterval.lengthInSeconds: Seconds

The number of whole seconds between the start and end of this interval.

lengthInSeconds

common

val TimePointInterval<*>.lengthInSeconds: Seconds

The number of whole seconds between the start and end of this interval.

lengthInWeeks

common

val DateRange.lengthInWeeks: Weeks

The number of whole weeks between the start and end of this range.

lengthInWeeks

common

val DateTimeInterval.lengthInWeeks: Weeks

The number of whole weeks between the start and end of this interval.

lengthInWeeks

common

val OffsetDateTimeInterval.lengthInWeeks: Weeks

The number of whole weeks between the start and end of this interval.

lengthInWeeks

common

val ZonedDateTimeInterval.lengthInWeeks: Weeks

The number of whole weeks between the start and end of this interval.

lengthInYears

common

val DateRange.lengthInYears: Years

The number of whole years between the start and end of this range.

lengthInYears

common

val DateTimeInterval.lengthInYears: Years

The number of whole years between the start and end of this interval.

lengthInYears

common

val OffsetDateTimeInterval.lengthInYears: Years

The number of whole years between the start and end of this interval.

lengthInYears

common

val ZonedDateTimeInterval.lengthInYears: Years

The number of whole years between the start and end of this interval.