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

你可能感兴趣的:(Google Guava Ranges(区间))