1/*
2 * Copyright (C) 2010 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15package com.google.common.collect;
16
17import static com.google.common.base.Preconditions.checkArgument;
18import static com.google.common.base.Preconditions.checkNotNull;
19
20import com.google.common.annotations.Beta;
21import com.google.common.annotations.GwtCompatible;
22
23import java.util.NoSuchElementException;
24
25/**
26 * A sorted set of contiguous values in a given {@link DiscreteDomain}.
27 *
28 * @author Gregory Kick
29 * @since 10.0
30 */
31@Beta
32@GwtCompatible
33@SuppressWarnings("unchecked") // allow ungenerified Comparable types
34public abstract class ContiguousSet<C extends Comparable> extends ImmutableSortedSet<C> {
35  final DiscreteDomain<C> domain;
36
37  ContiguousSet(DiscreteDomain<C> domain) {
38    super(Ordering.natural());
39    this.domain = domain;
40  }
41
42  @Override public ContiguousSet<C> headSet(C toElement) {
43    return headSet(checkNotNull(toElement), false);
44  }
45
46  @Override ContiguousSet<C> headSet(C toElement, boolean inclusive) {
47    return headSetImpl(checkNotNull(toElement), inclusive);
48  }
49
50  @Override public ContiguousSet<C> subSet(C fromElement, C toElement) {
51    checkNotNull(fromElement);
52    checkNotNull(toElement);
53    checkArgument(comparator().compare(fromElement, toElement) <= 0);
54    return subSet(fromElement, true, toElement, false);
55  }
56
57  @Override ContiguousSet<C> subSet(C fromElement, boolean fromInclusive, C toElement,
58      boolean toInclusive) {
59    checkNotNull(fromElement);
60    checkNotNull(toElement);
61    checkArgument(comparator().compare(fromElement, toElement) <= 0);
62    return subSetImpl(fromElement, fromInclusive, toElement, toInclusive);
63  }
64
65  @Override public ContiguousSet<C> tailSet(C fromElement) {
66    return tailSet(checkNotNull(fromElement), true);
67  }
68
69  @Override ContiguousSet<C> tailSet(C fromElement, boolean inclusive){
70    return tailSetImpl(checkNotNull(fromElement), inclusive);
71  }
72
73  /*
74   * These methods perform most headSet, subSet, and tailSet logic, besides parameter validation.
75   */
76  /*@Override*/ abstract ContiguousSet<C> headSetImpl(C toElement, boolean inclusive);
77
78  /*@Override*/ abstract ContiguousSet<C> subSetImpl(C fromElement, boolean fromInclusive,
79      C toElement, boolean toInclusive);
80
81  /*@Override*/ abstract ContiguousSet<C> tailSetImpl(C fromElement, boolean inclusive);
82
83  /**
84   * Returns the set of values that are contained in both this set and the other.
85   *
86   * <p>This method should always be used instead of
87   * {@link Sets#intersection} for {@link ContiguousSet} instances.
88   */
89  public abstract ContiguousSet<C> intersection(ContiguousSet<C> other);
90
91  /**
92   * Returns a range, closed on both ends, whose endpoints are the minimum and maximum values
93   * contained in this set.  This is equivalent to {@code range(CLOSED, CLOSED)}.
94   *
95   * @throws NoSuchElementException if this set is empty
96   */
97  public abstract Range<C> range();
98
99  /**
100   * Returns the minimal range with the given boundary types for which all values in this set are
101   * {@linkplain Range#contains(Comparable) contained} within the range.
102   *
103   * <p>Note that this method will return ranges with unbounded endpoints if {@link BoundType#OPEN}
104   * is requested for a domain minimum or maximum.  For example, if {@code set} was created from the
105   * range {@code [1..Integer.MAX_VALUE]} then {@code set.range(CLOSED, OPEN)} must return
106   * {@code [1..∞)}.
107   *
108   * @throws NoSuchElementException if this set is empty
109   */
110  public abstract Range<C> range(BoundType lowerBoundType, BoundType upperBoundType);
111
112  /** Returns a short-hand representation of the contents such as {@code "[1..100]"}. */
113  @Override public String toString() {
114    return range().toString();
115  }
116}
117