1 /* 2 * Copyright (C) 2011 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not 5 * use this file except in compliance with the License. You may obtain a copy of 6 * the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 13 * License for the specific language governing permissions and limitations under 14 * the License. 15 */ 16 17 package com.google.common.collect; 18 19 import com.google.common.annotations.Beta; 20 import com.google.common.annotations.GwtCompatible; 21 22 import java.util.Collection; 23 import java.util.Comparator; 24 import java.util.Iterator; 25 import java.util.NavigableSet; 26 import java.util.Set; 27 28 /** 29 * A {@link Multiset} which maintains the ordering of its elements, according to 30 * either their natural order or an explicit {@link Comparator}. This order is 31 * reflected when iterating over the sorted multiset, either directly, or through 32 * its {@code elementSet} or {@code entrySet} views. In all cases, 33 * this implementation uses {@link Comparable#compareTo} or 34 * {@link Comparator#compare} instead of {@link Object#equals} to determine 35 * equivalence of instances. 36 * 37 * <p><b>Warning:</b> The comparison must be <i>consistent with equals</i> as 38 * explained by the {@link Comparable} class specification. Otherwise, the 39 * resulting multiset will violate the {@link Collection} contract, which it is 40 * specified in terms of {@link Object#equals}. 41 * 42 * <p>See the Guava User Guide article on <a href= 43 * "http://code.google.com/p/guava-libraries/wiki/NewCollectionTypesExplained#Multiset"> 44 * {@code Multiset}</a>. 45 * 46 * @author Louis Wasserman 47 * @since 11.0 48 */ 49 @Beta 50 @GwtCompatible(emulated = true) 51 public interface SortedMultiset<E> extends SortedMultisetBridge<E>, SortedIterable<E> { 52 /** 53 * Returns the comparator that orders this multiset, or 54 * {@link Ordering#natural()} if the natural ordering of the elements is used. 55 */ 56 Comparator<? super E> comparator(); 57 58 /** 59 * Returns the entry of the first element in this multiset, or {@code null} if 60 * this multiset is empty. 61 */ 62 Entry<E> firstEntry(); 63 64 /** 65 * Returns the entry of the last element in this multiset, or {@code null} if 66 * this multiset is empty. 67 */ 68 Entry<E> lastEntry(); 69 70 /** 71 * Returns and removes the entry associated with the lowest element in this 72 * multiset, or returns {@code null} if this multiset is empty. 73 */ 74 Entry<E> pollFirstEntry(); 75 76 /** 77 * Returns and removes the entry associated with the greatest element in this 78 * multiset, or returns {@code null} if this multiset is empty. 79 */ 80 Entry<E> pollLastEntry(); 81 82 /** 83 * Returns a {@link NavigableSet} view of the distinct elements in this multiset. 84 * 85 * @since 14.0 (present with return type {@code SortedSet} since 11.0) 86 */ 87 @Override NavigableSet<E> elementSet(); 88 89 /** 90 * {@inheritDoc} 91 * 92 * <p>The {@code entrySet}'s iterator returns entries in ascending element 93 * order according to the this multiset's comparator. 94 */ 95 @Override Set<Entry<E>> entrySet(); 96 97 /** 98 * {@inheritDoc} 99 * 100 * <p>The iterator returns the elements in ascending order according to this 101 * multiset's comparator. 102 */ 103 @Override Iterator<E> iterator(); 104 105 /** 106 * Returns a descending view of this multiset. Modifications made to either 107 * map will be reflected in the other. 108 */ 109 SortedMultiset<E> descendingMultiset(); 110 111 /** 112 * Returns a view of this multiset restricted to the elements less than 113 * {@code upperBound}, optionally including {@code upperBound} itself. The 114 * returned multiset is a view of this multiset, so changes to one will be 115 * reflected in the other. The returned multiset supports all operations that 116 * this multiset supports. 117 * 118 * <p>The returned multiset will throw an {@link IllegalArgumentException} on 119 * attempts to add elements outside its range. 120 */ 121 SortedMultiset<E> headMultiset(E upperBound, BoundType boundType); 122 123 /** 124 * Returns a view of this multiset restricted to the range between 125 * {@code lowerBound} and {@code upperBound}. The returned multiset is a view 126 * of this multiset, so changes to one will be reflected in the other. The 127 * returned multiset supports all operations that 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 * <p>This method is equivalent to 133 * {@code tailMultiset(lowerBound, lowerBoundType).headMultiset(upperBound, 134 * upperBoundType)}. 135 */ 136 SortedMultiset<E> subMultiset(E lowerBound, BoundType lowerBoundType, 137 E upperBound, BoundType upperBoundType); 138 139 /** 140 * Returns a view of this multiset restricted to the elements greater than 141 * {@code lowerBound}, optionally including {@code lowerBound} itself. The 142 * returned multiset is a view of this multiset, so changes to one will be 143 * reflected in the other. The returned multiset supports all operations that 144 * this multiset supports. 145 * 146 * <p>The returned multiset will throw an {@link IllegalArgumentException} on 147 * attempts to add elements outside its range. 148 */ 149 SortedMultiset<E> tailMultiset(E lowerBound, BoundType boundType); 150 } 151
