Package de.xima.fc.utils.range

Class RangeUtils

  • public class RangeUtils
extends Object
    Utilities with additional methods on Ranges.
    Author:
    XIMA MEDIA GmbH

    • Field Detail

      • LOWER_ENDPOINT_COMPARATOR

        public static final 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 final 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.

      • constrainToRange

        public static <C extends Comparable> C constrainToRange​(C value,
                                                        com.google.common.collect.Range<? extends C> range)
        Constrains the given value to the given range.
        Type Parameters:
        C - Type of the range's end points.
        Parameters:
        value - Value to constrain.
        range - Range to which to constrain the value.
        Returns:
        The given value, constrained (capped) to the given range.

      • 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.

      • intersectNull

        public static <C extends Comparable> com.google.common.collect.Range<C> intersectNull​(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. null is treated as an range without elements. This method can be called consecutively on a range to restrict it successively.
        Type Parameters:
        C - Type of the end points of the ranges.
        Parameters:
        lhs - First range to process. null to indicate a range without elements.
        rhs - Second range to process. null to indicate a range without elements.
        Returns:
        The intersection of the given ranges. null 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.

      • lengthDouble

        public static Optional<BigDecimal> lengthDouble​(com.google.common.collect.Range<Double> range)
        Parameters:
        range - A range for which to compute the length.
        Returns:
        The length of the given range. An empty optional if the range is unbounded.

      • lengthFloat

        public static OptionalDouble lengthFloat​(com.google.common.collect.Range<Float> range)
        Parameters:
        range - A range for which to compute the length.
        Returns:
        The length of the given range. An empty optional if the range is unbounded.

      • lengthInt

        public static OptionalLong lengthInt​(com.google.common.collect.Range<Integer> range)
        Parameters:
        range - A range for which to compute the length.
        Returns:
        The length of the given range. An empty optional if the range is unbounded.

      • lengthLong

        public static Optional<BigInteger> lengthLong​(com.google.common.collect.Range<Long> range)
        Parameters:
        range - A range for which to compute the length.
        Returns:
        The length of the given range. An empty optional if the range is unbounded.

      • lengthShort

        public static OptionalLong lengthShort​(com.google.common.collect.Range<Short> range)
        Parameters:
        range - A range for which to compute the length.
        Returns:
        The length of the given range. An empty optional if the range is unbounded.

      • 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()