de.xima.fc.utils.range

Class RangeUtils

java.lang.Object

de.xima.fc.utils.range.RangeUtils

public class RangeUtils
extends Object

Utilities with additional methods on Ranges.

Author:

XIMA MEDIA GmbH

Field Summary

Fields

Modifier and Type	Field and Description
static Comparator<com.google.common.collect.Range>	LOWER_ENDPOINT_COMPARATOR An EndpointTypeComparator for comparing the lower end points of a range.
static Comparator<com.google.common.collect.Range>	UPPER_ENDPOINT_COMPARATOR An EndpointTypeComparator for comparing the upper end points of a range.

Method Summary

Modifier and Type	Method and Description
static <T,C extends Comparable> int	compareByEndpoint(T lhs, EndpointAccessor<T,C> lhsEndpoint, T rhs, EndpointAccessor<T,C> rhsEndpoint) Compares to endpoints of a range.
static <T,C extends Comparable> int	compareByEndpoint(T lhs, EndpointAccessor<T,C> lhsEndpoint, T rhs, EndpointAccessor<T,C> rhsEndpoint, EndpointTypeComparator comparator) Compares to endpoints of a range.
static <C extends Comparable> com.google.common.collect.Range<C>	createClosedRange(C lower, C upper) Creates an open range from two end points.
static <C extends Comparable> com.google.common.collect.Range<C>	createOpenRange(C lower, C upper) Creates a closed range from two end points.
static <C extends Comparable> com.google.common.collect.Range<C>	createRange(C lower, EndpointDescriptor lowerDesc, C upper, EndpointDescriptor upperDesc) Creates a range from two end points.
static <T,C extends Comparable> com.google.common.collect.Range<C>	createRange(T lhs, EndpointAccessor<T,C> lhsEndpoint, T rhs, EndpointAccessor<T,C> rhsEndpoint) Creates a range from two end points.
static <T extends Comparable> Iterable<T>	eachPointInRange(com.google.common.collect.Range<T> range, UnaryOperator<T> nextItem) Splits the given range into a sequence of points, starting at the lower endpoint of the range.
static <T extends Comparable> Iterable<T>	eachPointInRange(com.google.common.collect.Range<T> range, UnaryOperator<T> nextItem, boolean includeTail) Splits the given range into a sequence of points, starting at the lower endpoint of the range.
static <C extends Comparable> Iterable<com.google.common.collect.Range<C>>	eachSubrange(com.google.common.collect.Range<C> range, com.google.common.collect.BoundType boundType, boolean includeTail, UnaryOperator<C> nextItem) Splits the given range into a sequence of connected ranges, starting at the lower endpoint of the interval.
static <C extends Comparable> Iterable<com.google.common.collect.Range<C>>	eachSubrange(com.google.common.collect.Range<C> range, com.google.common.collect.BoundType boundType, UnaryOperator<C> nextItem) Splits the given range into a sequence of touching ranges, starting at the lower endpoint of the interval.
static <T,C extends Comparable> List<org.apache.commons.lang3.tuple.Pair<Integer,T>>	findOverlappingDepth(List<T> items, Function<T,com.google.common.collect.Range<C>> rangeAccessor, EndpointTypeComparator comparator) Finds the overlapping depth of each given range.
static <C extends Comparable> boolean	hasNonZeroOverlap(com.google.common.collect.Range<C> lhs, com.google.common.collect.Range<C> rhs) Checks whether the two given ranges have any overlap that has a length greater than zero, e.g. contains more than a single point.
static <C extends Comparable> boolean	hasNonZeroOverlap(com.google.common.collect.RangeSet<C> ranges, com.google.common.collect.Range<C> range) Checks whether a given range has any overlap (with one range of a set of ranges) that has a length greater than zero, e.g. contains more than a single point.
static <C extends Comparable> boolean	hasOverlap(com.google.common.collect.Range<C> lhs, com.google.common.collect.Range<C> rhs) Checks whether the two given ranges have any overlap that is not empty.
static <C extends Comparable> boolean	hasZeroLength(com.google.common.collect.Range<C> range) Checks if the length of a range is zero.
static <C extends Comparable> Optional<com.google.common.collect.Range<C>>	intersect(com.google.common.collect.Range<C> lhs, com.google.common.collect.Range<C> rhs) Returns a range representing the intersection of the two given ranges.
static com.google.common.collect.BoundType	invertBoundType(com.google.common.collect.BoundType boundType)
static <C extends Comparable> Comparator<com.google.common.collect.Range<C>>	lowerEndpointComparator()
static <C extends Comparable,T extends Comparable> com.google.common.collect.Range<T>	mapRange(com.google.common.collect.Range<C> range, Function<C,T> mapper) Returns a new range with the points mapped by the given mapping function.
static <C extends Comparable,T extends Comparable> com.google.common.collect.Range<T>	mapRange(com.google.common.collect.Range<C> range, Function<C,T> mapper, EndpointAccessor<com.google.common.collect.Range<C>,C> lowerAccessor, EndpointAccessor<com.google.common.collect.Range<C>,C> upperAccessor) Returns a new range with the points mapped by the given mapping function.
static <C extends Comparable,T extends Comparable> com.google.common.collect.Range<T>	mapRange(com.google.common.collect.Range<C> range, Function<C,T> lowerMapper, EndpointAccessor<com.google.common.collect.Range<C>,C> lowerAccessor, Function<C,T> upperMapper, EndpointAccessor<com.google.common.collect.Range<C>,C> upperAccessor) Returns a new range with the points mapped by the given mapping function.
static <C extends Comparable,T extends Comparable> com.google.common.collect.Range<T>	mapRange(com.google.common.collect.Range<C> range, Function<C,T> lowerMapper, Function<C,T> upperMapper) Returns a new range with the points mapped by the given mapping function.
static <T,C extends Comparable> List<T>	merge(List<T> items, Function<T,com.google.common.collect.Range<C>> rangeAccessor, BinaryOperator<T> merger, boolean mergeAdjacent) Merges all items whose ranges overlap, and returns a list of merged items.
static <C extends Comparable> com.google.common.collect.Range<C>	toClosed(com.google.common.collect.Range<C> range) Converts the range to a closed-closed range.
static <C extends Comparable> com.google.common.collect.Range<C>	toClosedOpen(com.google.common.collect.Range<C> range) Converts the range to a closed-open range.
static <C extends Comparable> com.google.common.collect.Range<C>	toOpen(com.google.common.collect.Range<C> range) Converts the range to an open-open range.
static <C extends Comparable> com.google.common.collect.Range<C>	toOpenClosed(com.google.common.collect.Range<C> range) Converts the range to a open -closed range.
static <C extends Comparable<C>> Collector<com.google.common.collect.Range<C>,?,com.google.common.collect.RangeSet<C>>	toRangeSet() Creates a collector for collecting a sequence of ranges into a RangeSet.
static <C extends Comparable> Comparator<com.google.common.collect.Range<C>>	upperEndpointComparator()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOWER_ENDPOINT_COMPARATOR

