Google Guava Ranges(区间)

￡神魔★判官ぃ 2021-12-08 19:34 362阅读 0赞

区间，有时也称为范围。Guava用类型Range表示区间。所有区间实现都是不可变类型。接下来我们对Guava中的Range做一个简单的介绍。我们先看下Range类里面每个函数的介绍，在说具体的使用。

> Range常用函数介绍

public final class Range<C extends Comparable> extends RangeGwtSerializationDependencies
            implements Predicate<C>, Serializable {
    
        /**
         * (a..b)
         */
        public static <C extends Comparable<?>> Range<C> open(C lower, C upper);
    
        /**
         * [a..b]
         */
        public static <C extends Comparable<?>> Range<C> closed(C lower, C upper);
    
        /**
         * [a..b)
         */
        public static <C extends Comparable<?>> Range<C> closedOpen(C lower, C upper);
    
        /**
         * (a..b]
         */
        public static <C extends Comparable<?>> Range<C> openClosed(C lower, C upper);
    
        /**
         * a..b
         * BoundType用于指示是开区间还是闭区间
         */
        public static <C extends Comparable<?>> Range<C> range(
                C lower, BoundType lowerType, C upper, BoundType upperType);
    
        /**
         * (-∞..b)
         */
        public static <C extends Comparable<?>> Range<C> lessThan(C endpoint);
    
        /**
         * (-∞..b]
         */
        public static <C extends Comparable<?>> Range<C> atMost(C endpoint);
    
        /**
         * -∞..b
         * BoundType用于指示是开区间还是闭区间
         */
        public static <C extends Comparable<?>> Range<C> upTo(C endpoint, BoundType boundType);
    
        /**
         * (a..+∞)
         */
        public static <C extends Comparable<?>> Range<C> greaterThan(C endpoint);
    
        /**
         * [a..+∞)
         */
        public static <C extends Comparable<?>> Range<C> atLeast(C endpoint);
    
        /**
         * a..+∞
         * BoundType用于指示是开区间还是闭区间
         */
        public static <C extends Comparable<?>> Range<C> downTo(C endpoint, BoundType boundType);
    
    
        /**
         * (-∞..+∞)
         */
        @SuppressWarnings("unchecked")
        public static <C extends Comparable<?>> Range<C> all();
    
        /**
         * 区间值包含给定的值
         */
        public static <C extends Comparable<?>> Range<C> singleton(C value);
    
        /**
         * 返回一个包含所有参数的最小范围的区间
         */
        public static <C extends Comparable<?>> Range<C> encloseAll(Iterable<C> values);
    
    
        /** 如果此范围具有较低的端点，则返回true */
        public boolean hasLowerBound();
    
        /**
         * 返回此范围的下端点（最小值）
         */
        public C lowerEndpoint();
    
        /**
         * 下断点的范围是开区间还是闭区间
         */
        public BoundType lowerBoundType();
    
        /** 如果此范围具有上端点，则返回true */
        public boolean hasUpperBound();
    
        /**
         * 返回上端点对应的值
         */
        public C upperEndpoint();
    
        /**
         * 上端点是开区间还是闭区间
         */
        public BoundType upperBoundType();
    
        /**
         * 区间是否为null
         */
        public boolean isEmpty();
    
        /**
         * 是否包含给定值
         */
        public boolean contains(C value);
    
    
        /**
         * 是否包含所有的值
         */
        public boolean containsAll(Iterable<? extends C> values);
    
        /**
         * 区间是否包含
         *
         * <ul>
         *   <li>{@code [3..6]} encloses {@code [4..5]}
         *   <li>{@code (3..6)} encloses {@code (3..6)}
         *   <li>{@code [3..6]} encloses {@code [4..4)} (even though the latter is empty)
         *   <li>{@code (3..6]} does not enclose {@code [3..6]}
         *   <li>{@code [4..5]} does not enclose {@code (3..6)} (even though it contains every value
         *       contained by the latter range)
         *   <li>{@code [3..6]} does not enclose {@code (1..1]} (even though it contains every value
         *       contained by the latter range)
         * </ul>
         */
        public boolean encloses(Range<C> other);
    
        /**
         * 区间是否可以连接起来
         *
         * <ul>
         *   <li>{@code [2, 4)} and {@code [5, 7)} are not connected
         *   <li>{@code [2, 4)} and {@code [3, 5)} are connected, because both enclose {@code [3, 4)}
         *   <li>{@code [2, 4)} and {@code [4, 6)} are connected, because both enclose the empty range
         *       {@code [4, 4)}
         * </ul>
         */
        public boolean isConnected(Range<C> other);
    
        /**
         * 返回两个区间的交集：既包含于第一个区间，又包含于另一个区间的最大区间
         */
        public Range<C> intersection(Range<C> connectedRange);
    
        /**
         * 返回此范围与otherRange之间的最大范围
         */
        public Range<C> gap(Range<C> otherRange);
    
        /**
         * 返回”同时包括两个区间的最小区间”，如果两个区间相连，那就是它们的并集
         */
        public Range<C> span(Range<C> other);
    
        /**
         * 把离散域转为区间的”规范形式”
         */
        public Range<C> canonical(DiscreteDomain<C> domain);
    
    }

