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 017package com.google.common.collect; 018 019import com.google.common.annotations.GwtCompatible; 020import java.util.Collection; 021import java.util.Comparator; 022import java.util.Iterator; 023import java.util.NavigableSet; 024import java.util.Set; 025 026/** 027 * A {@link Multiset} which maintains the ordering of its elements, according to either their 028 * natural order or an explicit {@link Comparator}. This order is reflected when iterating over the 029 * sorted multiset, either directly, or through its {@code elementSet} or {@code entrySet} views. In 030 * all cases, this implementation uses {@link Comparable#compareTo} or {@link Comparator#compare} 031 * instead of {@link Object#equals} to determine equivalence of instances. 032 * 033 * <p><b>Warning:</b> The comparison must be <i>consistent with equals</i> as explained by the 034 * {@link Comparable} class specification. Otherwise, the resulting multiset will violate the {@link 035 * Collection} contract, which it is specified in terms of {@link Object#equals}. 036 * 037 * <p>See the Guava User Guide article on <a href= 038 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#multiset"> {@code 039 * Multiset}</a>. 040 * 041 * @author Louis Wasserman 042 * @since 11.0 043 */ 044@GwtCompatible(emulated = true) 045public interface SortedMultiset<E> extends SortedMultisetBridge<E>, SortedIterable<E> { 046 /** 047 * Returns the comparator that orders this multiset, or {@link Ordering#natural()} if the natural 048 * ordering of the elements is used. 049 */ 050 @Override 051 Comparator<? super E> comparator(); 052 053 /** 054 * Returns the entry of the first element in this multiset, or {@code null} if this multiset is 055 * empty. 056 */ 057 Entry<E> firstEntry(); 058 059 /** 060 * Returns the entry of the last element in this multiset, or {@code null} if this multiset is 061 * empty. 062 */ 063 Entry<E> lastEntry(); 064 065 /** 066 * Returns and removes the entry associated with the lowest element in this multiset, or returns 067 * {@code null} if this multiset is empty. 068 */ 069 Entry<E> pollFirstEntry(); 070 071 /** 072 * Returns and removes the entry associated with the greatest element in this multiset, or returns 073 * {@code null} if this multiset is empty. 074 */ 075 Entry<E> pollLastEntry(); 076 077 /** 078 * Returns a {@link NavigableSet} view of the distinct elements in this multiset. 079 * 080 * @since 14.0 (present with return type {@code SortedSet} since 11.0) 081 */ 082 @Override 083 NavigableSet<E> elementSet(); 084 085 /** 086 * {@inheritDoc} 087 * 088 * <p>The {@code entrySet}'s iterator returns entries in ascending element order according to the 089 * this multiset's comparator. 090 */ 091 @Override 092 Set<Entry<E>> entrySet(); 093 094 /** 095 * {@inheritDoc} 096 * 097 * <p>The iterator returns the elements in ascending order according to this multiset's 098 * comparator. 099 */ 100 @Override 101 Iterator<E> iterator(); 102 103 /** 104 * Returns a descending view of this multiset. Modifications made to either map will be reflected 105 * in the other. 106 */ 107 SortedMultiset<E> descendingMultiset(); 108 109 /** 110 * Returns a view of this multiset restricted to the elements less than {@code upperBound}, 111 * optionally including {@code upperBound} itself. The returned multiset is a view of this 112 * multiset, so changes to one will be reflected in the other. The returned multiset supports all 113 * operations that this multiset supports. 114 * 115 * <p>The returned multiset will throw an {@link IllegalArgumentException} on attempts to add 116 * elements outside its range. 117 */ 118 SortedMultiset<E> headMultiset(E upperBound, BoundType boundType); 119 120 /** 121 * Returns a view of this multiset restricted to the range between {@code lowerBound} and {@code 122 * upperBound}. The returned multiset is a view of this multiset, so changes to one will be 123 * reflected in the other. The returned multiset supports all operations that this multiset 124 * supports. 125 * 126 * <p>The returned multiset will throw an {@link IllegalArgumentException} on attempts to add 127 * elements outside its range. 128 * 129 * <p>This method is equivalent to {@code tailMultiset(lowerBound, 130 * lowerBoundType).headMultiset(upperBound, upperBoundType)}. 131 */ 132 SortedMultiset<E> subMultiset( 133 E lowerBound, BoundType lowerBoundType, E upperBound, BoundType upperBoundType); 134 135 /** 136 * Returns a view of this multiset restricted to the elements greater than {@code lowerBound}, 137 * optionally including {@code lowerBound} itself. The returned multiset is a view of this 138 * multiset, so changes to one will be reflected in the other. The returned multiset supports all 139 * operations that this multiset supports. 140 * 141 * <p>The returned multiset will throw an {@link IllegalArgumentException} on attempts to add 142 * elements outside its range. 143 */ 144 SortedMultiset<E> tailMultiset(E lowerBound, BoundType boundType); 145}