public static Comparator<com.google.common.collect.Range> LOWER_ENDPOINT_COMPARATOR

An EndpointTypeComparator for comparing the lower end points of a range.

UPPER_ENDPOINT_COMPARATOR

public static Comparator<com.google.common.collect.Range> UPPER_ENDPOINT_COMPARATOR

An EndpointTypeComparator for comparing the upper end points of a range.

Method Detail

compareByEndpoint

public static <T,C extends Comparable> int compareByEndpoint(T lhs,
                                                             EndpointAccessor<T,C> lhsEndpoint,
                                                             T rhs,
                                                             EndpointAccessor<T,C> rhsEndpoint)

Compares to endpoints of a range.

Type Parameters:

T - Type of the item that contains a range.

C - Type of the range's end points.

Parameters:

lhs - First item with a range to compare.

lhsEndpoint - Object for accessing a range endpoint the first item.

rhs - Second item with a range to compare.

rhsEndpoint - Object for accessing a range endpoint of the second item.

Returns:

{-1} if the endpoint of the first item is smaller than the endpoint of the second item, 0 if they are equal, and 1 otherwise.

compareByEndpoint

public static <T,C extends Comparable> int compareByEndpoint(T lhs,
                                                             EndpointAccessor<T,C> lhsEndpoint,
                                                             T rhs,
                                                             EndpointAccessor<T,C> rhsEndpoint,
                                                             EndpointTypeComparator comparator)

