Package com.thanlinardos.spring_enterprise_library.time.model

Record Class InstantInterval

java.lang.Object

java.lang.Record

com.thanlinardos.spring_enterprise_library.time.model.InstantInterval

Record Components:

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

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

All Implemented Interfaces:

Comparable<InstantInterval>

public record InstantInterval(@Nullable Instant start, @Nullable Instant end)
extends Record
implements Comparable<InstantInterval>

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

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
boolean	adjacent(InstantInterval interval)	Checks if the given InstantInterval is touching this interval.
static boolean	anyOverlaps(Collection<InstantInterval> intervals)	Returns true if any of the given intervals overlap with each other, otherwise false
Optional<InstantInterval>	boundEnd(Instant upperBound)	Returns a new version of this InstantInterval, where the end date is bounded according to the given upperBound.
Optional<InstantInterval>	boundStart(Instant lowerBound)	Returns a new version of this InstantInterval, where the start date is bounded according to the given lowerBound Equivalent to calling getOverlap(InstantInterval) with an InstantInterval starting from lowerBound and ending in null.
InstantInterval	boundStartDateIfValid(Instant lowerBound)	Returns a new version of this InstantInterval, where the start date is bounded according to boundStart(Instant).
int	compareTo(InstantInterval o)
boolean	contains(InstantInterval interval)	Checks if the given InstantInterval is fully contained within this InstantInterval.
boolean	contains(Instant instant)	Checks if the given instant is contained within this InstantInterval.
boolean	contains(YearMonth yearMonth)	Checks if the given InstantInterval is fully contained within this InstantInterval.
boolean	containsNullAsMax(Instant instant)	Checks if the given instant is contained within this InstantInterval, treating null as MAX_INSTANT.
boolean	containsNullAsMin(Instant instant)	Checks if the given instant is contained within this InstantInterval, treating null as MIN_INSTANT.
Instant	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 InstantInterval	forIsoDates(String startDate, String endDate)	Constructs an InstantInterval using ISO 8601 formatted dates (such as "2007-12-03").
static InstantInterval	forIsoDates(String startDate, String endDate, TimeUnit accuracy, ZoneOffset zoneOffset)	Constructs an InstantInterval using ISO 8601 formatted dates (such as "2007-12-03").
static InstantInterval	forIsoDatesMilliUTC(String startDate, String endDate)	Constructs an InstantInterval same as in forIsoDates(String, String, TimeUnit, ZoneOffset), but using milliseconds accuracy and UTC zoneOffset.
static InstantInterval	forIsoInstants(String start, String end)	Constructs an InstantInterval using ISO 8601 formatted Instants (such as "2007-12-03T10:15:30.00Z").
static InstantInterval	forIsoMonth(String month)	Constructs an InstantInterval using a ISO 8601 formatted month ("YYYY-MM").
static InstantInterval	forIsoYear(int year)	Constructs an InstantInterval using a year.
static InstantInterval	fromIsoDateToNullMilliUTC(String startDate)	Constructs an InstantInterval same as in forIsoDates(String, String, TimeUnit, ZoneOffset), but using milliseconds accuracy and UTC zoneOffset, and with a null end date.
Instant	getEndNullAsMax()	Returns the end Instant, or the maximum Instant if the end is null.
List<InstantInterval>	getNotOverlaps(InstantInterval... intervals)	Vararg variant of getNotOverlaps(Collection)
List<InstantInterval>	getNotOverlaps(Collection<InstantInterval> intervals)	Returns a normalized list of the portions of intervals that do not overlap with this InstantInterval
Optional<InstantInterval>	getOverlap(InstantInterval interval)	Returns the overlap between this interval and the given interval, otherwise an empty Optional if there is no overlap
List<InstantInterval>	getOverlaps(InstantInterval... intervals)	Vararg variant of getOverlaps(Collection)
List<InstantInterval>	getOverlaps(Collection<InstantInterval> intervals)	Returns a normalized (see normalize(Collection)) list of overlaps between the given intervals and this InstantInterval
List<InstantInterval>	getOverlaps(Collection<InstantInterval> intervals, boolean mergeAdjacentIntervals)	Returns a normalized (see normalize(Collection)) list of overlaps between the given intervals and this InstantInterval Whether to merge adjacent overlaps is subject to the value of mergeAdjacentIntervals
Instant	getStartNullAsMin()	Returns the start Instant, or the minimum Instant if the start is null.
final int	hashCode()	Returns a hash code value for this object.
static boolean	isNotValid(Instant start, Instant end)	Validates whether the start Instant is before or equal to the end Instant.
static boolean	isValid(Instant start, Instant end)	Validates whether the start Instant is before or equal to the end Instant.
static List<InstantInterval>	normalize(Collection<InstantInterval> intervals)	Returns a sorted list of intervals, covering the same days as the input, but without any intervals overlapping.
static List<InstantInterval>	normalize(Collection<InstantInterval> intervals, boolean mergeAdjacentIntervals)	Returns a sorted list of intervals, covering the same days as the input, but without any intervals overlapping.
boolean	overlaps(InstantInterval interval)	Checks if this InstantInterval overlaps the given interval.
boolean	overlaps(YearMonth yearMonth)	Returns true if this InstantInterval overlaps with the given yearMonth, otherwise false.
boolean	overlaps(Collection<InstantInterval> intervals)	Returns true if this InstantInterval overlaps with any of the given intervals, otherwise false.
boolean	partiallyOverlaps(InstantInterval interval)	Checks if this InstantInterval partially overlaps the given interval, meaning that they overlap but neither contains the other.
List<InstantInterval>	relativeComplement(Collection<InstantInterval> intervals)	Returns the list of the given intervals, excluding any elements equal to this InstantInterval
static List<InstantInterval>	split(Collection<InstantInterval> intervals)	Returns a sorted list of intervals, covering the same Instants as the input, but without any intervals overlapping.
Instant	start()	Returns the value of the start record component.
List<InstantInterval>	subtract(InstantInterval interval)	Returns the remainder of this interval, after subtracting the overlap with the given interval.
List<InstantInterval>	subtract(Collection<InstantInterval> intervals)	Returns the remainder of this InstantInterval, 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