# 一 创建区间 #

## 1.1 创建区间的一些函数 ##

<table> 
 <thead> 
  <tr> 
   <th>区间</th> 
   <th>Range函数</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>(a…b)</td> 
   <td>open(C, C)</td> 
  </tr> 
  <tr> 
   <td>[a…b]</td> 
   <td>closed(C, C)</td> 
  </tr> 
  <tr> 
   <td>[a…b)</td> 
   <td>closedOpen(C, C)</td> 
  </tr> 
  <tr> 
   <td>(a…b]</td> 
   <td>openClosed(C, C)</td> 
  </tr> 
  <tr> 
   <td>(a…+∞)</td> 
   <td>greaterThan©</td> 
  </tr> 
  <tr> 
   <td>[a…+∞)</td> 
   <td>atLeast©</td> 
  </tr> 
  <tr> 
   <td>(-∞…b)</td> 
   <td>lessThan©</td> 
  </tr> 
  <tr> 
   <td>(-∞…b]</td> 
   <td>atMost©</td> 
  </tr> 
  <tr> 
   <td>(-∞…+∞)</td> 
   <td>all()</td> 
  </tr> 
  <tr> 
   <td>有界区间</td> 
   <td>range(C, BoundType, C, BoundType)</td> 
  </tr> 
  <tr> 
   <td>无上界区间：((a…+∞) 或[a…+∞))</td> 
   <td>downTo(C, BoundType)</td> 
  </tr> 
  <tr> 
   <td>无下界区间：((-∞…b) 或(-∞…b])</td> 
   <td>upTo(C, BoundType)</td> 
  </tr> 
 </tbody> 
</table>

上面有些函数有用到BoundType这个枚举类。BoundType用来指示区间是开区间还是闭区间。使用也很简单，举一个例子：

@Test
        public void boundType() {
            // [0, 10]的一个区间
            Range<Integer> range0 = Range.range(1, BoundType.CLOSED, 10, BoundType.CLOSED);
            System.out.println(range0.contains(1)); // true
    
            // (0, 10)的一个区间
            Range<Integer> range1 = Range.range(1, BoundType.OPEN, 10, BoundType.OPEN);
            System.out.println(range1.contains(1)); // false
        }

# 二 区间运算 #

Range的基本运算是它的contains© 方法，用来区间判断是否包含某个值。

@Test
        public void contain() {
            Range.closed(1, 3).contains(2);//return true
            Range.closed(1, 3).contains(4);//return false
            Range.lessThan(5).contains(5); //return false
            Range.closed(1, 4).containsAll(Ints.asList(1, 2, 3)); //return true
        }

## 2.1 查询运算 ##