Compares to endpoints of a range.

Type Parameters:

T - Type of the item that contains a range.

C - Type of the range's end points.

Parameters:

lhs - First item with a range to compare.

lhsEndpoint - Object for accessing a range endpoint the first item.

rhs - Second item with a range to compare.

rhsEndpoint - Object for accessing a range endpoint of the second item.

comparator - Comparator for comparing end point types when they lie at the same point.

Returns:

{-1} if the endpoint of the first item is smaller than the endpoint of the second item, 0 if they are equal, and 1 otherwise.

createClosedRange

public static <C extends Comparable> com.google.common.collect.Range<C> createClosedRange(C lower,
                                                                                          C upper)

Creates an open range from two end points.

Type Parameters:

C - Type of the range's end points.

Parameters:

lower - Lower end point.

upper - Upper end point.

Returns:

A closed range (lower, upper). When upper end points is before lower end point, an empty range is returned. If either end point is null, it is considered unbounded.

createOpenRange

public static <C extends Comparable> com.google.common.collect.Range<C> createOpenRange(C lower,
                                                                                        C upper)

Creates a closed range from two end points.

Type Parameters:

C - Type of the range's end points.

Parameters:

lower - Lower end point.

upper - Upper end point.

Returns:

A closed range [lower, upper]. When upper end points is before lower end point, an empty range is returned. If either end point is null, it is considered unbounded.

createRange

public static <C extends Comparable> com.google.common.collect.Range<C> createRange(C lower,
                                                                                    EndpointDescriptor lowerDesc,
                                                                                    C upper,
                                                                                    EndpointDescriptor upperDesc)

Creates a range from two end points.

Type Parameters:

C - Type of the range's end points.

Parameters:

lower - Lower end point.

lowerDesc - Type of the lower end point.

upper - Upper end point.

upperDesc - Type of the upper end point.

Returns:

The range with the given end points. When upper end points is before lower end point, an empty range is returned. If either end point is null, it is considered unbounded.

createRange

public static <T,C extends Comparable> com.google.common.collect.Range<C> createRange(T lhs,
                                                                                      EndpointAccessor<T,C> lhsEndpoint,
                                                                                      T rhs,
                                                                                      EndpointAccessor<T,C> rhsEndpoint)

Creates a range from two end points.

Type Parameters:

T - Type of the objects with the end points.

C - Type of the range's end points.

Parameters:

lhs - Object for the lower end point.

lhsEndpoint - Object for extracting the lower end point from the object.

rhs - Object for the upper end point.

rhsEndpoint - Object for extracting the upper end point from the object.

Returns:

The range with the given end points. When upper end points is before lower end point, an empty range is returned.

eachPointInRange

public static <T extends Comparable> Iterable<T> eachPointInRange(com.google.common.collect.Range<T> range,
                                                                  UnaryOperator<T> nextItem)

Splits the given range into a sequence of points, starting at the lower endpoint of the range. The lower and upper endpoints are included only if the range is closed. For example, the following prints the numbers 1,2,3,4,5,6,7,8,9,10:

 final Range<Integer> oneToTen = Range.closed(1, 10);S
 for (final int i : eachPointInRange(oneToTen, x -> x + 1)) {
   System.out.println(x);
 }
 

Type Parameters:

T - Type of the items in the range.

Parameters:

range - A range to split into points.

nextItem - A successor function that returns the next point. [0,2,5].

Returns:

An iterator of the points in the given range, starting at the lower endpoint.

eachPointInRange

public static <T extends Comparable> Iterable<T> eachPointInRange(com.google.common.collect.Range<T> range,
                                                                  UnaryOperator<T> nextItem,
                                                                  boolean includeTail)

Splits the given range into a sequence of points, starting at the lower endpoint of the range. The lower and upper endpoints are included only if the range is closed. For example, the following prints the numbers 1,2,3,4,5,6,7,8,9,10:

 final Range<Integer> oneToTen = Range.closed(1, 10);
 for (final int i : eachPointInRange(oneToTen, x -> x + 1)) {
   System.out.println(x);
 }
 

