001 /*
002 * Copyright (C) 2010 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015 package com.google.common.collect;
016
017 import static com.google.common.base.Preconditions.checkArgument;
018 import static com.google.common.base.Preconditions.checkNotNull;
019
020 import com.google.common.annotations.Beta;
021 import com.google.common.annotations.GwtCompatible;
022 import com.google.common.annotations.GwtIncompatible;
023
024 import java.util.Collections;
025 import java.util.NoSuchElementException;
026 import java.util.Set;
027
028 /**
029 * A sorted set of contiguous values in a given {@link DiscreteDomain}.
030 *
031 * <p><b>Warning:</b> Be extremely careful what you do with conceptually large instances (such as
032 * {@code ContiguousSet.create(Ranges.greaterThan(0), DiscreteDomains.integers()}). Certain
033 * operations on such a set can be performed efficiently, but others (such as {@link Set#hashCode}
034 * or {@link Collections#frequency}) can cause major performance problems.
035 *
036 * @author Gregory Kick
037 * @since 10.0
038 */
039 @Beta
040 @GwtCompatible(emulated = true)
041 @SuppressWarnings("rawtypes") // allow ungenerified Comparable types
042 public abstract class ContiguousSet<C extends Comparable> extends ImmutableSortedSet<C> {
043 /**
044 * Returns a {@code ContiguousSet} containing the same values in the given domain
045 * {@linkplain Range#contains contained} by the range.
046 *
047 * @throws IllegalArgumentException if neither range nor the domain has a lower bound, or if
048 * neither has an upper bound
049 *
050 * @since 13.0
051 */
052 public static <C extends Comparable> ContiguousSet<C> create(
053 Range<C> range, DiscreteDomain<C> domain) {
054 checkNotNull(range);
055 checkNotNull(domain);
056 Range<C> effectiveRange = range;
057 try {
058 if (!range.hasLowerBound()) {
059 effectiveRange = effectiveRange.intersection(Ranges.atLeast(domain.minValue()));
060 }
061 if (!range.hasUpperBound()) {
062 effectiveRange = effectiveRange.intersection(Ranges.atMost(domain.maxValue()));
063 }
064 } catch (NoSuchElementException e) {
065 throw new IllegalArgumentException(e);
066 }
067
068 // Per class spec, we are allowed to throw CCE if necessary
069 boolean empty = effectiveRange.isEmpty()
070 || Range.compareOrThrow(
071 range.lowerBound.leastValueAbove(domain),
072 range.upperBound.greatestValueBelow(domain)) > 0;
073
074 return empty
075 ? new EmptyContiguousSet<C>(domain)
076 : new RegularContiguousSet<C>(effectiveRange, domain);
077 }
078
079 final DiscreteDomain<C> domain;
080
081 ContiguousSet(DiscreteDomain<C> domain) {
082 super(Ordering.natural());
083 this.domain = domain;
084 }
085
086
087 @Override
088 public ContiguousSet<C> headSet(C toElement) {
089 return headSetImpl(checkNotNull(toElement), false);
090 }
091
092 /**
093 * @since 12.0
094 */
095
096 @Override
097 @GwtIncompatible("NavigableSet")
098 public ContiguousSet<C> headSet(C toElement, boolean inclusive) {
099 return headSetImpl(checkNotNull(toElement), inclusive);
100 }
101
102
103 @Override
104 public ContiguousSet<C> subSet(C fromElement, C toElement) {
105 checkNotNull(fromElement);
106 checkNotNull(toElement);
107 checkArgument(comparator().compare(fromElement, toElement) <= 0);
108 return subSetImpl(fromElement, true, toElement, false);
109 }
110
111 /**
112 * @since 12.0
113 */
114
115 @Override
116 @GwtIncompatible("NavigableSet")
117 public ContiguousSet<C> subSet(C fromElement, boolean fromInclusive, C toElement,
118 boolean toInclusive) {
119 checkNotNull(fromElement);
120 checkNotNull(toElement);
121 checkArgument(comparator().compare(fromElement, toElement) <= 0);
122 return subSetImpl(fromElement, fromInclusive, toElement, toInclusive);
123 }
124
125
126 @Override
127 public ContiguousSet<C> tailSet(C fromElement) {
128 return tailSetImpl(checkNotNull(fromElement), true);
129 }
130
131 /**
132 * @since 12.0
133 */
134
135 @Override
136 @GwtIncompatible("NavigableSet")
137 public ContiguousSet<C> tailSet(C fromElement, boolean inclusive) {
138 return tailSetImpl(checkNotNull(fromElement), inclusive);
139 }
140
141 /*
142 * These methods perform most headSet, subSet, and tailSet logic, besides parameter validation.
143 */
144 /*@Override*/ @Override
145 abstract ContiguousSet<C> headSetImpl(C toElement, boolean inclusive);
146
147 /*@Override*/ @Override
148 abstract ContiguousSet<C> subSetImpl(C fromElement, boolean fromInclusive,
149 C toElement, boolean toInclusive);
150
151 /*@Override*/ @Override
152 abstract ContiguousSet<C> tailSetImpl(C fromElement, boolean inclusive);
153
154 /**
155 * Returns the set of values that are contained in both this set and the other.
156 *
157 * <p>This method should always be used instead of
158 * {@link Sets#intersection} for {@link ContiguousSet} instances.
159 */
160 public abstract ContiguousSet<C> intersection(ContiguousSet<C> other);
161
162 /**
163 * Returns a range, closed on both ends, whose endpoints are the minimum and maximum values
164 * contained in this set. This is equivalent to {@code range(CLOSED, CLOSED)}.
165 *
166 * @throws NoSuchElementException if this set is empty
167 */
168 public abstract Range<C> range();
169
170 /**
171 * Returns the minimal range with the given boundary types for which all values in this set are
172 * {@linkplain Range#contains(Comparable) contained} within the range.
173 *
174 * <p>Note that this method will return ranges with unbounded endpoints if {@link BoundType#OPEN}
175 * is requested for a domain minimum or maximum. For example, if {@code set} was created from the
176 * range {@code [1..Integer.MAX_VALUE]} then {@code set.range(CLOSED, OPEN)} must return
177 * {@code [1..∞)}.
178 *
179 * @throws NoSuchElementException if this set is empty
180 */
181 public abstract Range<C> range(BoundType lowerBoundType, BoundType upperBoundType);
182
183 /** Returns a short-hand representation of the contents such as {@code "[1..100]"}. */
184
185 @Override
186 public String toString() {
187 return range().toString();
188 }
189 }