1 /* 2 * Copyright (C) 2007 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of 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, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * This package contains generic collection interfaces and implementations, and other utilities for 19 * working with collections. It is a part of the open-source <a 20 * href="http://github.com/google/guava">Guava</a> library. 21 * 22 * <h2>Collection Types</h2> 23 * 24 * <dl> 25 * <dt>{@link com.google.common.collect.BiMap} 26 * <dd>An extension of {@link java.util.Map} that guarantees the uniqueness of its values as well 27 * as that of its keys. This is sometimes called an "invertible map," since the restriction on 28 * values enables it to support an {@linkplain com.google.common.collect.BiMap#inverse inverse 29 * view} -- which is another instance of {@code BiMap}. 30 * <dt>{@link com.google.common.collect.Multiset} 31 * <dd>An extension of {@link java.util.Collection} that may contain duplicate values like a 32 * {@link java.util.List}, yet has order-independent equality like a {@link java.util.Set}. 33 * One typical use for a multiset is to represent a histogram. 34 * <dt>{@link com.google.common.collect.Multimap} 35 * <dd>A new type, which is similar to {@link java.util.Map}, but may contain multiple entries 36 * with the same key. Some behaviors of {@link com.google.common.collect.Multimap} are left 37 * unspecified and are provided only by the subtypes mentioned below. 38 * <dt>{@link com.google.common.collect.ListMultimap} 39 * <dd>An extension of {@link com.google.common.collect.Multimap} which permits duplicate entries, 40 * supports random access of values for a particular key, and has <i>partially order-dependent 41 * equality</i> as defined by {@link com.google.common.collect.ListMultimap#equals(Object)}. 42 * {@code ListMultimap} takes its name from the fact that the {@linkplain 43 * com.google.common.collect.ListMultimap#get collection of values} associated with a given 44 * key fulfills the {@link java.util.List} contract. 45 * <dt>{@link com.google.common.collect.SetMultimap} 46 * <dd>An extension of {@link com.google.common.collect.Multimap} which has order-independent 47 * equality and does not allow duplicate entries; that is, while a key may appear twice in a 48 * {@code SetMultimap}, each must map to a different value. {@code SetMultimap} takes its name 49 * from the fact that the {@linkplain com.google.common.collect.SetMultimap#get collection of 50 * values} associated with a given key fulfills the {@link java.util.Set} contract. 51 * <dt>{@link com.google.common.collect.SortedSetMultimap} 52 * <dd>An extension of {@link com.google.common.collect.SetMultimap} for which the {@linkplain 53 * com.google.common.collect.SortedSetMultimap#get collection values} associated with a given 54 * key is a {@link java.util.SortedSet}. 55 * <dt>{@link com.google.common.collect.Table} 56 * <dd>A new type, which is similar to {@link java.util.Map}, but which indexes its values by an 57 * ordered pair of keys, a row key and column key. 58 * <dt>{@link com.google.common.collect.ClassToInstanceMap} 59 * <dd>An extension of {@link java.util.Map} that associates a raw type with an instance of that 60 * type. 61 * </dl> 62 * 63 * <h2>Collection Implementations</h2> 64 * 65 * <h3>of {@link java.util.List}</h3> 66 * 67 * <ul> 68 * <li>{@link com.google.common.collect.ImmutableList} 69 * </ul> 70 * 71 * <h3>of {@link java.util.Set}</h3> 72 * 73 * <ul> 74 * <li>{@link com.google.common.collect.ImmutableSet} 75 * <li>{@link com.google.common.collect.ImmutableSortedSet} 76 * <li>{@link com.google.common.collect.ContiguousSet} (see {@code Range}) 77 * </ul> 78 * 79 * <h3>of {@link java.util.Map}</h3> 80 * 81 * <ul> 82 * <li>{@link com.google.common.collect.ImmutableMap} 83 * <li>{@link com.google.common.collect.ImmutableSortedMap} 84 * <li>{@link com.google.common.collect.MapMaker} 85 * </ul> 86 * 87 * <h3>of {@link com.google.common.collect.BiMap}</h3> 88 * 89 * <ul> 90 * <li>{@link com.google.common.collect.ImmutableBiMap} 91 * <li>{@link com.google.common.collect.HashBiMap} 92 * <li>{@link com.google.common.collect.EnumBiMap} 93 * <li>{@link com.google.common.collect.EnumHashBiMap} 94 * </ul> 95 * 96 * <h3>of {@link com.google.common.collect.Multiset}</h3> 97 * 98 * <ul> 99 * <li>{@link com.google.common.collect.ImmutableMultiset} 100 * <li>{@link com.google.common.collect.ImmutableSortedMultiset} 101 * <li>{@link com.google.common.collect.HashMultiset} 102 * <li>{@link com.google.common.collect.LinkedHashMultiset} 103 * <li>{@link com.google.common.collect.TreeMultiset} 104 * <li>{@link com.google.common.collect.EnumMultiset} 105 * <li>{@link com.google.common.collect.ConcurrentHashMultiset} 106 * </ul> 107 * 108 * <h3>of {@link com.google.common.collect.Multimap}</h3> 109 * 110 * <ul> 111 * <li>{@link com.google.common.collect.ImmutableMultimap} 112 * <li>{@link com.google.common.collect.ImmutableListMultimap} 113 * <li>{@link com.google.common.collect.ImmutableSetMultimap} 114 * <li>{@link com.google.common.collect.ArrayListMultimap} 115 * <li>{@link com.google.common.collect.HashMultimap} 116 * <li>{@link com.google.common.collect.TreeMultimap} 117 * <li>{@link com.google.common.collect.LinkedHashMultimap} 118 * <li>{@link com.google.common.collect.LinkedListMultimap} 119 * </ul> 120 * 121 * <h3>of {@link com.google.common.collect.Table}</h3> 122 * 123 * <ul> 124 * <li>{@link com.google.common.collect.ImmutableTable} 125 * <li>{@link com.google.common.collect.ArrayTable} 126 * <li>{@link com.google.common.collect.HashBasedTable} 127 * <li>{@link com.google.common.collect.TreeBasedTable} 128 * </ul> 129 * 130 * <h3>of {@link com.google.common.collect.ClassToInstanceMap}</h3> 131 * 132 * <ul> 133 * <li>{@link com.google.common.collect.ImmutableClassToInstanceMap} 134 * <li>{@link com.google.common.collect.MutableClassToInstanceMap} 135 * </ul> 136 * 137 * <h2>Classes of static utility methods</h2> 138 * 139 * <ul> 140 * <li>{@link com.google.common.collect.Collections2} 141 * <li>{@link com.google.common.collect.Iterators} 142 * <li>{@link com.google.common.collect.Iterables} 143 * <li>{@link com.google.common.collect.Lists} 144 * <li>{@link com.google.common.collect.Maps} 145 * <li>{@link com.google.common.collect.Queues} 146 * <li>{@link com.google.common.collect.Sets} 147 * <li>{@link com.google.common.collect.Multisets} 148 * <li>{@link com.google.common.collect.Multimaps} 149 * <li>{@link com.google.common.collect.Tables} 150 * <li>{@link com.google.common.collect.ObjectArrays} 151 * </ul> 152 * 153 * <h2>Comparison</h2> 154 * 155 * <ul> 156 * <li>{@link com.google.common.collect.Ordering} 157 * <li>{@link com.google.common.collect.ComparisonChain} 158 * </ul> 159 * 160 * <h2>Abstract implementations</h2> 161 * 162 * <ul> 163 * <li>{@link com.google.common.collect.AbstractIterator} 164 * <li>{@link com.google.common.collect.AbstractSequentialIterator} 165 * <li>{@link com.google.common.collect.ImmutableCollection} 166 * <li>{@link com.google.common.collect.UnmodifiableIterator} 167 * <li>{@link com.google.common.collect.UnmodifiableListIterator} 168 * </ul> 169 * 170 * <h2>Ranges</h2> 171 * 172 * <ul> 173 * <li>{@link com.google.common.collect.Range} 174 * <li>{@link com.google.common.collect.RangeMap} 175 * <li>{@link com.google.common.collect.DiscreteDomain} 176 * <li>{@link com.google.common.collect.ContiguousSet} 177 * </ul> 178 * 179 * <h2>Other</h2> 180 * 181 * <ul> 182 * <li>{@link com.google.common.collect.Interner}, {@link com.google.common.collect.Interners} 183 * <li>{@link com.google.common.collect.MapDifference}, {@link 184 * com.google.common.collect.SortedMapDifference} 185 * <li>{@link com.google.common.collect.MinMaxPriorityQueue} 186 * <li>{@link com.google.common.collect.PeekingIterator} 187 * </ul> 188 * 189 * <h2>Forwarding collections</h2> 190 * 191 * <ul> 192 * <li>{@link com.google.common.collect.ForwardingCollection} 193 * <li>{@link com.google.common.collect.ForwardingConcurrentMap} 194 * <li>{@link com.google.common.collect.ForwardingIterator} 195 * <li>{@link com.google.common.collect.ForwardingList} 196 * <li>{@link com.google.common.collect.ForwardingListIterator} 197 * <li>{@link com.google.common.collect.ForwardingListMultimap} 198 * <li>{@link com.google.common.collect.ForwardingMap} 199 * <li>{@link com.google.common.collect.ForwardingMapEntry} 200 * <li>{@link com.google.common.collect.ForwardingMultimap} 201 * <li>{@link com.google.common.collect.ForwardingMultiset} 202 * <li>{@link com.google.common.collect.ForwardingNavigableMap} 203 * <li>{@link com.google.common.collect.ForwardingNavigableSet} 204 * <li>{@link com.google.common.collect.ForwardingObject} 205 * <li>{@link com.google.common.collect.ForwardingQueue} 206 * <li>{@link com.google.common.collect.ForwardingSet} 207 * <li>{@link com.google.common.collect.ForwardingSetMultimap} 208 * <li>{@link com.google.common.collect.ForwardingSortedMap} 209 * <li>{@link com.google.common.collect.ForwardingSortedMultiset} 210 * <li>{@link com.google.common.collect.ForwardingSortedSet} 211 * <li>{@link com.google.common.collect.ForwardingSortedSetMultimap} 212 * <li>{@link com.google.common.collect.ForwardingTable} 213 * </ul> 214 */ 215 @CheckReturnValue 216 @ParametersAreNonnullByDefault 217 package com.google.common.collect; 218 219 import com.google.errorprone.annotations.CheckReturnValue; 220 import javax.annotation.ParametersAreNonnullByDefault; 221