Type Parameters:

T - Type of the items in the range.

Parameters:

range - A range to split into points.

nextItem - A successor function that returns the next point.

includeTail - If true, includes the last point of the range when the next point falls outside the interval. For example, when called with a range [0,5] and a next function x->x+2, this would return [0,2,5].

Returns:

An iterator of the points in the given range, starting at the lower endpoint.

eachSubrange

public static <C extends Comparable> Iterable<com.google.common.collect.Range<C>> eachSubrange(com.google.common.collect.Range<C> range,
                                                                                               com.google.common.collect.BoundType boundType,
                                                                                               boolean includeTail,
                                                                                               UnaryOperator<C> nextItem)

Splits the given range into a sequence of connected ranges, starting at the lower endpoint of the interval. For example, the following prints the ranges [0,2], [2,4], [4,5]:

 final Range<Integer> range = Range.closed(0, 5);
 for (final Range<Integer> r : eachSubrange(range, BoundType.CLOSED, true, x -> x + 2)) {
   System.out.println(r);
 }
 

Type Parameters:

C - Type of the items in the range.

Parameters:

range - A range to split.

boundType - Whether the sub ranges should be open or closed.

includeTail - If true, returns the last range when the next cut point falls outside the interval. E.g. [0,2], [2,4], [4,5] when called with the range [0,5] and the next function x -> x + 1

nextItem - A successor function that returns the next point.

Returns:

An iterator over the connected closed subranges of the given interval.

eachSubrange

public static <C extends Comparable> Iterable<com.google.common.collect.Range<C>> eachSubrange(com.google.common.collect.Range<C> range,
                                                                                               com.google.common.collect.BoundType boundType,
                                                                                               UnaryOperator<C> nextItem)

Splits the given range into a sequence of touching ranges, starting at the lower endpoint of the interval. For example, the following prints the ranges [0,2], [2,4]:

 final Range<Integer> range = Range.closed(0, 5);
 for (final Range<Integer> r : eachSubrange(range, BoundType.CLOSED, x -> x + 2)) {
   System.out.println(r);
 }
 

Type Parameters:

C - Type of the items in the range.

Parameters:

range - A range to split.

boundType - Whether the sub ranges should be open or closed.

nextItem - A successor function that returns the next point.

Returns:

An iterator over the connected closed subranges of the given interval.

findOverlappingDepth

public static <T,C extends Comparable> List<org.apache.commons.lang3.tuple.Pair<Integer,T>> findOverlappingDepth(List<T> items,
                                                                                                                 Function<T,com.google.common.collect.Range<C>> rangeAccessor,
                                                                                                                 EndpointTypeComparator comparator)

Finds the overlapping depth of each given range. A depth of 1 means that a range does not overlap any other range, a depth of >1 means that that many ranges are overlapping.

Type Parameters:

T - Type of the items holding a range.

C - Type of the end points of the ranges.

Parameters:

items - Range items to process.

rangeAccessor - Function for accessing the range represent by an item.

comparator - How to sort end point if they are on the same point.

Returns:

A list with the sorted items and the corresponding overlapping depth.

hasNonZeroOverlap

public static <C extends Comparable> boolean hasNonZeroOverlap(com.google.common.collect.Range<C> lhs,
                                                               com.google.common.collect.Range<C> rhs)

Checks whether the two given ranges have any overlap that has a length greater than zero, e.g. contains more than a single point. For example, the overlap of [1,2] and [2,3] is [2,2], which has a length of 0 and this method would return false. Conversely, [1,1.999] and [2,3] have a non-zero overlap, so this method would return true. This assumes a continuous domain.

Please note that this assumes a continuous domain for the type T.

Type Parameters:

C - Type of the items in the range.

Parameters:

lhs - First range to check.

rhs - Second range to check.

Returns:

true if there exists a non-empty range with a positive measure that is enclosed by both this range and other.

hasNonZeroOverlap

public static <C extends Comparable> boolean hasNonZeroOverlap(com.google.common.collect.RangeSet<C> ranges,
                                                               com.google.common.collect.Range<C> range)

