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.HashMultiset} 101 * <li>{@link com.google.common.collect.LinkedHashMultiset} 102 * <li>{@link com.google.common.collect.TreeMultiset} 103 * <li>{@link com.google.common.collect.EnumMultiset} 104 * <li>{@link com.google.common.collect.ConcurrentHashMultiset} 105 * </ul> 106 * 107 * <h3>of {@link com.google.common.collect.Multimap}</h3> 108 * 109 * <ul> 110 * <li>{@link com.google.common.collect.ImmutableMultimap} 111 * <li>{@link com.google.common.collect.ImmutableListMultimap} 112 * <li>{@link com.google.common.collect.ImmutableSetMultimap} 113 * <li>{@link com.google.common.collect.ArrayListMultimap} 114 * <li>{@link com.google.common.collect.HashMultimap} 115 * <li>{@link com.google.common.collect.TreeMultimap} 116 * <li>{@link com.google.common.collect.LinkedHashMultimap} 117 * <li>{@link com.google.common.collect.LinkedListMultimap} 118 * </ul> 119 * 120 * <h3>of {@link com.google.common.collect.Table}</h3> 121 * 122 * <ul> 123 * <li>{@link com.google.common.collect.ImmutableTable} 124 * <li>{@link com.google.common.collect.ArrayTable} 125 * <li>{@link com.google.common.collect.HashBasedTable} 126 * <li>{@link com.google.common.collect.TreeBasedTable} 127 * </ul> 128 * 129 * <h3>of {@link com.google.common.collect.ClassToInstanceMap}</h3> 130 * 131 * <ul> 132 * <li>{@link com.google.common.collect.ImmutableClassToInstanceMap} 133 * <li>{@link com.google.common.collect.MutableClassToInstanceMap} 134 * </ul> 135 * 136 * <h2>Classes of static utility methods</h2> 137 * 138 * <ul> 139 * <li>{@link com.google.common.collect.Collections2} 140 * <li>{@link com.google.common.collect.Iterators} 141 * <li>{@link com.google.common.collect.Iterables} 142 * <li>{@link com.google.common.collect.Lists} 143 * <li>{@link com.google.common.collect.Maps} 144 * <li>{@link com.google.common.collect.Queues} 145 * <li>{@link com.google.common.collect.Sets} 146 * <li>{@link com.google.common.collect.Multisets} 147 * <li>{@link com.google.common.collect.Multimaps} 148 * <li>{@link com.google.common.collect.Tables} 149 * <li>{@link com.google.common.collect.ObjectArrays} 150 * </ul> 151 * 152 * <h2>Comparison</h2> 153 * 154 * <ul> 155 * <li>{@link com.google.common.collect.Ordering} 156 * <li>{@link com.google.common.collect.ComparisonChain} 157 * </ul> 158 * 159 * <h2>Abstract implementations</h2> 160 * 161 * <ul> 162 * <li>{@link com.google.common.collect.AbstractIterator} 163 * <li>{@link com.google.common.collect.AbstractSequentialIterator} 164 * <li>{@link com.google.common.collect.ImmutableCollection} 165 * <li>{@link com.google.common.collect.UnmodifiableIterator} 166 * <li>{@link com.google.common.collect.UnmodifiableListIterator} 167 * </ul> 168 * 169 * <h2>Ranges</h2> 170 * 171 * <ul> 172 * <li>{@link com.google.common.collect.Range} 173 * <li>{@link com.google.common.collect.RangeMap} 174 * <li>{@link com.google.common.collect.DiscreteDomain} 175 * <li>{@link com.google.common.collect.ContiguousSet} 176 * </ul> 177 * 178 * <h2>Other</h2> 179 * 180 * <ul> 181 * <li>{@link com.google.common.collect.Interner}, {@link com.google.common.collect.Interners} 182 * <li>{@link com.google.common.collect.MapDifference}, {@link 183 * com.google.common.collect.SortedMapDifference} 184 * <li>{@link com.google.common.collect.MinMaxPriorityQueue} 185 * <li>{@link com.google.common.collect.PeekingIterator} 186 * </ul> 187 * 188 * <h2>Forwarding collections</h2> 189 * 190 * <ul> 191 * <li>{@link com.google.common.collect.ForwardingCollection} 192 * <li>{@link com.google.common.collect.ForwardingConcurrentMap} 193 * <li>{@link com.google.common.collect.ForwardingIterator} 194 * <li>{@link com.google.common.collect.ForwardingList} 195 * <li>{@link com.google.common.collect.ForwardingListIterator} 196 * <li>{@link com.google.common.collect.ForwardingListMultimap} 197 * <li>{@link com.google.common.collect.ForwardingMap} 198 * <li>{@link com.google.common.collect.ForwardingMapEntry} 199 * <li>{@link com.google.common.collect.ForwardingMultimap} 200 * <li>{@link com.google.common.collect.ForwardingMultiset} 201 * <li>{@link com.google.common.collect.ForwardingNavigableMap} 202 * <li>{@link com.google.common.collect.ForwardingNavigableSet} 203 * <li>{@link com.google.common.collect.ForwardingObject} 204 * <li>{@link com.google.common.collect.ForwardingQueue} 205 * <li>{@link com.google.common.collect.ForwardingSet} 206 * <li>{@link com.google.common.collect.ForwardingSetMultimap} 207 * <li>{@link com.google.common.collect.ForwardingSortedMap} 208 * <li>{@link com.google.common.collect.ForwardingSortedMultiset} 209 * <li>{@link com.google.common.collect.ForwardingSortedSet} 210 * <li>{@link com.google.common.collect.ForwardingSortedSetMultimap} 211 * <li>{@link com.google.common.collect.ForwardingTable} 212 * </ul> 213 */ 214 @CheckReturnValue 215 @ParametersAreNonnullByDefault 216 package com.google.common.collect; 217 218 import com.google.errorprone.annotations.CheckReturnValue; 219 import javax.annotation.ParametersAreNonnullByDefault; 220