8-區間 · Java 開源項目中文文檔

# 8-區間 [原文鏈接](http://code.google.com/p/guava-libraries/wiki/RangesExplained)?[譯文鏈接](http://ifeve.com/google-guava-ranges)?**譯文：**沈義揚 ## 范例 ``` List scores; Iterable belowMedian =Iterables.filter(scores,Range.lessThan(median)); ... Range validGrades = Range.closed(1, 12); for(int grade : ContiguousSet.create(validGrades, DiscreteDomain.integers())) { ... } ``` ## 簡介區間，有時也稱為范圍，是特定域中的凸性（非正式說法為連續的或不中斷的）部分。在形式上，凸性表示對a<=b<=c, range.contains(a)且range.contains(c)意味著range.contains(b)。區間可以延伸至無限——例如，范圍”x>3″包括任意大于3的值——也可以被限制為有限，如” 2<=x<5″。Guava用更緊湊的方法表示范圍，有數學背景的程序員對此是耳熟能詳的： * (a..b) = {x | a < x < b} * [a..b] = {x | a <= x <= b} * [a..b) = {x | a <= x < b} * (a..b] = {x | a < x <= b} * (a..+∞) = {x | x > a} * [a..+∞) = {x | x >= a} * (-∞..b) = {x | x < b} * (-∞..b] = {x | x <= b} * (-∞..+∞) = 所有值上面的a、b稱為端點。為了提高一致性，Guava中的Range要求上端點不能小于下端點。上下端點有可能是相等的，但要求區間是閉區間或半開半閉區間（至少有一個端點是包含在區間中的）： * [a..a]：單元素區間 * [a..a); (a..a]：空區間，但它們是有效的 * (a..a)：無效區間 Guava用類型[Range<C>](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html)表示區間。所有區間實現都是不可變類型。 ## 構建區間區間實例可以由[Range](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html)類的靜態方法獲取： | (a..b) | [open(C, C)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#open%28java.lang.Comparable,java.lang.Comparable%29) | |:--- |:--- | | [a..b] | [closed(C, C)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#closed%28java.lang.Comparable,java.lang.Comparable%29) | | [a..b) | [closedOpen(C, C)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#closedOpen%28java.lang.Comparable,java.lang.Comparable%29) | | (a..b] | [openClosed(C, C)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#openClosed%28java.lang.Comparable,java.lang.Comparable%29) | | (a..+∞) | [greaterThan(C)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#greaterThan%28C%29) | | [a..+∞) | [atLeast(C)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#atLeast%28C%29) | | (-∞..b) | [lessThan(C)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#lessThan%28C%29) | | (-∞..b] | [atMost(C)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#atMost%28C%29) | | (-∞..+∞) | [all()](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#all%28%29) | ``` Range.closed("left", "right"); //字典序在"left"和"right"之間的字符串，閉區間 Range.lessThan(4.0); //嚴格小于4.0的double值 ``` 此外，也可以明確地指定邊界類型來構造區間： | 有界區間 | [range(C, BoundType, C, ? BoundType)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/co…collect.BoundType,java.lang.Comparable,com.google.common.collect.BoundType)) | |:--- |:--- | | 無上界區間：((a..+∞) 或[a..+∞)) | [downTo(C, BoundType)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/co…Range.html#downTo%28java.lang.Comparable,com.google.common.collect.BoundType%29) | | 無下界區間：((-∞..b) 或(-∞..b]) | [upTo(C, BoundType)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/co…t/Range.html#upTo%28java.lang.Comparable,com.google.common.collect.BoundType%29) | 這里的[BoundType](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/BoundType.html)是一個枚舉類型，包含CLOSED和OPEN兩個值。 ``` Range.downTo(4, boundType);// (a..+∞)或[a..+∞)，取決于boundType Range.range(1, CLOSED, 4, OPEN);// [1..4)，等同于Range.closedOpen(1, 4) ``` ## 區間運算 Range的基本運算是它的[contains(C)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#contains%28C%29) 方法，和你期望的一樣，它用來區間判斷是否包含某個值。此外，Range實例也可以當作Predicate，并且在函數式編程中使用（譯者注：見第4章）。任何Range實例也都支持containsAll(Iterable<? extends C>)方法： ``` 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 ``` ### 查詢運算 Range類提供了以下方法來查看區間的端點： * [hasLowerBound()](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#hasLowerBound%28%29)和[hasUpperBound()](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#hasUpperBound%28%29)：判斷區間是否有特定邊界，或是無限的； * [lowerBoundType()](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#lowerBoundType%28%29)和[upperBoundType()](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#upperBoundType%28%29)：返回區間邊界類型，CLOSED或OPEN；如果區間沒有對應的邊界，拋出IllegalStateException； * [lowerEndpoint()](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#lowerEndpoint%28%29)和[upperEndpoint()](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#upperEndpoint%28%29)：返回區間的端點值；如果區間沒有對應的邊界，拋出IllegalStateException； * [isEmpty()](http://docs.guava-libraries.googlecode.com/git-history/release/javadoc/com/google/common/collect/Range.html#isEmpty%28%29)：判斷是否為空區間。 ``` 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 ``` ### 關系運算 **包含[enclose]** 區間之間的最基本關系就是包含[[`encloses(Range)`](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#encloses%28com.google.common.collect.Range%29)]：如果內區間的邊界沒有超出外區間的邊界，則外區間包含內區間。包含判斷的結果完全取決于區間端點的比較！ * [3..6] 包含[4..5] ； * (3..6) 包含(3..6) ； * [3..6] 包含[4..4)，雖然后者是空區間； * (3..6]不包含[3..6] ； * [4..5]不包含(3..6)，雖然前者包含了后者的所有值，離散域[discrete domains]可以解決這個問題（見8.5節）； * [3..6]不包含(1..1]，雖然前者包含了后者的所有值。包含是一種[偏序關系](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#partial_ordering)[[partial ordering](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#partial_ordering)]。基于包含關系的概念，Range還提供了以下運算方法。 **相連[isConnected]** `Range.isConnected(Range)`判斷區間是否是相連的。具體來說，isConnected測試是否有區間同時包含于這兩個區間，這等同于數學上的定義”兩個區間的并集是連續集合的形式”（空區間的特殊情況除外）。相連是一種自反的[[reflexive](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#reflexive)]、對稱的[[symmetric](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#symmetric)]關系。 ``` 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 ``` **交集[intersection]** [`Range.intersection(Range)`](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#intersection%28com.google.common.collect.Range%29)返回兩個區間的交集：既包含于第一個區間，又包含于另一個區間的最大區間。當且僅當兩個區間是相連的，它們才有交集。如果兩個區間沒有交集，該方法將拋出IllegalArgumentException`。` 交集是可互換的[[commutative](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#commutative)] 、關聯的[[associative](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#associative)] 運算[[operation](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#binary_operation)]。 ``` 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 ``` **跨區間[span]** [`Range.span(Range)`](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#span%28com.google.common.collect.Range%29)返回”同時包括兩個區間的最小區間”，如果兩個區間相連，那就是它們的并集。 span是可互換的[[commutative](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#commutative)] 、關聯的[[associative](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#associative)] 、閉合的[[closed](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#closed)]運算[[operation](http://code.google.com/p/guava-libraries/wiki/GuavaTermsExplained#binary_operation)]。 ``` 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] ``` ## 離散域部分（但不是全部）可比較類型是離散的，即區間的上下邊界都是可枚舉的。在Guava中，用[DiscreteDomain<C>](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/DiscreteDomain.html)實現類型C的離散形式操作。一個離散域總是代表某種類型值的全集；它不能代表類似”素數”、”長度為5的字符串”或”午夜的時間戳”這樣的局部域。 [DiscreteDomain](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/DiscreteDomain.html)提供的離散域實例包括： | **類型** | **離散域** | |:--- |:--- | | Integer | [integers()](http://docs.guava-libraries.googlecode.com/git-history/release/javadoc/com/google/common/collect/DiscreteDomain.html#integers%28%29) | | Long | [longs()](http://docs.guava-libraries.googlecode.com/git-history/release/javadoc/com/google/common/collect/DiscreteDomain.html#longs%28%29) | 一旦獲取了DiscreteDomain實例，你就可以使用下面的Range運算方法： * [ContiguousSet.create(range, domain)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/ContiguousSet.html#create%28com.google.common.collect.Range, com.google.common.collect.DiscreteDomain%29)：用ImmutableSortedSet<C>形式表示Range<C>中符合離散域定義的元素，并增加一些額外操作——_譯者注：實際返回__ImmutableSortedSet__的子類__ContiguousSet_。（對無限區間不起作用，除非類型C本身是有限的，比如int就是可枚舉的） * [canonical(domain)](http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/Range.html#canonical%28com.google.common.collect.DiscreteDomain%29)：把離散域轉為區間的”規范形式”。如果ContiguousSet.create(a, domain).equals(ContiguousSet.create(b, domain))并且!a.isEmpty()，則有a.canonical(domain).equals(b.canonical(domain))。（這并不意味著a.equals(b)） ``` ImmutableSortedSet set = ContigousSet.create(Range.open(1, 5), iscreteDomain.integers()); //set包含[2, 3, 4] ContiguousSet.create(Range.greaterThan(0), DiscreteDomain.integers()); //set包含[1, 2, ..., Integer.MAX_VALUE] ``` 注意，ContiguousSet.create并沒有真的構造了整個集合，而是返回了set形式的區間視圖。 ### 你自己的離散域你可以創建自己的離散域，但必須記住DiscreteDomain契約的幾個重要方面。 * 一個離散域總是代表某種類型值的全集；它不能代表類似”素數”或”長度為5的字符串”這樣的局部域。所以舉例來說，你無法構造一個DiscreteDomain以表示精確到秒的JODA DateTime日期集合：因為那將無法包含JODA DateTime的所有值。 * DiscreteDomain可能是無限的——比如BigInteger DiscreteDomain。這種情況下，你應當用minValue()和maxValue()的默認實現，它們會拋出NoSuchElementException。但Guava禁止把無限區間傳入ContiguousSet.create——_譯者注：那明顯得不到一個可枚舉的集合。_ ## 如果我需要一個Comparator呢？我們想要在Range的可用性與API復雜性之間找到特定的平衡，這部分導致了我們沒有提供基于Comparator的接口：我們不需要操心區間是怎樣基于不同Comparator互動的；所有API簽名都是簡單明確的；這樣更好。另一方面，如果你需要任意Comparator，可以按下列其中一項來做： * 使用通用的Predicate接口，而不是Range類。（Range實現了Predicate接口，因此可以用Predicates.compose(range, function)獲取Predicate實例） * 使用包裝類以定義期望的排序。 _譯者注：實際上Range規定元素類型必須是Comparable，這已經滿足了大多數需求。如果需要自定義特殊的比較邏輯，可以用Predicates.compose(range, function)組合比較的function。_