Checks whether a given range has any overlap (with one range of a set of ranges) that has a length greater than zero, e.g. contains more than a single point. For example, the overlap of [1,2] and [2,3] is [2,2], which has a length of 0 and this method would return false. Conversely, [1,1.999] and [2,3] have a non-zero overlap, so this method would return true. This assumes a continuous domain.

Please note that this assumes a continuous domain for the type T.

Type Parameters:

C - Type of the items in the range.

Parameters:

ranges - Ranges to check.

range - Range to check.

Returns:

true if there exists a non-empty range with a positive measure that is enclosed by both a range of the given range set; and the other range.

hasOverlap

public static <C extends Comparable> boolean hasOverlap(com.google.common.collect.Range<C> lhs,
                                                        com.google.common.collect.Range<C> rhs)

Checks whether the two given ranges have any overlap that is not empty.

Type Parameters:

C - Type of the items in the range.

Parameters:

lhs - First range to check.

rhs - Second range to check.

Returns:

true if there exists a non-empty range which is enclosed by both this range and other.

hasZeroLength

public static <C extends Comparable> boolean hasZeroLength(com.google.common.collect.Range<C> range)

Checks if the length of a range is zero. This differs from Range.isEmpty() in that a range with a single point (e.g. [1,1]) has zero length, but is not considered empty. This assumes a continuous domain.

Type Parameters:

C - Type of the end points of the range.

Parameters:

range - A range to check.

Returns:

true if the range has zero length, or false otherwise.

intersect

public static <C extends Comparable> Optional<com.google.common.collect.Range<C>> intersect(com.google.common.collect.Range<C> lhs,
                                                                                            com.google.common.collect.Range<C> rhs)

Returns a range representing the intersection of the two given ranges.

Type Parameters:

C - Type of the end points of the ranges.

Parameters:

lhs - First range to process.

rhs - Second range to process.

Returns:

The intersection of the given ranges. An empty optional when they do not have an intersection.

invertBoundType

public static com.google.common.collect.BoundType invertBoundType(com.google.common.collect.BoundType boundType)

Parameters:

boundType - A bound type to process.

Returns:

The inverse of the given bound type, e.g. BoundType.OPEN when BoundType.CLOSED is given and vice versa.

lowerEndpointComparator

public static <C extends Comparable> Comparator<com.google.common.collect.Range<C>> lowerEndpointComparator()

Type Parameters:

C - Type of the end points of the Range.

Returns:

A comparator for ranges that compares them by their lower end points.

See Also:

upperEndpointComparator()

mapRange

public static <C extends Comparable,T extends Comparable> com.google.common.collect.Range<T> mapRange(com.google.common.collect.Range<C> range,
                                                                                                      Function<C,T> mapper)

Returns a new range with the points mapped by the given mapping function. Cases when the range has no upper or lower bound type are handled correctly.

Type Parameters:

C - Type of the items in the given range.

T - Type of the items in the mapped range.

Parameters:

range - Range to map.

mapper - Function that maps from the items in the input range to the items of the target range.

Returns:

A new range with the points mapped by the given mapping function.

mapRange

public static <C extends Comparable,T extends Comparable> com.google.common.collect.Range<T> mapRange(com.google.common.collect.Range<C> range,
                                                                                                      Function<C,T> mapper,
                                                                                                      EndpointAccessor<com.google.common.collect.Range<C>,C> lowerAccessor,
                                                                                                      EndpointAccessor<com.google.common.collect.Range<C>,C> upperAccessor)

Returns a new range with the points mapped by the given mapping function. Cases when the range has no upper or lower bound type are handled correctly.

Type Parameters:

C - Type of the items in the given range.

T - Type of the items in the mapped range.

Parameters:

range - Range to map.

mapper - Function that maps from the lower and upper end point of the input range to the lower and upper end point of the target range.

lowerAccessor - Accessor for the lower end point.

upperAccessor - Accessor for the upper end point.

Returns:

A new range with the points mapped by the given mapping function.

mapRange

