Package com.thanlinardos.spring_enterprise_library.time.model

Record Class TimeInterval

java.lang.Object

java.lang.Record

com.thanlinardos.spring_enterprise_library.time.model.TimeInterval

Record Components:

start - the start of the interval.

end - the end of the interval.

All Implemented Interfaces:

Comparable<TimeInterval>

public record TimeInterval(@Nullable LocalDateTime start, @Nullable LocalDateTime end)
extends Record
implements Comparable<TimeInterval>

Represents a time interval with a start and end date. Provides utility methods for creating, manipulating, and analyzing Intervals.

Constructor Summary

Constructors

Constructor	Description
TimeInterval(Interval interval)	Constructs a TimeInterval for the given Interval.
TimeInterval(LocalDate date)	Constructs an TimeInterval for the given LocalDate, where the interval will span the whole given day.
TimeInterval(LocalDate startDate, LocalDate endDate)	Constructs an TimeInterval for the given start and end LocalDates.
TimeInterval(LocalDate startDate, LocalDate endDate, TimeUnit accuracy)	Constructs an TimeInterval for the given start and end LocalDates and with the given accuracy.
TimeInterval(LocalDateTime start, LocalDateTime end)	Constructs an interval with the given start and end dates.
TimeInterval(Year year)	Constructs an TimeInterval for the given Year.
TimeInterval(YearMonth yearMonth)	Constructs an TimeInterval for the given YearMonth.

Method Summary

