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