*  hasLowerBound()和hasUpperBound()：判断区间是否有特定边界，或是无限的；
 *  lowerBoundType()和upperBoundType()：返回区间边界类型，CLOSED或OPEN；如果区间没有对应的边界，抛出IllegalStateException；
 *  lowerEndpoint()和upperEndpoint()：返回区间的端点值；如果区间没有对应的边界，抛出IllegalStateException；
 *  isEmpty()：判断是否为空区间。

@Test
        public void query() {
            Range.closedOpen(4, 4).isEmpty(); // returns true
            Range.openClosed(4, 4).isEmpty(); // returns true
            Range.closed(4, 4).isEmpty(); // returns false
    //        Range.open(4, 4).isEmpty(); // Range.open throws IllegalArgumentException
            Range.closed(3, 10).lowerEndpoint(); // returns 3
            Range.open(3, 10).lowerEndpoint(); // returns 3
            Range.closed(3, 10).lowerBoundType(); // returns CLOSED
            Range.open(3, 10).upperBoundType(); // returns OPEN
        }

## 2.2 关系运算 ##

### 2.2.1 包含\[enclose\] ###

一个range里面的值都在另一个range里面。我们直接用几个简单的实例来说明。

@Test
        public void enclose() {
            // (3, 6)
            Range<Integer> range0Parent = Range.open(3, 6);
            // [4, 5]
            Range<Integer> range0Child = Range.range(4, BoundType.CLOSED, 5, BoundType.CLOSED);
            System.out.println(range0Parent.encloses(range0Child)); // true
    
            // [3, 6]
            Range<Integer> range1Parent = Range.closed(3, 6);
            // [4, 4) -> 里面没有元素
            Range<Integer> range1Child = Range.closedOpen(4, 4);
            System.out.println(range1Parent.encloses(range1Child)); // true
    
            // [3, 6]
            Range<Integer> range2Parent = Range.closed(3, 6);
            // [4, 7)
            Range<Integer> range2Child = Range.closedOpen(4, 7);
            System.out.println(range2Parent.encloses(range2Child)); // false
        }

### 2.2.2 相连\[isConnected\] ###

两个区间是否相连，指的是两个区间有相交的情况或者两个区间的元素正好可以拼起来。

@Test
        public void isConnected() {
            Range.closed(3, 5).isConnected(Range.open(5, 10)); // returns true
            Range.closed(0, 9).isConnected(Range.closed(3, 4)); // returns true
            Range.closed(0, 5).isConnected(Range.closed(3, 9)); // returns true
            Range.open(3, 5).isConnected(Range.open(5, 10)); // returns false
            Range.closed(1, 5).isConnected(Range.closed(6, 10)); // returns false
        }

### 2.2.3 交集\[intersection\] ###

返回两个区间的交集：既包含于第一个区间，又包含于另一个区间的最大区间。当且仅当两个区间是相连的，它们才有交集。如果两个区间没有交集，该方法将抛出IllegalArgumentException。

@Test
        public void intersection() {
            Range.closed(3, 5).intersection(Range.open(5, 10)); // returns (5, 5]
            Range.closed(0, 9).intersection(Range.closed(3, 4)); // returns [3, 4]
            Range.closed(0, 5).intersection(Range.closed(3, 9)); // returns [3, 5]
            Range.open(3, 5).intersection(Range.open(5, 10)); // throws IAE
            Range.closed(1, 5).intersection(Range.closed(6, 10)); // throws IAE
        }

### 2.2.4 两个区间之间的范围(gap) ###

返回原区间范围与目标区间之间的最大范围。这个是有条件的：原区间一定要在目标区间的右边，并且不能有交集。

@Test
        public void gap() {
            Range.closed(1, 5).gap(Range.closed(6, 10)); // returns (5, 6)
            Range.closed(1, 10).gap(Range.closed(6, 20)); // IllegalArgumentException
            Range.closed(1, 10).gap(Range.closed(-10, -5)); // IllegalArgumentException
        }