Modifier and Type	Method	Description
boolean	adjacent(TimeInterval interval)	Checks if the given TimeInterval is touching this interval.
static boolean	anyOverlaps(Collection<TimeInterval> intervals)	Returns true if any of the given intervals overlap with each other, otherwise false
Optional<TimeInterval>	boundEnd(LocalDateTime upperBound)	Returns a new version of this interval, where the end date is bounded according to the given upperBound.
Optional<TimeInterval>	boundStart(LocalDateTime lowerBound)	Returns a new version of this interval, where the start date is bounded according to the given lowerBound Equivalent to calling getOverlap(TimeInterval) with an interval starting from lowerBound and ending in null.
TimeInterval	boundStartDateIfValid(LocalDateTime lowerBound)	Returns a new version of this interval, where the start date is bounded according to boundStart(LocalDateTime).
int	compareTo(TimeInterval o)
boolean	contains(TimeInterval interval)	Checks if the given TimeInterval is fully contained within this interval.
boolean	contains(LocalDateTime dateTime)	Checks if the given dateTime is contained within this interval.
boolean	contains(YearMonth yearMonth)	Checks if the given YearMonth is fully contained within this interval.
boolean	containsNullAsMax(LocalDateTime dateTime)	Checks if the given dateTime is contained within this interval, treating null as TimeFactory.getMaxDateTime().
boolean	containsNullAsMin(LocalDateTime dateTime)	Checks if the given dateTime is contained within this interval, treating null as TimeFactory.getMinDateTime().
LocalDateTime	end()	Returns the value of the end record component.
final boolean	equals(Object o)	Indicates whether some other object is "equal to" this one.
static TimeInterval	forIsoDateMilliToNull(String startDate)	Constructs an open-ended TimeInterval same as in forIsoDateToNull(String), but with overridden millisecond accuracy.
static TimeInterval	forIsoDates(String startDate, String endDate)	Constructs an TimeInterval using ISO 8601 formatted dates (such as "2007-12-03").
static TimeInterval	forIsoDates(String startDate, String endDate, TimeUnit accuracy)	Constructs an TimeInterval using ISO 8601 formatted dates (such as "2007-12-03"), with the given accuracy to override the default with.
static TimeInterval	forIsoDatesMilli(String startDate, String endDate)	Constructs an TimeInterval same as in forIsoDates(String, String, TimeUnit), but with overridden millisecond accuracy.
static TimeInterval	forIsoDateTimes(String start, String end)	Constructs an TimeInterval using ISO 8601 formatted date times (such as "2007-12-03T10:15:30.00").
static TimeInterval	forIsoDateToNull(String startDate)	Constructs an TimeInterval using ISO 8601 formatted date (such as "2007-12-03"), starting from the given date time and with open end.
static TimeInterval	forIsoMonth(String month)	Constructs an TimeInterval using a ISO 8601 formatted month ("YYYY-MM").
static TimeInterval	forIsoYear(int year)	Constructs an TimeInterval using a year.
LocalDateTime	getEndNullAsMax()	Returns the end LocalDateTime, or the maximum LocalDateTime if the end is null.
List<TimeInterval>	getNotOverlaps(TimeInterval... intervals)	Vararg variant of getNotOverlaps(Collection)
List<TimeInterval>	getNotOverlaps(Collection<TimeInterval> intervals)	Returns a normalized list of the portions of intervals that do not overlap with this interval
Optional<TimeInterval>	getOverlap(TimeInterval interval)	Returns the overlap between this interval and the given interval, otherwise an empty Optional if there is no overlap
List<TimeInterval>	getOverlaps(TimeInterval... intervals)	Vararg variant of getOverlaps(Collection)
List<TimeInterval>	getOverlaps(Collection<TimeInterval> intervals)	Returns a normalized (see normalize(Collection)) list of overlaps between the given intervals and this interval
List<TimeInterval>	getOverlaps(Collection<TimeInterval> intervals, boolean mergeAdjacentIntervals)	Returns a normalized (see normalize(Collection)) list of overlaps between the given intervals and this interval Whether to merge adjacent overlaps is subject to the value of mergeAdjacentIntervals
LocalDateTime	getStartNullAsMin()	Returns the start LocalDateTime, or the minimum LocalDateTime if the start is null.
final int	hashCode()	Returns a hash code value for this object.
static boolean	isNotValid(LocalDateTime start, LocalDateTime end)	Validates whether the start dateTime is before or equal to the end dateTime.
static boolean	isValid(LocalDateTime start, LocalDateTime end)	Validates whether the start LocalDateTime is before or equal to the end LocalDateTime.
static List<TimeInterval>	normalize(Collection<TimeInterval> intervals)	Returns a sorted list of intervals, covering the same days as the input, but without any intervals overlapping.
static List<TimeInterval>	normalize(Collection<TimeInterval> intervals, boolean mergeAdjacentIntervals)	Returns a sorted list of intervals, covering the same days as the input, but without any intervals overlapping.
boolean	overlaps(TimeInterval interval)	Checks if this TimeInterval overlaps the given interval.
boolean	overlaps(YearMonth yearMonth)	Returns true if this TimeInterval overlaps with the given yearMonth, otherwise false.
boolean	overlaps(Collection<TimeInterval> intervals)	Checks if this TimeInterval overlaps with any of the given intervals.
boolean	partiallyOverlaps(TimeInterval interval)	Checks if this TimeInterval partially overlaps the given interval, meaning that they overlap but neither contains the other.
List<TimeInterval>	relativeComplement(Collection<TimeInterval> intervals)	Returns the list of the given intervals, excluding any elements equal to this interval
static List<TimeInterval>	split(Collection<TimeInterval> intervals)	Returns a sorted list of intervals, covering the same LocalDateTimes as the input, but without any intervals overlapping.
LocalDateTime	start()	Returns the value of the start record component.
List<TimeInterval>	subtract(TimeInterval interval)	Returns the remainder of this interval, after subtracting the overlap with the given interval
List<TimeInterval>	subtract(Collection<TimeInterval> intervals)	Returns the remainder of this interval, after subtracting the overlap with the given intervals
final String	toString()	Returns a string representation of this record class.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

TimeInterval

public TimeInterval(@Nullable
 LocalDateTime start,
 @Nullable
 LocalDateTime end)

Constructs an interval with the given start and end dates.

Parameters:

start - the start date of the interval (nullable)

end - the end date of the interval (nullable)

Throws:

IllegalArgumentException - if the start date is after the end date