InstantInterval

public InstantInterval(@Nullable
 Instant start,
 @Nullable
 Instant end)

Constructs an InstantInterval with the given start and end dates.

Parameters:

start - the start date of the InstantInterval (nullable)

end - the end date of the InstantInterval (nullable)

Throws:

IllegalArgumentException - if the start date is after the end date

InstantInterval

public InstantInterval(LocalDate date)

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

Parameters:

date - the LocalDate to create the InstantInterval for.

InstantInterval

public InstantInterval(LocalDate startDate,
 LocalDate endDate)

Constructs an InstantInterval for the given start and end LocalDates.

Parameters:

startDate - the start LocalDate to create the InstantInterval for.

endDate - the end LocalDate to create the InstantInterval for.

InstantInterval

public InstantInterval(LocalDate startDate,
 LocalDate endDate,
 TimeUnit accuracy,
 ZoneOffset zoneOffset)

Constructs an InstantInterval for the given start and end LocalDates.

Parameters:

startDate - the start LocalDate to create the InstantInterval for.

endDate - the end LocalDate to create the InstantInterval for.

accuracy - the accuracy to use when converting LocalDate to Instant.

zoneOffset - the zoneOffset to use when converting LocalDate to Instant.

InstantInterval

public InstantInterval(Interval interval)

Constructs an InstantInterval for the given Interval.

Parameters:

interval - the Interval to create the InstantInterval for.

InstantInterval

public InstantInterval(YearMonth yearMonth)

Constructs an InstantInterval for the given YearMonth.

Parameters:

yearMonth - the YearMonth to create the InstantInterval for.

InstantInterval

public InstantInterval(Year year)

Constructs an InstantInterval for the given Year.

Parameters:

year - the Year to create the InstantInterval for.

Method Details

isNotValid

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

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

Parameters:

start - the start Instant

end - the end Instant

Returns:

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

isValid

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

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

Parameters:

start - the start Instant.

end - the end Instant.

Returns:

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

forIsoInstants

public static InstantInterval forIsoInstants(@Nullable
 String start,
 @Nullable
 String end)

Constructs an InstantInterval using ISO 8601 formatted Instants (such as "2007-12-03T10:15:30.00Z"). The format is further specified in DateTimeFormatter.ISO_INSTANT.

Parameters:

start - start of the InstantInterval (inclusive).

end - end of the InstantInterval (inclusive).

Returns:

an InstantInterval based on the given Instants.

forIsoDates

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

Constructs an InstantInterval using ISO 8601 formatted dates (such as "2007-12-03"). The format is further specified in DateTimeFormatter.ISO_LOCAL_DATE.

Parameters:

startDate - the start date (inclusive).

endDate - the end date (inclusive).

Returns:

an InstantInterval based on the given dates.

forIsoDates

public static InstantInterval forIsoDates(@Nullable
 String startDate,
 @Nullable
 String endDate,
 TimeUnit accuracy,
 ZoneOffset zoneOffset)

Constructs an InstantInterval using ISO 8601 formatted dates (such as "2007-12-03"). The format is further specified in DateTimeFormatter.ISO_LOCAL_DATE. The given accuracy and zoneOffset parameters are used to override the defaults from TimeFactory.

Parameters:

startDate - the start date (inclusive).

endDate - the end date (inclusive).

accuracy - the accuracy to use when converting LocalDate to Instant.

zoneOffset - the zoneOffset to use when converting LocalDate to Instant.

Returns:

an InstantInterval based on the given dates.

forIsoDatesMilliUTC

public static InstantInterval forIsoDatesMilliUTC(@Nullable
 String startDate,
 @Nullable
 String endDate)

Constructs an InstantInterval same as in forIsoDates(String, String, TimeUnit, ZoneOffset), but using milliseconds accuracy and UTC zoneOffset.

Parameters:

startDate - the start date (inclusive).

