Package com.thanlinardos.spring_enterprise_library.time.model

Record Class Interval

java.lang.Object

java.lang.Record

com.thanlinardos.spring_enterprise_library.time.model.Interval

Record Components:

start - the start date of the interval (nullable).

end - the end date of the interval (nullable).

All Implemented Interfaces:

DateTemporal, Comparable<Interval>

public record Interval(@Nullable LocalDate start, @Nullable LocalDate end)
extends Record
implements Comparable<Interval>, DateTemporal

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

Constructor Summary

Constructors

Constructor	Description
Interval(LocalDate start, LocalDate end)	Constructs an Interval with the given start and end dates.
Interval(Year year)	Constructs an Interval for the given Year.
Interval(YearMonth yearMonth)	Constructs an Interval for the given YearMonth.

Method Summary

Modifier and Type	Method	Description
boolean	adjacent(Interval interval)	Checks if the given Interval is touching this Interval.
static boolean	anyOverlaps(Collection<Interval> intervals)	Returns true if any of the given intervals overlap with each other, otherwise false.
Optional<Interval>	boundEndDate(LocalDate upperBound)	Returns a new version of this interval, where the end date is bounded according to the given upperBound.
Optional<Interval>	boundStartDate(LocalDate lowerBound)	Returns a new version of this interval, where the start date is bounded according to the given lowerBound.
Interval	boundStartDateIfValid(LocalDate lowerBound)	Returns a new version of this interval, where the start date is bounded according to boundStartDate(LocalDate).
int	compareTo(Interval o)
boolean	contains(Interval interval)	Checks if this Interval fully contains the given Interval.
boolean	contains(LocalDate date)	Checks if the given date is contained within this interval.
boolean	contains(YearMonth yearMonth)	Returns true if this Interval fully contains the given yearMonth, otherwise false.
boolean	containsNullAsMax(LocalDate date)	Checks if the given date is contained within this interval, treating null as MAX_DATE.
boolean	containsNullAsMin(LocalDate date)	Checks if the given date is contained within this interval, treating null as MIN_DATE.
LocalDate	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 Interval	forIsoDates(String startDate, String endDate)	Constructs an Interval using ISO 8601 formatted dates ("YYYY-MM-DD").
static Interval	forIsoMonth(String month)	Constructs an Interval using a ISO 8601 formatted month ("YYYY-MM").
static Interval	forIsoYear(int year)	Constructs an Interval using a year.
LocalDate	getEndNullAsMax()	Returns the end date, or the maximum date if the end is null.
Interval	getInterval()	Gets the date interval of the temporal entity.
List<Interval>	getNotOverlaps(Interval... intervals)	Vararg variant of getNotOverlaps(Collection).
List<Interval>	getNotOverlaps(Collection<Interval> intervals)	Returns a normalized list of the portions of intervals that do not overlap with this interval.
Optional<Interval>	getOverlap(Interval interval)	Returns the overlap between this Interval and the given interval, otherwise an empty Optional if there is no overlap.
List<Interval>	getOverlaps(Interval... intervals)	Vararg variant of getOverlaps(Collection)
List<Interval>	getOverlaps(Collection<Interval> intervals)	Returns a normalized (see normalize(Collection)) list of overlaps between the given intervals and this interval.
List<Interval>	getOverlaps(Collection<Interval> intervals, boolean mergeAdjacentIntervals)	Returns a normalized (see normalize(Collection)) list of overlaps between the given intervals and this interval.
LocalDate	getStartNullAsMin()	Returns the start date, or the minimum date if the start is null.
final int	hashCode()	Returns a hash code value for this object.
static boolean	isNotValid(LocalDate start, LocalDate end)	Validates whether the start date is before or equal to the end date.
static boolean	isValid(LocalDate start, LocalDate end)	Validates whether the start date is before or equal to the end date.
static List<Interval>	normalize(Collection<Interval> intervals)	Returns a sorted list of intervals, covering the same days as the input, but without any intervals overlapping.
static List<Interval>	normalize(Collection<Interval> intervals, boolean mergeAdjacentIntervals)	Returns a sorted list of intervals, covering the same days as the input, but without any intervals overlapping.
boolean	overlaps(Interval interval)	Checks if this Interval overlaps the given Interval.
boolean	overlaps(Year year)	Returns true if this Interval overlaps with the given year, otherwise false.
boolean	overlaps(YearMonth yearMonth)	Returns true if this Interval overlaps with the given yearMonth, otherwise false.
boolean	overlaps(Collection<Interval> intervals)	Checks if this Interval overlaps with any of the given intervals, otherwise false.
boolean	partiallyOverlaps(Interval interval)	Checks if this Interval partially overlaps the given Interval, meaning they overlap but neither contains the other.
List<Interval>	relativeComplement(Collection<Interval> intervals)	Returns the list of the given intervals, excluding any elements equal to this interval.
static List<Interval>	split(Collection<Interval> intervals)	Returns a sorted list of intervals, covering the same days as the input, but without any intervals overlapping.
LocalDate	start()	Returns the value of the start record component.
List<Interval>	subtract(Interval interval)	Returns the remainder of this interval, after subtracting the overlap with the given interval.
List<Interval>	subtract(Collection<Interval> 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

Methods inherited from interface com.thanlinardos.spring_enterprise_library.time.api.DateTemporal

containsDate, containsInterval, containsMonth, endsAfter, endsAfterOrOn, equalsInterval, isContainedIn, isContainedIn, isInRange, overlapsInterval, overlapsInterval, overlapsMonth, overlapsYear, overlapsYear, startsAfter, startsBefore, startsBeforeOrOn

Constructor Details

Interval

public Interval(@Nullable
 LocalDate start,
 @Nullable
 LocalDate 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

Interval

public Interval(YearMonth yearMonth)

Constructs an Interval for the given YearMonth.

Parameters:

yearMonth - the YearMonth to create the interval for.

Interval

public Interval(Year year)

Constructs an Interval for the given Year.

Parameters:

year - the Year to create the interval for.

Method Details

getInterval

public Interval getInterval()

Description copied from interface: DateTemporal

Gets the date interval of the temporal entity.

Specified by:

getInterval in interface DateTemporal

Returns:

the date interval.

isNotValid

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

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

Parameters:

start - the start date

end - the end date

Returns:

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

isValid

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

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

Parameters:

start - the start date.

end - the end date.

Returns:

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

forIsoDates

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

Constructs an Interval using ISO 8601 formatted dates ("YYYY-MM-DD").

Parameters:

startDate - start of the interval (inclusive).

endDate - end of the interval (inclusive).

Returns:

an Interval based on the given dates.

forIsoMonth

public static Interval forIsoMonth(@Nonnull
 String month)

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

Parameters:

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

Returns:

an Interval based on the given month

forIsoYear

public static Interval forIsoYear(int year)

Constructs an Interval using a year.

Parameters:

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

Returns:

an Interval based on the given year

getStartNullAsMin

public LocalDate getStartNullAsMin()

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

Returns:

the start date or MIN_DATE

getEndNullAsMax

public LocalDate getEndNullAsMax()

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

Returns:

the end date or MAX_DATE

split

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

Returns a sorted list of intervals, covering the same days 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
 LocalDate date)

Checks if the given date is contained within this interval, treating null as MIN_DATE.

Parameters:

date - the date to check

Returns:

true if the date is contained, false otherwise

containsNullAsMax

public boolean containsNullAsMax(@Nullable
 LocalDate date)

Checks if the given date is contained within this interval, treating null as MAX_DATE.

Parameters:

date - the date to check

Returns:

true if the date is contained, false otherwise

contains

public boolean contains(@Nonnull
 LocalDate date)

Checks if the given date is contained within this interval.

Parameters:

date - the date to check.

Returns:

true if the date is contained, false otherwise.

contains

public boolean contains(@Nonnull
 YearMonth yearMonth)

Returns true if this Interval fully contains the given yearMonth, otherwise false.

Parameters:

yearMonth - a YearMonth

Returns:

true if this Interval fully contains the given yearMonth, otherwise false

contains

public boolean contains(@Nonnull
 Interval interval)

Checks if this Interval fully contains the given Interval.

Parameters:

interval - a given Interval

Returns:

true if this Interval fully contains the given Interval, otherwise false

overlaps

public boolean overlaps(@Nonnull
 Interval interval)

Checks if this Interval overlaps the given Interval.

Parameters:

interval - a given Interval

Returns:

true if this Interval overlaps the given Interval, otherwise false

overlaps

public boolean overlaps(Collection<Interval> intervals)

Checks if this Interval overlaps with any of the given intervals, otherwise false.

Parameters:

intervals - a collection of Interval

Returns:

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

overlaps

public boolean overlaps(@Nonnull
 YearMonth yearMonth)

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

Parameters:

yearMonth - a YearMonth

Returns:

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

overlaps

public boolean overlaps(@Nonnull
 Year year)

Returns true if this Interval overlaps with the given year, otherwise false.

Parameters:

year - a Year

Returns:

true if this Interval overlaps with the given year, otherwise false.

anyOverlaps

public static boolean anyOverlaps(Collection<Interval> 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<Interval> relativeComplement(Collection<Interval> 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
 Interval interval)

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

Parameters:

interval - a given Interval

Returns:

true if this Interval overlaps the given Interval and neither Interval contains the other, otherwise false.

getOverlap

public Optional<Interval> getOverlap(@Nonnull
 Interval 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 Interval

Returns:

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

boundEndDate

public Optional<Interval> boundEndDate(@Nullable
 LocalDate upperBound)

Returns a new version of this interval, where the end date is bounded according to the given upperBound. Equivalent to calling getOverlap(Interval) 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

boundStartDate

public Optional<Interval> boundStartDate(@Nullable
 LocalDate lowerBound)

Returns a new version of this interval, where the start date is bounded according to the given lowerBound. Equivalent to calling getOverlap(Interval) 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 Interval boundStartDateIfValid(@Nullable
 LocalDate lowerBound)

Returns a new version of this interval, where the start date is bounded according to boundStartDate(LocalDate). 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<Interval> getOverlaps(Collection<Interval> 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<Interval> getOverlaps(Interval... 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<Interval> getOverlaps(Collection<Interval> 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<Interval> getNotOverlaps(Collection<Interval> 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<Interval> getNotOverlaps(Interval... 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<Interval> normalize(Collection<Interval> 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<Interval> normalize(Collection<Interval> 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
 Interval interval)

Checks if the given Interval is touching this Interval.

Parameters:

interval - a given Interval

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<Interval> subtract(Interval 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 Interval.

subtract

public List<Interval> subtract(Collection<Interval> 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 Interval.

compareTo

public int compareTo(@Nonnull
 Interval o)

Specified by:

compareTo in interface Comparable<Interval>

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 LocalDate start()

Returns the value of the start record component.

Returns:

the value of the start record component

end

@Nullable
public LocalDate end()

Returns the value of the end record component.

Returns:

the value of the end record component