TimeInterval

public TimeInterval(LocalDate date)

Constructs an TimeInterval for the given LocalDate, where the interval will span the whole given day.

Parameters:

date - the LocalDate to create the interval for.

TimeInterval

public TimeInterval(LocalDate startDate,
 LocalDate endDate)

Constructs an TimeInterval for the given start and end LocalDates.

Parameters:

startDate - the start LocalDate to create the interval for.

endDate - the end LocalDate to create the interval for.

TimeInterval

public TimeInterval(LocalDate startDate,
 LocalDate endDate,
 TimeUnit accuracy)

Constructs an TimeInterval for the given start and end LocalDates and with the given accuracy.

Parameters:

startDate - the start LocalDate to create the interval for.

endDate - the end LocalDate to create the interval for.

accuracy - the TimeUnit accuracy to represent the date-time interval with.

TimeInterval

public TimeInterval(Interval interval)

Constructs a TimeInterval for the given Interval.

Parameters:

interval - the Interval to create the interval for.

TimeInterval

public TimeInterval(YearMonth yearMonth)

Constructs an TimeInterval for the given YearMonth.

Parameters:

yearMonth - the YearMonth to create the interval for.

TimeInterval

public TimeInterval(Year year)

Constructs an TimeInterval for the given Year.

Parameters:

year - the Year to create the interval for.

Method Details

isNotValid

public static boolean isNotValid(@Nullable
 LocalDateTime start,
 @Nullable
 LocalDateTime end)

Validates whether the start dateTime is before or equal to the end dateTime.

Parameters:

start - the start dateTime

end - the end dateTime

Returns:

true if the start dateTime is after the end dateTime, false otherwise.

isValid

public static boolean isValid(@Nullable
 LocalDateTime start,
 @Nullable
 LocalDateTime end)

Validates whether the start LocalDateTime is before or equal to the end LocalDateTime.

Parameters:

start - the start LocalDateTime.

end - the end LocalDateTime.

Returns:

true if the start LocalDateTime is before or equal to the end LocalDateTime, false otherwise.

forIsoDateToNull

public static TimeInterval forIsoDateToNull(String startDate)

Constructs an TimeInterval using ISO 8601 formatted date (such as "2007-12-03"), starting from the given date time and with open end.

Parameters:

startDate - the start date time (inclusive).

Returns:

a TimeInterval based on the given date and open end.

forIsoDateMilliToNull

public static TimeInterval forIsoDateMilliToNull(String startDate)

Constructs an open-ended TimeInterval same as in forIsoDateToNull(String), but with overridden millisecond accuracy.

Parameters:

startDate - the start date time (inclusive).

Returns:

a TimeInterval based on the given date and open end.

forIsoDateTimes

public static TimeInterval forIsoDateTimes(@Nullable
 String start,
 @Nullable
 String end)

Constructs an TimeInterval using ISO 8601 formatted date times (such as "2007-12-03T10:15:30.00"). The format is further specified in DateTimeFormatter.ISO_LOCAL_DATE_TIME.

Parameters:

start - start of the interval (inclusive).

end - end of the interval (inclusive).

Returns:

an TimeInterval based on the given dateTimes.

forIsoDates

public static TimeInterval forIsoDates(@Nullable
 String startDate,
 @Nullable
 String endDate)

Constructs an TimeInterval using ISO 8601 formatted dates (such as "2007-12-03").

Parameters:

startDate - the start date (inclusive).

endDate - the end date (inclusive).

Returns:

an TimeInterval based on the given dates.

forIsoDates

public static TimeInterval forIsoDates(@Nullable
 String startDate,
 @Nullable
 String endDate,
 TimeUnit accuracy)

Constructs an TimeInterval using ISO 8601 formatted dates (such as "2007-12-03"), with the given accuracy to override the default with.

Parameters:

startDate - the start date (inclusive).

endDate - the end date (inclusive).

accuracy - the TimeUnit accuracy to represent the date-time interval with.

Returns:

an TimeInterval based on the given dates.

forIsoDatesMilli

public static TimeInterval forIsoDatesMilli(@Nullable
 String startDate,
 @Nullable
 String endDate)

Constructs an TimeInterval same as in forIsoDates(String, String, TimeUnit), but with overridden millisecond accuracy.

Parameters:

startDate - the start date (inclusive).

endDate - the end date (inclusive).

Returns:

an TimeInterval based on the given dates.

forIsoMonth

public static TimeInterval forIsoMonth(@Nonnull
 String month)

Constructs an TimeInterval using a ISO 8601 formatted month ("YYYY-MM").

Parameters:

month - a string representing the month (e.g. "2025-07")

Returns:

an TimeInterval based on the given month

forIsoYear

public static TimeInterval forIsoYear(int year)

Constructs an TimeInterval using a year.

Parameters:

year - an int representing the year (e.g. 2025)

Returns:

an TimeInterval based on the given year

getStartNullAsMin

public LocalDateTime getStartNullAsMin()

Returns the start LocalDateTime, or the minimum LocalDateTime if the start is null.

Returns:

the start LocalDateTime or TimeFactory.getMinDateTime()

getEndNullAsMax

public LocalDateTime getEndNullAsMax()

Returns the end LocalDateTime, or the maximum LocalDateTime if the end is null.

Returns:

the end LocalDateTime or TimeFactory.getMaxDateTime()

split

public static List<TimeInterval> split(Collection<TimeInterval> intervals)

Returns a sorted list of intervals, covering the same LocalDateTimes as the input, but without any intervals overlapping.

 Input:
 [-----------]    [-------------][------][----------------]    [---]
        [---------------]                    [---][---]
 Output:
 [-----][----][--][-----][------][------][--][---][---][--]    [---]
 

Parameters:

intervals - collection of intervals to normalize

Returns:

split list of intervals

containsNullAsMin

public boolean containsNullAsMin(@Nullable
 LocalDateTime dateTime)

Checks if the given dateTime is contained within this interval, treating null as TimeFactory.getMinDateTime().

Parameters:

dateTime - the dateTime to check

Returns:

true if the dateTime is contained, false otherwise

containsNullAsMax

public boolean containsNullAsMax(@Nullable
 LocalDateTime dateTime)

Checks if the given dateTime is contained within this interval, treating null as TimeFactory.getMaxDateTime().

Parameters:

dateTime - the dateTime to check

Returns:

true if the dateTime is contained, false otherwise

contains

public boolean contains(@Nonnull
 LocalDateTime dateTime)

Checks if the given dateTime is contained within this interval.

Parameters:

dateTime - the dateTime to check.

Returns:

true if the dateTime is contained, false otherwise.

contains

public boolean contains(@Nonnull
 YearMonth yearMonth)

Checks if the given YearMonth is fully contained within this interval.

Parameters:

yearMonth - a given YearMonth.

Returns:

true if this TimeInterval fully contains the given YearMonth, otherwise false.

contains

public boolean contains(@Nonnull
 TimeInterval interval)

Checks if the given TimeInterval is fully contained within this interval.

Parameters:

interval - a given TimeInterval.

Returns:

true if this TimeInterval fully contains the given TimeInterval, otherwise false.

overlaps

public boolean overlaps(@Nonnull
 TimeInterval interval)

Checks if this TimeInterval overlaps the given interval.

Parameters:

interval - a given TimeInterval

Returns:

true if this TimeInterval overlaps the given interval, otherwise false

overlaps

public boolean overlaps(Collection<TimeInterval> intervals)

Checks if this TimeInterval overlaps with any of the given intervals.

Parameters:

intervals - a collection of TimeInterval

Returns:

true if this TimeInterval overlaps with any of the given intervals, otherwise false

overlaps

public boolean overlaps(@Nonnull
 YearMonth yearMonth)

Returns true if this TimeInterval overlaps with the given yearMonth, otherwise false.

Parameters:

yearMonth - a YearMonth

