    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
    023    import java.util.NoSuchElementException;
    024
    025    /**
    026     * A sorted set of contiguous values in a given {@link DiscreteDomain}.
    027     *
    028     * @author Gregory Kick
    029     * @since 10.0
    030     */
    031    @Beta
    032    @GwtCompatible
    033    @SuppressWarnings("unchecked") // allow ungenerified Comparable types
    034    public abstract class ContiguousSet<C extends Comparable> extends ImmutableSortedSet<C> {
    035      final DiscreteDomain<C> domain;
    036
    037      ContiguousSet(DiscreteDomain<C> domain) {
    038        super(Ordering.natural());
    039        this.domain = domain;
    040      }
    041
    042      @Override public ContiguousSet<C> headSet(C toElement) {
    043        return headSet(checkNotNull(toElement), false);
    044      }
    045
    046      @Override ContiguousSet<C> headSet(C toElement, boolean inclusive) {
    047        return headSetImpl(checkNotNull(toElement), inclusive);
    048      }
    049
    050      @Override public ContiguousSet<C> subSet(C fromElement, C toElement) {
    051        checkNotNull(fromElement);
    052        checkNotNull(toElement);
    053        checkArgument(comparator().compare(fromElement, toElement) <= 0);
    054        return subSet(fromElement, true, toElement, false);
    055      }
    056
    057      @Override ContiguousSet<C> subSet(C fromElement, boolean fromInclusive, C toElement,
    058          boolean toInclusive) {
    059        checkNotNull(fromElement);
    060        checkNotNull(toElement);
    061        checkArgument(comparator().compare(fromElement, toElement) <= 0);
    062        return subSetImpl(fromElement, fromInclusive, toElement, toInclusive);
    063      }
    064
    065      @Override public ContiguousSet<C> tailSet(C fromElement) {
    066        return tailSet(checkNotNull(fromElement), true);
    067      }
    068
    069      @Override ContiguousSet<C> tailSet(C fromElement, boolean inclusive){
    070        return tailSetImpl(checkNotNull(fromElement), inclusive);
    071      }
    072
    073      /*
    074       * These methods perform most headSet, subSet, and tailSet logic, besides parameter validation.
    075       */
    076      /*@Override*/ abstract ContiguousSet<C> headSetImpl(C toElement, boolean inclusive);
    077
    078      /*@Override*/ abstract ContiguousSet<C> subSetImpl(C fromElement, boolean fromInclusive,
    079          C toElement, boolean toInclusive);
    080
    081      /*@Override*/ abstract ContiguousSet<C> tailSetImpl(C fromElement, boolean inclusive);
    082
    083      /**
    084       * Returns the set of values that are contained in both this set and the other.
    085       *
    086       * <p>This method should always be used instead of
    087       * {@link Sets#intersection} for {@link ContiguousSet} instances.
    088       */
    089      public abstract ContiguousSet<C> intersection(ContiguousSet<C> other);
    090
    091      /**
    092       * Returns a range, closed on both ends, whose endpoints are the minimum and maximum values
    093       * contained in this set.  This is equivalent to {@code range(CLOSED, CLOSED)}.
    094       *
    095       * @throws NoSuchElementException if this set is empty
    096       */
    097      public abstract Range<C> range();
    098
    099      /**
    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    }