endDate - the end date (inclusive).

Returns:

an InstantInterval based on the given dates.

fromIsoDateToNullMilliUTC

public static InstantInterval fromIsoDateToNullMilliUTC(@Nullable
 String startDate)

Constructs an InstantInterval same as in forIsoDates(String, String, TimeUnit, ZoneOffset), but using milliseconds accuracy and UTC zoneOffset, and with a null end date.

Parameters:

startDate - the start date (inclusive).

Returns:

an open-ended InstantInterval based on the given start date.

forIsoMonth

public static InstantInterval forIsoMonth(@Nonnull
 String month)

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

Parameters:

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

Returns:

an InstantInterval based on the given month

forIsoYear

public static InstantInterval forIsoYear(int year)

Constructs an InstantInterval using a year.

Parameters:

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

Returns:

an InstantInterval based on the given year

getStartNullAsMin

public Instant getStartNullAsMin()

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

Returns:

the start Instant or MIN_INSTANT

getEndNullAsMax

public Instant getEndNullAsMax()

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

Returns:

the end Instant or MAX_INSTANT

split

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

Returns a sorted list of intervals, covering the same Instants 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
 Instant instant)

Checks if the given instant is contained within this InstantInterval, treating null as MIN_INSTANT.

Parameters:

instant - the instant to check

Returns:

true if the instant is contained, false otherwise

containsNullAsMax

public boolean containsNullAsMax(@Nullable
 Instant instant)

Checks if the given instant is contained within this InstantInterval, treating null as MAX_INSTANT.

Parameters:

instant - the instant to check

Returns:

true if the instant is contained, false otherwise

contains

public boolean contains(@Nonnull
 Instant instant)

Checks if the given instant is contained within this InstantInterval.

Parameters:

instant - the instant to check.

Returns:

true if the instant is contained, false otherwise.

contains

public boolean contains(@Nonnull
 YearMonth yearMonth)

Checks if the given InstantInterval is fully contained within this InstantInterval.

Parameters:

yearMonth - a given YearMonth.

Returns:

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

contains

public boolean contains(@Nonnull
 InstantInterval interval)

Checks if the given InstantInterval is fully contained within this InstantInterval.

Parameters:

interval - a given InstantInterval.

Returns:

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

overlaps

public boolean overlaps(@Nonnull
 InstantInterval interval)

Checks if this InstantInterval overlaps the given interval.

Parameters:

interval - a given InstantInterval

Returns:

true if this InstantInterval overlaps the given interval, otherwise false

overlaps

public boolean overlaps(Collection<InstantInterval> intervals)

Returns true if this InstantInterval overlaps with any of the given intervals, otherwise false.

Parameters:

intervals - a collection of InstantInterval

Returns:

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

overlaps

public boolean overlaps(@Nonnull
 YearMonth yearMonth)

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

Parameters:

yearMonth - a YearMonth

Returns:

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

anyOverlaps

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

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

Parameters:

intervals - a list of intervals

Returns:

the result of removing any intervals equal to this InstantInterval

partiallyOverlaps

public boolean partiallyOverlaps(@Nonnull
 InstantInterval interval)

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

Parameters:

interval - a given InstantInterval

Returns:

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

getOverlap

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

Returns:

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

boundEnd

public Optional<InstantInterval> boundEnd(@Nullable
 Instant upperBound)

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

Parameters:

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

Returns:

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

boundStart

public Optional<InstantInterval> boundStart(@Nullable
 Instant lowerBound)

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

Parameters:

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

Returns:

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

boundStartDateIfValid

public InstantInterval boundStartDateIfValid(@Nullable
 Instant lowerBound)

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

Parameters:

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

Returns:

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

getOverlaps

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

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

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

Parameters:

intervals - intervals to determine overlaps for

Returns:

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

getOverlaps

public List<InstantInterval> getOverlaps(InstantInterval... 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 InstantInterval

getOverlaps

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

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

 This InstantInterval:
 |--------------------------------|
 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 InstantInterval

getNotOverlaps

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

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

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

Parameters:

intervals - list of intervals

Returns:

the portions of intervals that do not overlap with this InstantInterval

getNotOverlaps

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

Vararg variant of getNotOverlaps(Collection)

Parameters:

intervals - given intervals

Returns:

the portions of intervals that do not overlap with this InstantInterval

normalize

public static List<InstantInterval> normalize(Collection<InstantInterval> 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<InstantInterval> normalize(Collection<InstantInterval> 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
 InstantInterval interval)

Checks if the given InstantInterval is touching this interval.

Parameters:

interval - a given InstantInterval

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<InstantInterval> subtract(InstantInterval 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 InstantInterval

subtract

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

Returns the remainder of this InstantInterval, 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 InstantInterval

compareTo

public int compareTo(@Nonnull
 InstantInterval o)

Specified by:

compareTo in interface Comparable<InstantInterval>

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

Returns the value of the start record component.

Returns:

the value of the start record component

end

@Nullable
public Instant end()

Returns the value of the end record component.

Returns:

the value of the end record component