Returns:

true if this TimeInterval overlaps with the given yearMonth, otherwise false

anyOverlaps

public static boolean anyOverlaps(Collection<TimeInterval> intervals)

Returns true if any of the given intervals overlap with each other, otherwise false

Parameters:

intervals - a list of intervals

Returns:

true if any of the given intervals overlap with each other

relativeComplement

public List<TimeInterval> relativeComplement(Collection<TimeInterval> intervals)

Returns the list of the given intervals, excluding any elements equal to this interval

Parameters:

intervals - a list of intervals

Returns:

the result of removing any intervals equal to this interval

partiallyOverlaps

public boolean partiallyOverlaps(@Nonnull
 TimeInterval interval)

Checks if this TimeInterval partially overlaps the given interval, meaning that they overlap but neither contains the other.

Parameters:

interval - a given TimeInterval

Returns:

true if this TimeInterval overlaps the given interval and neither interval contains the other, otherwise false

getOverlap

public Optional<TimeInterval> getOverlap(@Nonnull
 TimeInterval interval)

Returns the overlap between this interval and the given interval, otherwise an empty Optional if there is no overlap

 This interval:
 |--------------------------------------|
 Input:
        |---------------|
 Output:
        |---------------|
 

Parameters:

interval - a given TimeInterval

Returns:

the overlap between this interval and the given interval, otherwise an empty Optional if there is no overlap

boundEnd

public Optional<TimeInterval> boundEnd(@Nullable
 LocalDateTime upperBound)

Returns a new version of this interval, where the end date is bounded according to the given upperBound. Equivalent to calling getOverlap(TimeInterval) with an interval starting from null and ending in upperBound.

Parameters:

upperBound - an interval defining the bounds to apply to this interval

Returns:

a new version of this interval, bounded according to given upperBound, or an empty Optional if the bounding results in an invalid interval

boundStart

public Optional<TimeInterval> boundStart(@Nullable
 LocalDateTime lowerBound)

Returns a new version of this interval, where the start date is bounded according to the given lowerBound Equivalent to calling getOverlap(TimeInterval) with an interval starting from lowerBound and ending in null.

Parameters:

lowerBound - a date defining the lower bound to apply to this interval

Returns:

a new version of this interval, bounded according to given lowerBound, or an empty Optional if the bounding results in an invalid interval

boundStartDateIfValid

public TimeInterval boundStartDateIfValid(@Nullable
 LocalDateTime lowerBound)

Returns a new version of this interval, where the start date is bounded according to boundStart(LocalDateTime). If the bounding results in an invalid interval, the original interval is returned.

Parameters:

lowerBound - a date defining the lower bound to apply to this interval.

Returns:

a new version of this interval, bounded according to given lowerBound, or the original interval if the bounding results in an invalid interval.

getOverlaps

public List<TimeInterval> getOverlaps(Collection<TimeInterval> intervals)

Returns a normalized (see normalize(Collection)) list of overlaps between the given intervals and this interval

 This interval:
 |--------------------------------|
 Input:
        |---------|           |------|
             |-------||--|
 Output:
        |----------------|    |---|
 

Parameters:

intervals - intervals to determine overlaps for

Returns:

a normalized list of overlaps between the given intervals and this interval

getOverlaps

public List<TimeInterval> getOverlaps(TimeInterval... intervals)

Vararg variant of getOverlaps(Collection)

Parameters:

intervals - intervals to determine overlaps for

Returns:

a normalized list of overlaps between the given intervals and this interval

getOverlaps

public List<TimeInterval> getOverlaps(Collection<TimeInterval> intervals,
 boolean mergeAdjacentIntervals)

Returns a normalized (see normalize(Collection)) list of overlaps between the given intervals and this interval Whether to merge adjacent overlaps is subject to the value of mergeAdjacentIntervals

 This interval:
 |--------------------------------|
 Input:
        |---------|           |------|
             |-------||--|
 Output:
        |----------------|    |---|      (if mergeAdjacentIntervals = true)
 or
        |------------||--|    |---|      (if mergeAdjacentIntervals = false)
 

