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 * @author Louis Wasserman
040 * @since 11.0
041 */
042 @Beta
043 @GwtCompatible
044 public interface SortedMultiset<E> extends Multiset<E>, SortedIterable<E> {
045 /**
046 * Returns the comparator that orders this multiset, or
047 * {@link Ordering#natural()} if the natural ordering of the elements is used.
048 */
049 Comparator<? super E> comparator();
050
051 /**
052 * Returns the entry of the first element in this multiset, or {@code null} if
053 * this multiset is empty.
054 */
055 Entry<E> firstEntry();
056
057 /**
058 * Returns the entry of the last element in this multiset, or {@code null} if
059 * this multiset is empty.
060 */
061 Entry<E> lastEntry();
062
063 /**
064 * Returns and removes the entry associated with the lowest element in this
065 * multiset, or returns {@code null} if this multiset is empty.
066 */
067 Entry<E> pollFirstEntry();
068
069 /**
070 * Returns and removes the entry associated with the greatest element in this
071 * multiset, or returns {@code null} if this multiset is empty.
072 */
073 Entry<E> pollLastEntry();
074
075 /**
076 * Returns a {@link SortedSet} view of the distinct elements in this multiset.
077 */
078 @Override SortedSet<E> elementSet();
079
080 /**
081 * {@inheritDoc}
082 *
083 * <p>The iterator returns the elements in ascending order according to this
084 * multiset's comparator.
085 */
086 @Override Iterator<E> iterator();
087
088 /**
089 * Returns a descending view of this multiset. Modifications made to either
090 * map will be reflected in the other.
091 */
092 SortedMultiset<E> descendingMultiset();
093
094 /**
095 * Returns a view of this multiset restricted to the elements less than
096 * {@code upperBound}, optionally including {@code upperBound} itself. The
097 * returned multiset is a view of this multiset, so changes to one will be
098 * reflected in the other. The returned multiset supports all operations that
099 * this multiset supports.
100 *
101 * <p>The returned multiset will throw an {@link IllegalArgumentException} on
102 * attempts to add elements outside its range.
103 */
104 SortedMultiset<E> headMultiset(E upperBound, BoundType boundType);
105
106 /**
107 * Returns a view of this multiset restricted to the range between
108 * {@code lowerBound} and {@code upperBound}. The returned multiset is a view
109 * of this multiset, so changes to one will be reflected in the other. The
110 * returned multiset supports all operations that this multiset supports.
111 *
112 * <p>The returned multiset will throw an {@link IllegalArgumentException} on
113 * attempts to add elements outside its range.
114 *
115 * <p>This method is equivalent to
116 * {@code tailMultiset(lowerBound, lowerBoundType).headMultiset(upperBound,
117 * upperBoundType)}.
118 */
119 SortedMultiset<E> subMultiset(E lowerBound, BoundType lowerBoundType,
120 E upperBound, BoundType upperBoundType);
121
122 /**
123 * Returns a view of this multiset restricted to the elements greater than
124 * {@code lowerBound}, optionally including {@code lowerBound} itself. The
125 * returned multiset is a view of this multiset, so changes to one will be
126 * reflected in the other. The returned multiset supports all operations that
127 * this multiset supports.
128 *
129 * <p>The returned multiset will throw an {@link IllegalArgumentException} on
130 * attempts to add elements outside its range.
131 */
132 SortedMultiset<E> tailMultiset(E lowerBound, BoundType boundType);
133 }