    001    /*
    002     * Copyright (C) 2011 The Guava Authors
    003     *
    004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not
    005     * use this file except in compliance with the License. You may obtain a copy of
    006     * the License at
    007     *
    008     * http://www.apache.org/licenses/LICENSE-2.0
    009     *
    010     * Unless required by applicable law or agreed to in writing, software
    011     * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
    012     * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
    013     * License for the specific language governing permissions and limitations under
    014     * the License.
    015     */
    016
    017    package com.google.common.collect;
    018
    019    import com.google.common.annotations.Beta;
    020    import com.google.common.annotations.GwtCompatible;
    021
    022    import java.util.Collection;
    023    import java.util.Comparator;
    024    import java.util.Iterator;
    025    import java.util.SortedSet;
    026
    027    /**
    028     * A {@link Multiset} which maintains the ordering of its elements, according to
    029     * either their natural order or an explicit {@link Comparator}. In all cases,
    030     * this implementation uses {@link Comparable#compareTo} or
    031     * {@link Comparator#compare} instead of {@link Object#equals} to determine
    032     * equivalence of instances.
    033     *
    034     * <p><b>Warning:</b> The comparison must be <i>consistent with equals</i> as
    035     * explained by the {@link Comparable} class specification. Otherwise, the
    036     * resulting multiset will violate the {@link Collection} contract, which it is
    037     * specified in terms of {@link Object#equals}.
    038     *
    039     * <p>See the Guava User Guide article on <a href=
    040     * "http://code.google.com/p/guava-libraries/wiki/NewCollectionTypesExplained#Multiset">
    041     * {@code Multiset}</a>.
    042     *
    043     * @author Louis Wasserman
    044     * @since 11.0
    045     */
    046    @Beta
    047    @GwtCompatible
    048    public interface SortedMultiset<E> extends Multiset<E>, SortedIterable<E> {
    049      /**
    050       * Returns the comparator that orders this multiset, or
    051       * {@link Ordering#natural()} if the natural ordering of the elements is used.
    052       */
    053      Comparator<? super E> comparator();
    054
    055      /**
    056       * Returns the entry of the first element in this multiset, or {@code null} if
    057       * this multiset is empty.
    058       */
    059      Entry<E> firstEntry();
    060
    061      /**
    062       * Returns the entry of the last element in this multiset, or {@code null} if
    063       * this multiset is empty.
    064       */
    065      Entry<E> lastEntry();
    066
    067      /**
    068       * Returns and removes the entry associated with the lowest element in this
    069       * multiset, or returns {@code null} if this multiset is empty.
    070       */
    071      Entry<E> pollFirstEntry();
    072
    073      /**
    074       * Returns and removes the entry associated with the greatest element in this
    075       * multiset, or returns {@code null} if this multiset is empty.
    076       */
    077      Entry<E> pollLastEntry();
    078
    079      /**
    080       * Returns a {@link SortedSet} view of the distinct elements in this multiset.
    081       */
    082      @Override SortedSet<E> elementSet();
    083
    084      /**
    085       * {@inheritDoc}
    086       *
    087       * <p>The iterator returns the elements in ascending order according to this
    088       * multiset's comparator.
    089       */
    090      @Override Iterator<E> iterator();
    091
    092      /**
    093       * Returns a descending view of this multiset. Modifications made to either
    094       * map will be reflected in the other.
    095       */
    096      SortedMultiset<E> descendingMultiset();
    097
    098      /**
    099       * Returns a view of this multiset restricted to the elements less than
    100       * {@code upperBound}, optionally including {@code upperBound} itself. The
    101       * returned multiset is a view of this multiset, so changes to one will be
    102       * reflected in the other. The returned multiset supports all operations that
    103       * this multiset supports.
    104       *
    105       * <p>The returned multiset will throw an {@link IllegalArgumentException} on
    106       * attempts to add elements outside its range.
    107       */
    108      SortedMultiset<E> headMultiset(E upperBound, BoundType boundType);
    109
    110      /**
    111       * Returns a view of this multiset restricted to the range between
    112       * {@code lowerBound} and {@code upperBound}. The returned multiset is a view
    113       * of this multiset, so changes to one will be reflected in the other. The
    114       * returned multiset supports all operations that this multiset supports.
    115       *
    116       * <p>The returned multiset will throw an {@link IllegalArgumentException} on
    117       * attempts to add elements outside its range.
    118       *
    119       * <p>This method is equivalent to
    120       * {@code tailMultiset(lowerBound, lowerBoundType).headMultiset(upperBound,
    121       * upperBoundType)}.
    122       */
    123      SortedMultiset<E> subMultiset(E lowerBound, BoundType lowerBoundType,
    124          E upperBound, BoundType upperBoundType);
    125
    126      /**
    127       * Returns a view of this multiset restricted to the elements greater than
    128       * {@code lowerBound}, optionally including {@code lowerBound} itself. The
    129       * returned multiset is a view of this multiset, so changes to one will be
    130       * reflected in the other. The returned multiset supports all operations that
    131       * this multiset supports.
    132       *
    133       * <p>The returned multiset will throw an {@link IllegalArgumentException} on
    134       * attempts to add elements outside its range.
    135       */
    136      SortedMultiset<E> tailMultiset(E lowerBound, BoundType boundType);
    137    }