Parameters:

intervals - intervals to determine overlaps for

mergeAdjacentIntervals - whether to merge adjacent overlaps

Returns:

a normalized list of overlaps between the given intervals and this interval

getNotOverlaps

public List<TimeInterval> getNotOverlaps(Collection<TimeInterval> intervals)

Returns a normalized list of the portions of intervals that do not overlap with this interval

 This interval:
                |---------------|
 Input:
        |---------|         |------|
             |---------|
 Output:
        |------|                 |-|
 

Parameters:

intervals - list of intervals

Returns:

the portions of intervals that do not overlap with this interval

getNotOverlaps

public List<TimeInterval> getNotOverlaps(TimeInterval... intervals)

Vararg variant of getNotOverlaps(Collection)

Parameters:

intervals - given intervals

Returns:

the portions of intervals that do not overlap with this interval

normalize

public static List<TimeInterval> normalize(Collection<TimeInterval> intervals)

Returns a sorted list of intervals, covering the same days as the input, but without any intervals overlapping. intervals that start just after the previous one ends will also be merged.

 Input:
 [-----------]    [-------------][------][----------------]    [---]
        [---------------]                    [---][---]
 Output:
 [--------------------------------------------------------]    [---]
 

Parameters:

intervals - collection of intervals to normalize

Returns:

normalized list of intervals

normalize

public static List<TimeInterval> normalize(Collection<TimeInterval> intervals,
 boolean mergeAdjacentIntervals)

Returns a sorted list of intervals, covering the same days as the input, but without any intervals overlapping.

 Input:
 [-----------]    [-------------][------][----------------]    [---]
        [---------------]                    [---][---]
 Output:
 [--------------------------------------------------------]    [---]   (if mergeAdjacentIntervals = true)
 or
 [------------------------------][------][----------------]    [---]   (if mergeAdjacentIntervals = false)
 

Parameters:

intervals - collection of intervals to normalize

mergeAdjacentIntervals - whether to merge adjacent intervals

Returns:

normalized list of intervals

adjacent

public boolean adjacent(@Nonnull
 TimeInterval interval)

Checks if the given TimeInterval is touching this interval.

Parameters:

interval - a given TimeInterval

Returns:

true if this interval ends on the day before the given interval starts or starts on the day after the given interval ends, otherwise false.

subtract

public List<TimeInterval> subtract(TimeInterval interval)

Returns the remainder of this interval, after subtracting the overlap with the given interval

 This:
 |---------------------------|
 Input:
        |----|
 Output:
 |-----|      |--------------|
 

Parameters:

interval - a given interval to subtract with

Returns:

list of Intervals after subtracting the given interval from this TimeInterval

subtract

public List<TimeInterval> subtract(Collection<TimeInterval> intervals)

Returns the remainder of this interval, after subtracting the overlap with the given intervals

 This:
 |---------------------------|
 Input:
        |----|    |---|
 Output:
 |-----|      |--|     |-----|
 

Parameters:

intervals - intervals to subtract with

Returns:

list of intervals after subtracting the given intervals from this TimeInterval

compareTo

public int compareTo(@Nonnull
 TimeInterval o)

Specified by:

compareTo in interface Comparable<TimeInterval>

toString

public final String toString()

Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.

Specified by:

toString in class Record

Returns:

a string representation of this object

hashCode

public final int hashCode()

Returns a hash code value for this object. The value is derived from the hash code of each of the record components.

Specified by:

hashCode in class Record

Returns:

a hash code value for this object

equals

public final boolean equals(Object o)

Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).

Specified by:

equals in class Record

Parameters:

o - the object with which to compare

Returns:

true if this object is the same as the o argument; false otherwise.

start

@Nullable
public LocalDateTime start()

Returns the value of the start record component.

Returns:

the value of the start record component

end

@Nullable
public LocalDateTime end()

Returns the value of the end record component.

Returns:

the value of the end record component