net.time4j.range

Class IntervalTree<T,I extends ChronoInterval<T>>

java.lang.Object

java.util.AbstractCollection<I>

net.time4j.range.IntervalTree<T,I>

Type Parameters:

T - the temporal type of time points in intervals

I - the type of intervals stored in the tree

All Implemented Interfaces:

Iterable<I>, Collection<I>

public class IntervalTree<T,I extends ChronoInterval<T>>
extends AbstractCollection<I>

Represents an augmented interval tree holding intervals for easy and quick search.

The semantics of augmented interval trees (AVL-trees) is described for example in Wikipedia. Empty intervals are never stored. An interval tree is also like a read-only collection of intervals.

Since:

3.25/4.21

Author:

Meno Hochschild

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	IntervalTree.Visitor<I> Callback interface for tree traversal according to the visitor pattern design.

Method Summary

Modifier and Type	Method and Description
void	accept(IntervalTree.Visitor<I> visitor) Accepts given interval tree visitor.
boolean	contains(ChronoInterval<T> interval) Queries if given interval is stored in this tree.
List<I>	findIntersections(ChronoInterval<T> interval) Obtains a list of all stored intervals which intersect given search interval.
List<I>	findIntersections(T timepoint) Obtains a list of all stored intervals which intersect given point in time.
boolean	isEmpty() Checks if this tree contains no intervals.
Iterator<I>	iterator() Collects all stored intervals into a new list and then obtains an iterator for this list.
static <T,I extends ChronoInterval<T>> IntervalTree<T,I>	on(TimeLine<T> timeLine, Collection<I> intervals) Creates an interval tree on a timeline filled with given intervals.
static <I extends ChronoInterval<PlainTime>> IntervalTree<PlainTime,I>	onClockAxis(Collection<I> intervals) Creates an interval tree on the clock axis filled with given clock intervals.
static <I extends ChronoInterval<PlainDate>> IntervalTree<PlainDate,I>	onDateAxis(Collection<I> intervals) Creates an interval tree on the date axis filled with given date intervals.
static IntervalTree<Instant,SimpleInterval<Instant>>	onInstantTimeLine(Collection<SimpleInterval<Instant>> intervals) Creates an interval tree for the type java.time.Instant filled with given simple intervals.
static <I extends ChronoInterval<Moment>> IntervalTree<Moment,I>	onMomentAxis(Collection<I> intervals) Creates an interval tree on the moment axis (UTC) filled with given moment intervals.
static <I extends ChronoInterval<PlainTimestamp>> IntervalTree<PlainTimestamp,I>	onTimestampAxis(Collection<I> intervals) Creates an interval tree on the timestamp axis filled with given timestamp intervals.
static IntervalTree<Date,SimpleInterval<Date>>	onTraditionalTimeLine(Collection<SimpleInterval<Date>> intervals) Creates an interval tree for the legacy type java.util.Date filled with given simple intervals.
int	size() Obtains the count of stored intervals.

Methods inherited from class java.util.AbstractCollection

add, addAll, clear, contains, containsAll, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

equals, hashCode, parallelStream, removeIf, spliterator, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

onDateAxis

public static <I extends ChronoInterval<PlainDate>> IntervalTree<PlainDate,I> onDateAxis(Collection<I> intervals)

Creates an interval tree on the date axis filled with given date intervals.

Type Parameters:

I - the type of intervals stored in the tree

Parameters:

intervals - collection of date intervals

Returns:

new interval tree

Throws:

ArithmeticException - if the count of intervals overflows an int

onClockAxis

public static <I extends ChronoInterval<PlainTime>> IntervalTree<PlainTime,I> onClockAxis(Collection<I> intervals)

Creates an interval tree on the clock axis filled with given clock intervals.

Type Parameters:

I - the type of intervals stored in the tree

Parameters:

intervals - collection of clock intervals

Returns:

new interval tree

Throws:

ArithmeticException - if the count of intervals overflows an int

onTimestampAxis

public static <I extends ChronoInterval<PlainTimestamp>> IntervalTree<PlainTimestamp,I> onTimestampAxis(Collection<I> intervals)

Creates an interval tree on the timestamp axis filled with given timestamp intervals.

Type Parameters:

I - the type of intervals stored in the tree

Parameters:

intervals - collection of timestamp intervals

Returns:

new interval tree

Throws:

ArithmeticException - if the count of intervals overflows an int

onMomentAxis

public static <I extends ChronoInterval<Moment>> IntervalTree<Moment,I> onMomentAxis(Collection<I> intervals)