### 2.2.4 跨区间\[span\] ###

返回”同时包括两个区间的最小区间”，如果两个区间相连，那就是它们的并集。

@Test
        public void span() {
            Range.closed(3, 5).span(Range.open(5, 10)); // returns [3, 10)
            Range.closed(0, 9).span(Range.closed(3, 4)); // returns [0, 9]
            Range.closed(0, 5).span(Range.closed(3, 9)); // returns [0, 9]
            Range.open(3, 5).span(Range.open(5, 10)); // returns (3, 10)
            Range.closed(1, 5).span(Range.closed(6, 10)); // returns [1, 10]
            Range.open(1, 3).span(Range.open(5, 10)); // return (1, 10)
        }

# 三 离散域 #

离散域，简单来讲就是给定一个区间里面的最大值和最小值之后，区间里面的各个值，我们可以根据某种规则列举出来(根据当前值推断出前一个值，后一个值。并且最大值，最小值是确定的)。在Guava中，用DiscreteDomain实现类型C的离散形式操作。

> DiscreteDomain提供的离散域实例包括：

<table> 
 <thead> 
  <tr> 
   <th>类型</th> 
   <th>离散域</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>Integer</td> 
   <td>integers()</td> 
  </tr> 
  <tr> 
   <td>Long</td> 
   <td>longs()</td> 
  </tr> 
 </tbody> 
</table>

一旦获取了DiscreteDomain实例，我们就可以使用下面的Range运算方法：

*  ContiguousSet.create(range, domain)：用ImmutableSortedSet形式表示Range中符合离散域定义的元素，并增加一些额外操作——译者注：实际返回ImmutableSortedSet的子类ContiguousSet。（对无限区间不起作用，除非类型C本身是有限的，比如int就是可枚举的）
 *  canonical(domain)：把离散域转为区间的”规范形式”。如果ContiguousSet.create(a, domain).equals(ContiguousSet.create(b, domain))并且!a.isEmpty()，则有a.canonical(domain).equals(b.canonical(domain))。（这并不意味着a.equals(b)）

@Test
        public void discreteDomain() {
            //set包含[2, 3, 4]
            ImmutableSortedSet set0 = ContiguousSet.create(Range.open(1, 5), DiscreteDomain.integers());
            //set包含[1, 2, ..., Integer.MAX_VALUE]
            ImmutableSortedSet set1 = ContiguousSet.create(Range.greaterThan(0), DiscreteDomain.integers());
        }

关于DiscreteDomain的使用，我们多讲一点。我们来自定义0到100之间的偶数的DiscreteDomain。实现代码如下：

@Test
        public void discreteDomain1() {
            // canonical
            Range<Integer> range =  Range.closed(2, 10).canonical(new EvenInteger()); // range: 2、4、6、8、10
            System.out.println(range.contains(4)); // true
            System.out.println(range.contains(3)); // false
        }
    
        /**
         * 简单实现一个0到100的偶数的离散型结构
         */
        static class EvenInteger extends DiscreteDomain<Integer> {
    
            
            @Override
            public Integer next(Integer value) {
                Integer adapterValue = value % 2 == 0 ? value : value - 1;
                System.out.println("next = " + adapterValue);
                return adapterValue > 100 ? null : adapterValue + 2;
            }
    
            @Override
            public Integer previous(Integer value) {
                Integer adapterValue = value % 2 == 0 ? value : value - 1;
                System.out.println("previous = " + adapterValue);
                return adapterValue < 0 ? null : adapterValue - 2;
            }
    
            @Override
            public long distance(Integer start, Integer end) {
                Integer adapterStart = start % 2 == 0 ? start : start - 1;
                Integer adapterEnd = end % 2 == 0 ? end : end - 1;
                return adapterEnd - adapterStart;
            }
    
            @Override
            public Integer minValue() {
                return 0;
            }
    
            @Override
            public Integer maxValue() {
                return 100;
            }
        }