Google Guava Ranges(区间)

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

Range常用函数介绍

public final class Range extends RangeGwtSerializationDependencies
        implements Predicate, Serializable {

    /**
     * (a..b)
     */
    public static > Range open(C lower, C upper);

    /**
     * [a..b]
     */
    public static > Range closed(C lower, C upper);

    /**
     * [a..b)
     */
    public static > Range closedOpen(C lower, C upper);

    /**
     * (a..b]
     */
    public static > Range openClosed(C lower, C upper);

    /**
     * a..b
     * BoundType用于指示是开区间还是闭区间
     */
    public static > Range range(
            C lower, BoundType lowerType, C upper, BoundType upperType);

    /**
     * (-∞..b)
     */
    public static > Range lessThan(C endpoint);

    /**
     * (-∞..b]
     */
    public static > Range atMost(C endpoint);

    /**
     * -∞..b
     * BoundType用于指示是开区间还是闭区间
     */
    public static > Range upTo(C endpoint, BoundType boundType);

    /**
     * (a..+∞)
     */
    public static > Range greaterThan(C endpoint);

    /**
     * [a..+∞)
     */
    public static > Range atLeast(C endpoint);

    /**
     * a..+∞
     * BoundType用于指示是开区间还是闭区间
     */
    public static > Range downTo(C endpoint, BoundType boundType);


    /**
     * (-∞..+∞)
     */
    @SuppressWarnings("unchecked")
    public static > Range all();

    /**
     * 区间值包含给定的值
     */
    public static > Range singleton(C value);

    /**
     * 返回一个包含所有参数的最小范围的区间
     */
    public static > Range encloseAll(Iterable 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 values);

    /**
     * 区间是否包含
     *
     * 

     *   
{@code [3..6]} encloses {@code [4..5]}
     *   
{@code (3..6)} encloses {@code (3..6)}
     *   
{@code [3..6]} encloses {@code [4..4)} (even though the latter is empty)
     *   
{@code (3..6]} does not enclose {@code [3..6]}
     *   
{@code [4..5]} does not enclose {@code (3..6)} (even though it contains every value
     *       contained by the latter range)
     *   
{@code [3..6]} does not enclose {@code (1..1]} (even though it contains every value
     *       contained by the latter range)
     * 
     */
    public boolean encloses(Range other);

    /**
     * 区间是否可以连接起来
     *
     * 

     *   
{@code [2, 4)} and {@code [5, 7)} are not connected
     *   
{@code [2, 4)} and {@code [3, 5)} are connected, because both enclose {@code [3, 4)}
     *   
{@code [2, 4)} and {@code [4, 6)} are connected, because both enclose the empty range
     *       {@code [4, 4)}
     * 
     */
    public boolean isConnected(Range other);

    /**
     * 返回两个区间的交集：既包含于第一个区间，又包含于另一个区间的最大区间
     */
    public Range intersection(Range connectedRange);

    /**
     * 返回此范围与otherRange之间的最大范围
     */
    public Range gap(Range otherRange);

    /**
     * 返回”同时包括两个区间的最小区间”，如果两个区间相连，那就是它们的并集
     */
    public Range span(Range other);

    /**
     * 把离散域转为区间的”规范形式”
     */
    public Range canonical(DiscreteDomain 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(C)
[a..+∞)	atLeast(C)
(-∞..b)	lessThan(C)
(-∞..b]	atMost(C)
(-∞..+∞)	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 range0 = Range.range(1, BoundType.CLOSED, 10, BoundType.CLOSED);
        System.out.println(range0.contains(1)); // true

        // (0, 10)的一个区间
        Range range1 = Range.range(1, BoundType.OPEN, 10, BoundType.OPEN);
        System.out.println(range1.contains(1)); // false
    }

二 区间运算

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

    @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 range0Parent = Range.open(3, 6);
        // [4, 5]
        Range range0Child = Range.range(4, BoundType.CLOSED, 5, BoundType.CLOSED);
        System.out.println(range0Parent.encloses(range0Child)); // true

        // [3, 6]
        Range range1Parent = Range.closed(3, 6);
        // [4, 4) -> 里面没有元素
        Range range1Child = Range.closedOpen(4, 4);
        System.out.println(range1Parent.encloses(range1Child)); // true

        // [3, 6]
        Range range2Parent = Range.closed(3, 6);
        // [4, 7)
        Range 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 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 {

        
        @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;
        }
    }