Creates an interval tree on the moment axis (UTC) filled with given moment intervals.

Type Parameters:

I - the type of intervals stored in the tree

Parameters:

intervals - collection of moment intervals

Returns:

new interval tree

Throws:

ArithmeticException - if the count of intervals overflows an int

onTraditionalTimeLine

public static IntervalTree<Date,SimpleInterval<Date>> onTraditionalTimeLine(Collection<SimpleInterval<Date>> intervals)

Creates an interval tree for the legacy type java.util.Date filled with given simple intervals.

Parameters:

intervals - collection of simple intervals

Returns:

new interval tree

Throws:

ArithmeticException - if the count of intervals overflows an int

onInstantTimeLine

public static IntervalTree<Instant,SimpleInterval<Instant>> onInstantTimeLine(Collection<SimpleInterval<Instant>> intervals)

Creates an interval tree for the type java.time.Instant filled with given simple intervals.

Parameters:

intervals - collection of simple intervals

Returns:

new interval tree

Throws:

ArithmeticException - if the count of intervals overflows an int

on

public static <T,I extends ChronoInterval<T>> IntervalTree<T,I> on(TimeLine<T> timeLine,
                                                                   Collection<I> intervals)

Creates an interval tree on a timeline filled with given intervals.

Type Parameters:

T - the temporal type of time points in intervals

I - the type of intervals stored in the tree

Parameters:

timeLine - the underlying timeline

intervals - collection of intervals

Returns:

new interval tree

Throws:

ArithmeticException - if the count of intervals overflows an int

Since:

5.0

See Also:

TimeAxis, CalendarFamily.getTimeLine(String), CalendarFamily.getTimeLine(net.time4j.engine.VariantSource), CalendarYear.timeline(), CalendarQuarter.timeline(), CalendarMonth.timeline(), CalendarWeek.timeline()

isEmpty

public boolean isEmpty()

Checks if this tree contains no intervals.

Specified by:

isEmpty in interface Collection<I extends ChronoInterval<T>>

Overrides:

isEmpty in class AbstractCollection<I extends ChronoInterval<T>>

Returns:

true if empty else false

iterator

public Iterator<I> iterator()

Collects all stored intervals into a new list and then obtains an iterator for this list.

This method is only useful if users really want to iterate over all stored intervals. Otherwise a customized Visitor-implementation is more flexible.

Specified by:

iterator in interface Iterable<I extends ChronoInterval<T>>

Specified by:

iterator in interface Collection<I extends ChronoInterval<T>>

Specified by:

iterator in class AbstractCollection<I extends ChronoInterval<T>>

Returns:

an Iterator which is read-only

size

public int size()

Obtains the count of stored intervals.

Specified by:

size in interface Collection<I extends ChronoInterval<T>>

Specified by:

size in class AbstractCollection<I extends ChronoInterval<T>>

Returns:

int

findIntersections

public List<I> findIntersections(T timepoint)

Obtains a list of all stored intervals which intersect given point in time.

Parameters:

timepoint - the point in time to be checked

Returns:

unmodifiable list of all stored intervals which contain given point in time, maybe empty

findIntersections

public List<I> findIntersections(ChronoInterval<T> interval)

Obtains a list of all stored intervals which intersect given search interval.

Parameters:

interval - the search interval

Returns:

unmodifiable list of all stored intervals which intersect the search interval, maybe empty

contains

public boolean contains(ChronoInterval<T> interval)

Queries if given interval is stored in this tree.

Parameters:

interval - the interval to be checked

Returns:

boolean

accept

public void accept(IntervalTree.Visitor<I> visitor)

Accepts given interval tree visitor.

All nodes will be visited in ascending order, first sorted by start then by end.

Example:

     DateInterval i1 = DateInterval.between(PlainDate.of(2014, 2, 28), PlainDate.of(2014, 5, 31));
     DateInterval i2 = DateInterval.between(PlainDate.of(2014, 5, 31), PlainDate.of(2014, 6, 1));
     DateInterval i3 = DateInterval.between(PlainDate.of(2014, 6, 15), PlainDate.of(2014, 6, 30));
     IntervalTree<PlainDate, DateInterval> tree = IntervalTree.onDateAxis(Arrays.asList(i3, i1, i2));

     tree.accept(
       (interval) -> {
         System.out.println(interval);
         return false;
       }
     );

     // output:
     [2014-02-28/2014-05-31]
     [2014-05-31/2014-06-01]
     [2014-06-15/2014-06-30]
 

Parameters:

visitor - the interval tree visitor