Google Guava Ranges(區間)

       區間，有時也稱爲範圍。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 創建區間的一些函數

區間	Range函數
(a…b)	open(C, C)
[a…b]	closed(C, C)
[a…b)	closedOpen(C, C)
(a…b]	openClosed(C, C)
(a…+∞)	greaterThan©
[a…+∞)	atLeast©
(-∞…b)	lessThan©
(-∞…b]	atMost©
(-∞…+∞)	all()
有界區間	range(C, BoundType, C, BoundType)
無上界區間：((a…+∞) 或[a…+∞))	downTo(C, BoundType)
無下界區間：((-∞…b) 或(-∞…b])	upTo(C, BoundType)

       上面有些函數有用到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提供的離散域實例包括：

類型	離散域
Integer	integers()
Long	longs()

       一旦獲取了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;
        }
    }