public static <C extends Comparable,T extends Comparable> com.google.common.collect.Range<T> mapRange(com.google.common.collect.Range<C> range,
                                                                                                      Function<C,T> lowerMapper,
                                                                                                      EndpointAccessor<com.google.common.collect.Range<C>,C> lowerAccessor,
                                                                                                      Function<C,T> upperMapper,
                                                                                                      EndpointAccessor<com.google.common.collect.Range<C>,C> upperAccessor)

Returns a new range with the points mapped by the given mapping function. Cases when the range has no upper or lower bound type are handled correctly.

Type Parameters:

C - Type of the items in the given range.

T - Type of the items in the mapped range.

Parameters:

range - Range to map.

lowerMapper - Function that maps from the lower end point of the input range to the lower end point of the target range.

lowerAccessor - Accessor for the lower end point.

upperMapper - Function that maps from the upper end point of the input range to the upper end point of the target range.

upperAccessor - Accessor for the upper end point.

Returns:

A new range with the points mapped by the given mapping function.

mapRange

public static <C extends Comparable,T extends Comparable> com.google.common.collect.Range<T> mapRange(com.google.common.collect.Range<C> range,
                                                                                                      Function<C,T> lowerMapper,
                                                                                                      Function<C,T> upperMapper)

Returns a new range with the points mapped by the given mapping function. Cases when the range has no upper or lower bound type are handled correctly.

Type Parameters:

C - Type of the items in the given range.

T - Type of the items in the mapped range.

Parameters:

range - Range to map.

lowerMapper - Function that maps from the lower end point of the input range to the lower end point of the target range.

upperMapper - Function that maps from the upper end point of the input range to the upper end point of the target range.

Returns:

A new range with the points mapped by the given mapping function.

merge

public static <T,C extends Comparable> List<T> merge(List<T> items,
                                                     Function<T,com.google.common.collect.Range<C>> rangeAccessor,
                                                     BinaryOperator<T> merger,
                                                     boolean mergeAdjacent)

Merges all items whose ranges overlap, and returns a list of merged items. The original list is not modified.

Type Parameters:

T - Type of the items.

C - Type of the end point of the ranges of the items.

Parameters:

items - Items to process.

rangeAccessor - Accessor for accessing the range of an item.

merger - Merge that merges two overlapping items.

mergeAdjacent - If true, adjacent ranges are merged as well (overlapping in a single point).

Returns:

The list of merged items.

toClosed

public static <C extends Comparable> com.google.common.collect.Range<C> toClosed(com.google.common.collect.Range<C> range)

Converts the range to a closed-closed range.

Type Parameters:

C - Type of the end point of the range.

Parameters:

range - A range to convert.

Returns:

The range, with both end points closed.

toClosedOpen

public static <C extends Comparable> com.google.common.collect.Range<C> toClosedOpen(com.google.common.collect.Range<C> range)

Converts the range to a closed-open range.

Type Parameters:

C - Type of the end point of the range.

Parameters:

range - A range to convert.

Returns:

The range, with both the first end point closed and the second open.

toOpen

public static <C extends Comparable> com.google.common.collect.Range<C> toOpen(com.google.common.collect.Range<C> range)

Converts the range to an open-open range.

Type Parameters:

C - Type of the end point of the range.

Parameters:

range - A range to convert.

Returns:

The range, with both end points open.

toOpenClosed

public static <C extends Comparable> com.google.common.collect.Range<C> toOpenClosed(com.google.common.collect.Range<C> range)

Converts the range to a open -closed range.

Type Parameters:

C - Type of the end point of the range.

Parameters:

range - A range to convert.

Returns:

The range, with both the first end point open and the second closed.

toRangeSet

public static <C extends Comparable<C>> Collector<com.google.common.collect.Range<C>,?,com.google.common.collect.RangeSet<C>> toRangeSet()

Creates a collector for collecting a sequence of ranges into a RangeSet.

Type Parameters:

C - Type of the range's end points.

Returns:

A collectors that puts the ranges in a RangeSet.

upperEndpointComparator

public static <C extends Comparable> Comparator<com.google.common.collect.Range<C>> upperEndpointComparator()

Type Parameters:

C - Type of the end points of the Range.

Returns:

A comparator for ranges that compares them by their upper end points.

See Also:

lowerEndpointComparator()